# MarkerCollection

class

The collection of all [markers](module_engine_model_markercollection-Marker.md) attached to the document. It lets you [get](#function-get) markers or track them using [event-update](#event-update) event.

To create, change or remove makers use [model writers'](module_engine_model_writer-ModelWriter.md) methods: [`addMarker`](module_engine_model_writer-ModelWriter.md#function-addMarker) or [`removeMarker`](module_engine_model_writer-ModelWriter.md#function-removeMarker). Since the writer is the only proper way to change the data model it is not possible to change markers directly using this collection. All markers created by the writer will be automatically added to this collection.

By default there is one marker collection available as [model property](module_engine_model_model-Model.md#member-markers).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L40)

<a id="properties">

## Properties

<a id="member-_markers">

### `_markers: Map<string, Marker>` _(private)_

Stores [markers](module_engine_model_markercollection-Marker.md) added to the collection.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L44)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( args )` _(inherited)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/mix.ts#L57)

#### Parameters

* `args: [ ]`

<a id="function-Symbol.iterator">

### `Symbol.iterator() → IterableIterator<Marker>`

Iterable interface.

Iterates over all [markers](module_engine_model_markercollection-Marker.md) added to the collection.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L51)

#### Returns

* `IterableIterator<Marker>`

<a id="function-delegate">

### `delegate( events ) → EmitterMixinDelegateChain` _(inherited)_

Delegates selected events to another [`Emitter`](module_utils_emittermixin-Emitter.md). For instance:

```typescript
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```

then `eventX` is delegated (fired by) `emitterB` and `emitterC` along with `data`:

```typescript
emitterA.fire( 'eventX', data );
```

and `eventY` is delegated (fired by) `emitterC` along with `data`:

```typescript
emitterA.fire( 'eventY', data );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L539)

#### Parameters

* `events: Array<string>`

  Event names that will be delegated to another emitter.

#### Returns

* `EmitterMixinDelegateChain`

<a id="function-destroy">

### `destroy() → void`

Destroys marker collection and all markers inside it.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L229)

#### Returns

* `void`

<a id="function-fire">

### `fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]` _(inherited)_

Fires an event, executing all callbacks registered for it.

The first parameter passed to callbacks is an [`EventInfo`](module_utils_eventinfo-EventInfo.md) object, followed by the optional `args` provided in the `fire()` method call.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L512)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `eventOrInfo: GetNameOrEventInfo<TEvent>`

  The name of the event or `EventInfo` object if event is delegated.

* `args: TEvent[ 'args' ]`

  Additional arguments to be passed to the callbacks.

#### Returns

* `GetEventInfo<TEvent>[ 'return' ]`

  By default the method returns `undefined`. However, the return value can be changed by listeners through modification of the [`evt.return`](module_utils_eventinfo-EventInfo.md#member-return)'s property (the event info is the first param of every callback).

<a id="function-get">

### `get( markerName ) → Marker | null`

Returns [marker](module_engine_model_markercollection-Marker.md) with given `markerName`.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L74)

#### Parameters

* `markerName: string`

  Name of marker to get.

#### Returns

* `Marker | null`

  Marker with given name or `null` if such marker was not added to the collection.

<a id="function-getMarkersAtPosition">

### `getMarkersAtPosition( position ) → IterableIterator<Marker>`

Returns iterator that iterates over all markers, which ranges contain given [position](module_engine_model_position-ModelPosition.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L207)

#### Parameters

* `position: ModelPosition`

#### Returns

* `IterableIterator<Marker>`

<a id="function-getMarkersGroup">

### `getMarkersGroup( prefix ) → IterableIterator<Marker>`

Iterates over all markers that starts with given `prefix`.

