Control

Main controller class for managing annotations. It manages rendering and editing of annotations.

Extends

EventEmitter<FeatureEvents>

Constructors

Constructor

new Control(ogma, options): Control;

Parameters

ogma

Ogma

options

Partial<ControllerOptions> = {}

Returns

Control

Properties

prefixed

static prefixed: string | boolean;

Methods

add()

add(annotation): this;

Add an annotation to the controller

Parameters

annotation

The annotation to add

Annotation | AnnotationCollection

Returns

this

addListener()

addListener<T>(
   event, 
   fn, 
   context?): this;

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

cancelDrawing()

cancelDrawing(): Control;

Cancel the current drawing operation

Returns

Control

this for chaining

canRedo()

canRedo(): boolean;

Check if there are changes to redo

Returns

boolean

true if redo is possible

canUndo()

canUndo(): boolean;

Check if there are changes to undo

Returns

boolean

true if undo is possible

clearHistory()

clearHistory(): void;

Clear the undo/redo history

Returns

void

destroy()

destroy(): void;

Destroy the controller and its elements

Returns

void

disableEraseMode()

disableEraseMode(): this;

Turn erase mode off. No-op if it isn't active.

Returns

this

editFeature()

editFeature(id): this;

(Re-)apply id's handler attachment (drag/resize/text-edit) to match isEditable right now, instead of waiting for a deselect/reselect - this is the same call a selection change makes internally. Call it directly after changing whatever external state your isEditable predicate depends on (e.g. a locked flag kept outside the annotation - see the lock-toolbar-item.ts example): closes any open text editor and detaches the handler if id just became non-editable, or attaches it if id is selected and just became editable again.

Parameters

id

Id

Returns

this

emit()

emit<T>(event, ...args): boolean;

Calls each of the listeners registered for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

args

...ArgumentMap<FeatureEvents>[Extract<T, keyof FeatureEvents>]

Returns

boolean

enableArrowDrawing()

enableArrowDrawing(style?): this;

Enable arrow drawing mode - the recommended way to add arrows.

Call this method when the user clicks an "Add Arrow" button. The control will:

Wait for the next mousedown event
Create an arrow at that position with the specified style
Start the interactive drawing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startArrow() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<ArrowStyles | undefined>

Arrow style options

Returns

this

this for chaining

Example

addArrowButton.addEventListener('click', () => {
  control.enableArrowDrawing({ strokeColor: '#3A03CF', strokeWidth: 2 });
});

See

startArrow for low-level programmatic control

enableBoxDrawing()

enableBoxDrawing(style?): this;

Enable box drawing mode - the recommended way to add boxes.

Call this method when the user clicks an "Add Box" button. The control will:

Wait for the next mousedown event
Create a box at that position with the specified style
Start the interactive drawing process (drag to size)
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startBox() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<BoxStyle | undefined>

Box style options

Returns

this

this for chaining

Example

addBoxButton.addEventListener('click', () => {
  control.enableBoxDrawing({ background: '#EDE6FF', borderRadius: 8 });
});

See

startBox for low-level programmatic control

enableCommentDrawing()

enableCommentDrawing(options): this;

Enable comment drawing mode - the recommended way to add comments.

Call this method when the user clicks an "Add Comment" button. The control will:

Wait for the next mousedown event
Create a comment with an arrow pointing to that position
Smart positioning: automatically finds the best placement for the comment box
Start the interactive editing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startComment() if you need to implement custom mouse handling or positioning logic.

Parameters

options

Drawing options including offsets and styles

arrowStyle?

Partial<ArrowProperties>

Style options for the arrow

commentStyle?

Partial<CommentProps>

Style options for the comment box

offsetX?

number

Manual X offset for comment placement (overrides smart positioning)

offsetY?

number

Manual Y offset for comment placement (overrides smart positioning)

Returns

this

this for chaining

Example

addCommentButton.addEventListener('click', () => {
  control.enableCommentDrawing({
    commentStyle: { color: '#3A03CF', background: '#EDE6FF' },
    arrowStyle: { strokeColor: '#3A03CF', head: 'halo-dot' }
  });
});

