# MutationObserver

class

Mutation observer's role is to watch for any DOM changes inside the editor that weren't done by the editor's [`ViewRenderer`](module_engine_view_renderer-ViewRenderer.md) itself and reverting these changes.

It does this by observing all mutations in the DOM, marking related view elements as changed and calling [`render`](module_engine_view_renderer-ViewRenderer.md#function-render). Because all mutated nodes are marked as "to be rendered" and the [`render()`](module_engine_view_renderer-ViewRenderer.md#function-render) method is called, all changes are reverted in the DOM (the DOM is synced with the editor's view structure).

Note that this observer is attached by the [`EditingView`](module_engine_view_view-EditingView.md) and is available by default.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L35)

<a id="properties">

## Properties

<a id="member-document">

### `document: ViewDocument` _(readonly)_

A reference to the [`ViewDocument`](module_engine_view_document-ViewDocument.md) object.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/observer.ts#L32)

<a id="member-domConverter">

### `domConverter: ViewDomConverter` _(readonly)_

Reference to the [`domConverter`](module_engine_view_view-EditingView.md#member-domConverter).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L39)

<a id="member-isEnabled">

### `isEnabled: boolean` _(readonly)_

The state of the observer. If it is disabled, no events will be fired.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/observer.ts#L52)

<a id="member-view">

### `view: EditingView` _(readonly)_

An instance of the view controller.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/observer.ts#L27)

<a id="member-_config">

### `_config: MutationObserverInit` _(private)_

Native mutation observer config.

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

<a id="member-_domElements">

### `_domElements: Set<HTMLElement>` _(private)_

Observed DOM elements.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L49)

<a id="member-_mutationObserver">

### `_mutationObserver: MutationObserver` _(private)_

Native mutation observer.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L54)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( view )`

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L59)

#### Parameters

* `view: EditingView`

<a id="function-checkShouldIgnoreEventFromTarget">

### `checkShouldIgnoreEventFromTarget( domTarget ) → boolean` _(inherited)_

Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).

Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute. This attribute can be used inside the structures generated by [`ViewDowncastWriter#createUIElement()`](module_engine_view_downcastwriter-ViewDowncastWriter.md#function-createUIElement) to ignore events fired within a UI that should be excluded from CKEditor 5's realms.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/observer.ts#L100)

#### Parameters

* `domTarget: Node | null`

  The DOM event target to check (usually an element, sometimes a text node and potentially sometimes a document, too).

#### Returns

* `boolean`

  Whether this event should be ignored by the observer.

<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`

Disables and destroys the observer, among others removes event listeners created by the observer.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L132)

#### Returns

* `void`

<a id="function-disable">

### `disable() → void`

Disables the observer. This method is called before [rendering](module_engine_view_view-EditingView.md#function-forceRender) to prevent firing events during rendering.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L123)

#### Returns

* `void`

#### Related:

* [Observer#enable](module_engine_view_observer_observer-Observer.md#function-enable)

<a id="function-enable">

### `enable() → void`

Enables the observer. This method is called when the observer is registered to the [`EditingView`](module_engine_view_view-EditingView.md) and after [rendering](module_engine_view_view-EditingView.md#function-forceRender) (all observers are [disabled](#function-disable) before rendering).

A typical use case for disabling observers is that mutation observers need to be disabled for the rendering. However, a child class may not need to be disabled, so it can implement an empty method.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L112)

#### Returns

* `void`

#### Related:

* [Observer#disable](module_engine_view_observer_observer-Observer.md#function-disable)

<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-flush">

### `flush() → void`

Synchronously handles mutations and empties the queue.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L77)

#### Returns

* `void`

<a id="function-listenTo:DOM_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/dom/emittermixin.ts#L457)

#### 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?: CallbackOptions`

  Additional options.

#### Returns

* `void`

<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-listenTo:HTML_EMITTER">

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

Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with [`listenTo`](module_utils_emittermixin-Emitter.md#function-listenTo:BASE_EMITTER).

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

#### Type parameters

* `K: extends keyof DomEventMap`

#### Parameters

* `emitter: Window | EventTarget | Node`

  The object that fires the event.

* `event: K`

  The name of the event.

* `callback: ( this: this, ev: EventInfo, event: DomEventMap[ K ] ) => void`

  The function to be called on event.

* `options?: CallbackOptions & object`

  Additional options.

#### Returns

* `void`

<a id="function-observe">

### `observe( domElement ) → void`

Starts observing given DOM element.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L84)

#### Parameters

* `domElement: HTMLElement`

  DOM element to observe.

#### 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:DOM_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:HTML_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-stopListening:DOM_STOP">

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

Stops listening for events. It can be used at different levels: It is backwards compatible with [`listenTo`](module_utils_emittermixin-Emitter.md#function-listenTo:BASE_EMITTER).

* 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/dom/emittermixin.ts#L481)

#### Parameters

* `emitter?: Window | EventTarget | Node | 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-stopObserving">

### `stopObserving( domElement ) → void`

Stops observing given DOM element.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L95)

#### Parameters

* `domElement: HTMLElement`

#### Returns

* `void`

<a id="function-_isBogusBrMutation">

### `_isBogusBrMutation( mutation ) → boolean | null` _(private)_

Checks if mutation was generated by the browser inserting bogus br on the end of the block element. Such mutations are generated while pressing space or performing native spellchecker correction on the end of the block element in Firefox browser.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L247)

#### Parameters

* `mutation: MutationRecord`

  Native mutation object.

#### Returns

* `boolean | null`

<a id="function-_onMutations">

### `_onMutations( domMutations ) → void` _(private)_

Handles mutations. Mark view elements to sync and call render.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/observer/mutationobserver.ts#L143)

#### Parameters

* `domMutations: Array<MutationRecord>`

  Array of native mutations.

#### Returns

* `void`

---

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