```typescript
const markerFooA = markersCollection._set( 'foo:a', rangeFooA );
const markerFooB = markersCollection._set( 'foo:b', rangeFooB );
const markerBarA = markersCollection._set( 'bar:a', rangeBarA );
const markerFooBarA = markersCollection._set( 'foobar:a', rangeFooBarA );
Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L251)

#### Parameters

* `prefix: string`

#### Returns

* `IterableIterator<Marker>`

<a id="function-getMarkersIntersectingRange">

### `getMarkersIntersectingRange( range ) → Iterable<Marker>`

Returns iterator that iterates over all markers, which intersects with given [range](module_engine_model_range-ModelRange.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L218)

#### Parameters

* `range: ModelRange`

#### Returns

* `Iterable<Marker>`

<a id="function-has">

### `has( markerOrName ) → boolean`

Checks if given [marker](module_engine_model_markercollection-Marker.md) or marker name is in the collection.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L61)

#### Parameters

* `markerOrName: string | Marker`

  Name of marker or marker instance to check.

#### Returns

* `boolean`

  `true` if marker is in the collection, `false` otherwise.

<a id="function-listenTo:BASE_EMITTER">

### `listenTo( emitter, event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed when an event is fired in a specific (emitter) object.

Events can be grouped in namespaces using `:`. When namespaced event is fired, it additionally fires all callbacks for that namespace.

```typescript
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```

An event callback can [stop the event](module_utils_eventinfo-EventInfo.md#member-stop) and set the [return value](module_utils_eventinfo-EventInfo.md#member-return) of the [`fire`](#function-fire) method.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L475)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `emitter: Emitter`

  The object that fires the event.

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-off">

### `off( event, callback ) → void` _(inherited)_

Stops executing the callback on the given event. Shorthand for [`this.stopListening( this, event, callback )`](#function-stopListening:BASE_STOP).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L444)

#### Parameters

* `event: string`

  The name of the event.

* `callback: Function`

  The function to stop being called.

#### Returns

* `void`

<a id="function-on">

### `on( event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed when an event is fired.

Shorthand for [`this.listenTo( this, event, callback, options )`](#function-listenTo:BASE_EMITTER) (it makes the emitter listen on itself).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L416)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-once">

### `once( event, callback, options? ) → void` _(inherited)_

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling [`on`](#function-on) followed by [`off`](#function-off) in the callback.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L431)

#### Type parameters

* `TEvent: extends BaseEvent`

  The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md).

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-stopDelegating">

### `stopDelegating( event?, emitter? ) → void` _(inherited)_

Stops delegating events. It can be used at different levels:

* To stop delegating all events.
* To stop delegating a specific event to all emitters.
* To stop delegating a specific event to a specific emitter.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L552)

#### Parameters

* `event?: string`

  The name of the event to stop delegating. If omitted, stops it all delegations.

* `emitter?: Emitter`

  (requires `event`) The object to stop delegating a particular event to. If omitted, stops delegation of `event` to all emitters.

#### Returns

* `void`

<a id="function-stopListening:BASE_STOP">

### `stopListening( emitter?, event?, callback? ) → void` _(inherited)_

Stops listening for events. It can be used at different levels:

* To stop listening to a specific callback.
* To stop listening to a specific event.
* To stop listening to all events fired by a specific object.
* To stop listening to all events fired by all objects.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L497)

#### Parameters

* `emitter?: Emitter`

  The object to stop listening to. If omitted, stops it for all objects.

* `event?: string`

  (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it for all events from `emitter`.

* `callback?: Function`

  (Requires the `event`) The function to be removed from the call list for the given `event`.

#### Returns

* `void`

<a id="function-_refresh">

### `_refresh( markerOrName ) → void` _(internal)_

Fires an [event-update](#event-update) event for the given [marker](module_engine_model_markercollection-Marker.md) but does not change the marker. Useful to force [downcast conversion](module_engine_conversion_downcastdispatcher-DowncastDispatcher.md) for the marker.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L185)

#### Parameters

* `markerOrName: string | Marker`

  Marker or name of a marker to refresh.

#### Returns

* `void`

#### Fires

* [update](#event-update)

<a id="function-_remove">

### `_remove( markerOrName ) → boolean` _(internal)_

Removes given [marker](module_engine_model_markercollection-Marker.md) or a marker with given name from the `MarkerCollection`.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L160)

#### Parameters

* `markerOrName: string | Marker`

  Marker or name of a marker to remove.

#### Returns

* `boolean`

  `true` if marker was found and removed, `false` otherwise.

#### Fires

* [update](#event-update)

<a id="function-_set">

### `_set( markerOrName, range, managedUsingOperations, affectsData ) → Marker` _(internal)_

Creates and adds a [marker](module_engine_model_markercollection-Marker.md) to the `MarkerCollection` with given name on given [range](module_engine_model_range-ModelRange.md).

If `MarkerCollection` already had a marker with given name (or [marker](module_engine_model_markercollection-Marker.md) was passed), the marker in collection is updated and [event-update](#event-update) event is fired but only if there was a change (marker range or [`managedUsingOperations`](module_engine_model_markercollection-Marker.md#member-managedUsingOperations) flag has changed.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L96)

#### Parameters

* `markerOrName: string | Marker`

  Name of marker to set or marker instance to update.

* `range: ModelRange`

  Marker range.

* `managedUsingOperations: boolean`

  Specifies whether the marker is managed using operations.

  Defaults to `false`

* `affectsData: boolean`

  Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).

  Defaults to `false`

#### Returns

* `Marker`

  `Marker` instance which was added or updated.

#### Fires

* [update](#event-update)

<a id="function-_destroyMarker">

### `_destroyMarker( marker ) → void` _(private)_

Destroys the marker.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L262)

#### Parameters

* `marker: Marker`

#### Returns

* `void`

<a id="events">

## Events

<a id="event-update">

### `update( eventInfo, marker, oldRange, newRange, oldMarkerData )`

Fired whenever marker is added, updated or removed from `MarkerCollection`.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/model/markercollection.ts#L576)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `marker: Marker`

  Updated Marker.

* `oldRange: ModelRange | null`

  Marker range before the update. When is not defined it means that marker is just added.

* `newRange: ModelRange | null`

  Marker range after update. When is not defined it means that marker is just removed.

* `oldMarkerData: MarkerData`

  Data of the marker before the change.

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)