See

startComment for low-level programmatic control

enableEraseMode()

enableEraseMode(): this;

Enable erase mode: every click on an annotation deletes it immediately. Stays armed across multiple clicks until disableEraseMode() is called, or another drawing tool is enabled / cancelDrawing() is called.

Returns

this

this for chaining

See

disableEraseMode to turn erase mode off

enablePlacement()

enablePlacement(annotation): this;

Place a pre-created annotation by moving it with the cursor. The annotation follows the mouse until the user clicks to place it. Press Escape to cancel.

Parameters

annotation

The text or box annotation to place

Box | Text

Returns

this

this for chaining

enablePolygonDrawing()

enablePolygonDrawing(style?): this;

Enable polygon drawing mode - the recommended way to add polygons.

Call this method when the user clicks an "Add Polygon" button. The control will:

Wait for the next mousedown event
Create a polygon starting at that position with the specified style
Start the interactive drawing process (click points to draw shape)
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startPolygon() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<PolygonStyle | undefined>

Polygon style options

Returns

this

this for chaining

Example

addPolygonButton.addEventListener('click', () => {
  control.enablePolygonDrawing({ strokeColor: '#3A03CF', background: 'rgba(58, 3, 207, 0.15)' });
});

See

startPolygon for low-level programmatic control

enableStickyNoteDrawing()

enableStickyNoteDrawing(style?): this;

Enable sticky note drawing mode - drops a plain, resizable text box (empty content, "Quick note…" ghost placeholder, no connector arrow) like a Miro sticky note, unlike enableCommentDrawing. It's a regular text annotation, so it's placed the same interactive way as enableBoxDrawing/enableTextDrawing: click for a default-size square, or drag to size it - either way it keeps the usual corner/edge drag handles to resize it afterward.

Call this method when the user clicks an "Add sticky note" button. The control will:

Wait for the next mousedown event
Create the note at that position and start the interactive corner-drag, already selected
On release: a plain click (no drag) gets a default square size, a drag gets sized to match instead - either way it drops straight into editing (the placeholder is just ghost text, so typing immediately replaces it)
Clean up automatically when done

Parameters

style?

Partial<TextStyle | undefined>

Sticky note style options (merged over the sticky note defaults)

Returns

this

this for chaining

Example

addStickyNoteButton.addEventListener('click', () => {
  control.enableStickyNoteDrawing({ background: '#FFEB99' });
});

See

startStickyNote for low-level programmatic control

enableTextDrawing()

enableTextDrawing(style?): this;

Enable text drawing mode - the recommended way to add text annotations.

Call this method when the user clicks an "Add Text" button. The control will:

Wait for the next mousedown event
Create a text box at that position with the specified style
Start the interactive drawing/editing process
Clean up automatically when done

This is the recommended API for 99% of use cases. Only use startText() if you need to implement custom mouse handling or positioning logic.

Parameters

style?

Partial<TextStyle | undefined>

Text style options

Returns

this

this for chaining

Example

addTextButton.addEventListener('click', () => {
  control.enableTextDrawing({ color: '#3A03CF', fontSize: 24 });
});

See

startText for low-level programmatic control

eventNames()

eventNames(): keyof FeatureEvents[];

Return an array listing the events for which the emitter has registered listeners.

Returns

keyof FeatureEvents[]

getAnnotation()

getAnnotation<T>(id): T | undefined;

Get a specific annotation by id

Type Parameters

T

T = Annotation

Parameters

id

Id

The id of the annotation to retrieve

Returns

T | undefined

The annotation with the given id, or undefined if not found

getAnnotations()

getAnnotations(): AnnotationCollection;

Get all annotations in the controller

Returns

AnnotationCollection

A FeatureCollection containing all annotations

getOgma()

getOgma(): Ogma;

The underlying Ogma instance this controller was created with. Needed by UI built on top of Control's public API (e.g. TextAnnotationToolbar) that must mount its own ogma.layers.addOverlay(...) layer rather than going through a renderer/handler internal to Control.

Returns

Ogma

getRotation()

getRotation(): number;

Current global annotation-rotation angle (radians) - see TextStyle/Handles' counterRotation. Needed alongside getZoom() by TextAnnotationToolbar to anchor its pill above a (possibly rotated) Text box's world-space bounds.

Returns

number

getSelected()

getSelected(): Annotation | null;

Get the first selected annotation (for backwards compatibility)

Returns

Annotation | null

The currently selected annotation, or null if none selected

getSelectedAnnotations()

getSelectedAnnotations(): AnnotationCollection;

Get the currently selected annotations as a collection

Returns

AnnotationCollection

A FeatureCollection of selected annotations

getZoom()

getZoom(): number;

Current zoom level - needed by TextAnnotationToolbar to convert a fixedSize Text annotation's screen-pixel dimensions back to graph units for its anchor-point math (same conversion Handles does).

Returns

number

isAnnotationEditable()

isAnnotationEditable(id): boolean;

Can id be dragged/resized/restyled/text-edited/deleted/re-linked right now, per the isEditable option? false for an unknown id.

Parameters

id

Id

Returns

boolean

isAnnotationVisible()

isAnnotationVisible(id): boolean;

Is id rendered and hit-testable right now, per the isVisible option? false for an unknown id.

Parameters

id

Id

Returns

boolean

isDrawing()

isDrawing(): boolean;

Returns

boolean

isEraseModeActive()

isEraseModeActive(): boolean;

Whether erase mode is currently active.

Returns

boolean

link()

Call Signature

link(
   arrowId, 
   targetNode, 
   side): this;

Attach an arrow to a node at the specified side

Parameters

arrowId

Id

targetNode

Node$1

side

Side

Returns

this

Call Signature

link(
   arrowId, 
   target, 
   side): this;

Attach an arrow to an annotation at the specified side

Parameters

Returns

this

listenerCount()

listenerCount(event): number;

Return the number of listeners listening to a given event.

Parameters

event

keyof FeatureEvents

Returns

number

listeners()

listeners<T>(event): (...args) => void[];

Return the listeners registered for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

Returns

(...args) => void[]

off()

off<T>(
   event, 
   fn?, 
   context?, 
   once?): this;

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn?

(...args) => void

context?

any

once?

boolean

Returns

this

on()

on<T>(
   event, 
   fn, 
   context?): this;

Add a listener for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

once()

once<T>(
   event, 
   fn, 
   context?): this;

Add a one-time listener for a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn

(...args) => void

context?

any

Returns

this

redo()

redo(): boolean;

Redo the last undone change

Returns

boolean

true if redo was successful, false if no changes to redo

remove()

remove(annotation): this;

Remove an annotation or an array of annotations from the controller

Parameters

annotation

The annotation(s) to remove

Annotation | AnnotationCollection

Returns

this

removeAllListeners()

removeAllListeners(event?): this;

Remove all listeners, or those of the specified event.

Parameters

event?

keyof FeatureEvents

Returns

this

removeListener()

removeListener<T>(
   event, 
   fn?, 
   context?, 
   once?): this;

Remove the listeners of a given event.

Type Parameters

T

T extends keyof FeatureEvents

Parameters

event

T

fn?

(...args) => void

context?

any

once?

boolean

Returns

this

select()

select(annotations): this;

Select one or more annotations by id

Parameters

annotations

The id(s) of the annotation(s) to select

Id | Id[]

Returns

this

this for chaining

setOptions()

setOptions(options): object;

Set the options for the controller

Parameters

options

Partial<ControllerOptions> = {}

new Options

Returns

object

the updated options

authorStyle?

optional authorStyle: Partial<AuthorLineStyle>;

detectMargin

detectMargin: number;

editButtonIcon

editButtonIcon: string;

isEditable()

isEditable: (annotation) => boolean;

Parameters

annotation

Annotation

Returns

boolean

isVisible()

isVisible: (annotation) => boolean;

Parameters

annotation

Annotation

Returns

boolean

magnetHandleRadius

magnetHandleRadius: number;

magnetRadius

magnetRadius: number;

maxArrowHeight

maxArrowHeight: number;

minArrowHeight

minArrowHeight: number;

minReadableFontSize

minReadableFontSize: number;

sendButtonIcon

sendButtonIcon: string;

showEditButton

showEditButton: boolean;

showSendButton

showSendButton: boolean;

textPlaceholder

textPlaceholder: string;

setScale()

setScale(
   id, 
   scale, 
   ox, 
   oy): this;

Scale an annotation by a given factor around an origin point

Parameters

id

Id

The id of the annotation to scale

scale

number

The scale factor

ox

number

Origin x coordinate

oy

number

Origin y coordinate

Returns

this

this for chaining

startArrow()

startArrow(
   x, 
   y, 
   arrow?): Control;

Advanced API: Programmatically start drawing an arrow at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the arrow object yourself.

For most use cases, use enableArrowDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the arrow start

y

number

Y coordinate for the arrow start

arrow?

Arrow

The arrow annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const arrow = createArrow(x, y, x, y, { strokeColor: '#3A03CF' });
  control.startArrow(x, y, arrow);
});

See

enableArrowDrawing for the recommended high-level API

startBox()

startBox(
   x, 
   y, 
   box?): Control;

Advanced API: Programmatically start drawing a box at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the box object yourself.

For most use cases, use enableBoxDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the box origin

y

number

Y coordinate for the box origin

box?

Box

The box annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const box = createBox(x, y, 100, 50, { background: '#EDE6FF' });
  control.startBox(x, y, box);
});

See

enableBoxDrawing for the recommended high-level API

startComment()

startComment(
   x, 
   y, 
   comment, 
   options?): this;

Advanced API: Programmatically start drawing a comment at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and create the comment object yourself.

For most use cases, use enableCommentDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate to start drawing

y

number

Y coordinate to start drawing

comment

Comment

The comment annotation to add

options?

Drawing options including offsets and styles

arrowStyle?

Partial<ArrowProperties>

commentStyle?

Partial<CommentProps>

offsetX?

number

offsetY?

number

Returns

this

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const comment = createComment(x, y, 'My comment', { color: '#3A03CF' });
  control.startComment(x, y, comment);
});

See

enableCommentDrawing for the recommended high-level API

startPolygon()

startPolygon(
   x, 
   y, 
   polygon): this;

Advanced API: Programmatically start drawing a polygon at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and create the polygon object yourself.

For most use cases, use enablePolygonDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate to start drawing

y

number

Y coordinate to start drawing

polygon

Polygon

The polygon annotation to add

Returns

this

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const polygon = createPolygon([[[x, y]]], { strokeColor: '#3A03CF' });
  control.startPolygon(x, y, polygon);
});

See

enablePolygonDrawing for the recommended high-level API

startStickyNote()

startStickyNote(
   x, 
   y, 
   style?): this;

Advanced API: Programmatically start drawing a sticky note at specific coordinates - same interactive corner-drag as startBox. You must handle mouse events yourself (or immediately release/complete it via the same events enableStickyNoteDrawing would).

For most use cases, use enableStickyNoteDrawing() instead.

Parameters

x

number

X coordinate for the note's top-left corner

y

number

Y coordinate for the note's top-left corner

style?

Partial<TextStyle | undefined>

Sticky note style options

Returns

this

this for chaining

See

enableStickyNoteDrawing for the recommended high-level API

startText()

startText(
   x, 
   y, 
   text?): Control;

Advanced API: Programmatically start drawing a text annotation at specific coordinates.

This is a low-level method that gives you full control over the drawing process. You must handle mouse events and optionally create the text object yourself.

For most use cases, use enableTextDrawing() instead - it handles all mouse events and annotation creation automatically.

Use this method only when you need:

Custom mouse event handling (e.g., custom cursors, right-click menus)
Programmatic placement without user interaction
Integration with custom UI frameworks

Parameters

x

number

X coordinate for the text

y

number

Y coordinate for the text

text?

Text

The text annotation to add (optional, will be created if not provided)

Returns

Control

this for chaining

Example

// Custom cursor example
ogma.setOptions({ cursor: { default: 'crosshair' } });
ogma.events.once('mousedown', (evt) => {
  const { x, y } = ogma.view.screenToGraphCoordinates(evt);
  const text = createText(x, y, 0, 0, 'Hello', { color: '#3A03CF' });
  control.startText(x, y, text);
});

See

enableTextDrawing for the recommended high-level API

toggleComment()

toggleComment(id): this;

Toggle a comment between collapsed and expanded mode

Parameters

id

Id

The id of the comment to toggle

Returns

this

this for chaining

undo()

undo(): boolean;

Undo the last change

Returns

boolean

true if undo was successful, false if no changes to undo

unselect()

unselect(annotations?): this;

Unselect one or more annotations, or all if no ids provided

Parameters

annotations?

The id(s) of the annotation(s) to unselect, or undefined to unselect all

Id | Id[]

Returns

this

this for chaining

update()

update<A>(annotation): this;

Update an annotation with partial updates

This method allows you to update any properties of an annotation, including geometry, properties, and style. Updates are merged with existing data.

Type Parameters

A

A extends Annotation

Parameters

annotation

DeepPartial<A> & object

Partial annotation object with id and properties to update

Returns

this

this for chaining

Example

// Update arrow geometry
controller.update({
  id: arrowId,
  geometry: {
    type: 'LineString',
    coordinates: [[0, 0], [200, 200]]
  }
});

// Update text content and position
controller.update({
  id: textId,
  geometry: {
    type: 'Point',
    coordinates: [100, 100]
  },
  properties: {
    content: 'Updated text'
  }
});

// Update style only (prefer updateStyle for style-only updates)
controller.update({
  id: boxId,
  properties: {
    style: {
      background: '#ff0000'
    }
  }
});

updateStyle()

updateStyle<A>(id, style): this;

Update the style of the annotation with the given id

Type Parameters

A

A extends Annotation

Parameters

id

Id

The id of the annotation to update

style

A["properties"]["style"]

The new style

Returns

this

Events

Control ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

ogma ​

options ​

Returns ​

Properties ​

prefixed ​

Methods ​

add() ​

Parameters ​

annotation ​

Returns ​

addListener() ​

Type Parameters ​

T ​

Parameters ​

event ​

fn ​

context? ​

Returns ​

cancelDrawing() ​

Returns ​

canRedo() ​

Returns ​

canUndo() ​

Returns ​

clearHistory() ​

Returns ​

destroy() ​

Returns ​

disableEraseMode() ​

Returns ​

editFeature() ​

Parameters ​

id ​

Returns ​

emit() ​

Type Parameters ​

T ​

Parameters ​

event ​

args ​

Returns ​

enableArrowDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

enableBoxDrawing() ​

Parameters ​

style? ​

Returns ​

Example ​

See ​

enableCommentDrawing() ​

Parameters ​

options ​

arrowStyle? ​

commentStyle? ​

offsetX? ​

offsetY? ​

Returns ​

Example ​

See ​

enableEraseMode() ​

Returns ​

See ​

enablePlacement() ​

Parameters ​

annotation ​

Returns ​

enablePolygonDrawing() ​

Parameters ​

style? ​

Returns ​

Control

Extends

Constructors

Constructor

Parameters

ogma

options

Returns

Properties

prefixed

Methods

add()

Parameters

annotation

Returns

addListener()

Type Parameters

T

Parameters

event

fn

context?

Returns

cancelDrawing()

Returns

canRedo()

Returns

canUndo()

Returns

clearHistory()

Returns

destroy()

Returns

disableEraseMode()

Returns

editFeature()

Parameters

id

Returns

emit()

Type Parameters

T

Parameters

event

args

Returns

enableArrowDrawing()

Parameters

style?

Returns

Example

See

enableBoxDrawing()

Parameters

style?

Returns

Example

See

enableCommentDrawing()

Parameters

options

arrowStyle?

commentStyle?

offsetX?

offsetY?

Returns

Example

See

enableEraseMode()

Returns

See

enablePlacement()

Parameters

annotation

Returns

enablePolygonDrawing()

Parameters

style?

Returns

Example