# ModelLivePosition

class

`ModelLivePosition` is a type of [Position](module_engine_model_position-ModelPosition.md) that updates itself as [document](module_engine_model_document-ModelDocument.md) is changed through operations. It may be used as a bookmark.

**Note:** Contrary to [`ModelPosition`](module_engine_model_position-ModelPosition.md), `ModelLivePosition` works only in roots that are [`ModelRootElement`](module_engine_model_rootelement-ModelRootElement.md). If [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md) is passed, error will be thrown.

**Note:** Be very careful when dealing with `ModelLivePosition`. Each `ModelLivePosition` instance bind events that might have to be unbound. Use [`detach`](#function-detach) whenever you don't need `ModelLivePosition` anymore.

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

<a id="properties">

## Properties

<a id="member-index">

### `index: number` _(readonly)_

Position [offset](module_engine_model_position-ModelPosition.md#member-offset) converted to an index in position's parent node. It is equal to the [index](module_engine_model_node-ModelNode.md#member-index) of a node after this position. If position is placed in text node, position index is equal to the index of that text node.

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

<a id="member-isAtEnd">

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

Is `true` if position is at the end of its [parent](module_engine_model_position-ModelPosition.md#member-parent), `false` otherwise.

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

<a id="member-isAtStart">

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

Is `true` if position is at the beginning of its [parent](module_engine_model_position-ModelPosition.md#member-parent), `false` otherwise.

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

<a id="member-nodeAfter">

### `nodeAfter: ModelNode | null` _(readonly)_

Node directly after this position. Returns `null` if this position is at the end of its parent, or if it is in a text node.

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

<a id="member-nodeBefore">

### `nodeBefore: ModelNode | null` _(readonly)_

Node directly before this position. Returns `null` if this position is at the start of its parent, or if it is in a text node.

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

<a id="member-offset">

### `offset: number` _(inherited)_

Offset at which this position is located in its [parent](module_engine_model_position-ModelPosition.md#member-parent). It is equal to the last item in position [path](module_engine_model_position-ModelPosition.md#member-path).

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

#### Parameters

* `newOffset: number`

<a id="member-parent">

### `parent: ModelElement | ModelDocumentFragment` _(readonly)_

Parent element of this position.

Keep in mind that `parent` value is calculated when the property is accessed. If [position path](module_engine_model_position-ModelPosition.md#member-path) leads to a non-existing element, `parent` property will throw error.

Also it is a good idea to cache `parent` property if it is used frequently in an algorithm (i.e. in a long loop).

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

<a id="member-path">

### `path: readonly Array<number>` _(readonly)_

Position of the node in the tree. **Path contains offsets, not indexes.**

Position can be placed before, after or in a [node](module_engine_model_node-ModelNode.md) if that node has [`offsetSize`](module_engine_model_node-ModelNode.md#member-offsetSize) greater than `1`. Items in position path are [starting offsets](module_engine_model_node-ModelNode.md#member-startOffset) of position ancestors, starting from direct root children, down to the position offset in it's parent.

```
ROOT
 |- P            before: [ 0 ]         after: [ 1 ]
 |- UL           before: [ 1 ]         after: [ 2 ]
    |- LI        before: [ 1, 0 ]      after: [ 1, 1 ]
    |  |- foo    before: [ 1, 0, 0 ]   after: [ 1, 0, 3 ]
    |- LI        before: [ 1, 1 ]      after: [ 1, 2 ]
       |- bar    before: [ 1, 1, 0 ]   after: [ 1, 1, 3 ]
```

`foo` and `bar` are representing [text nodes](module_engine_model_text-ModelText.md). Since text nodes has offset size greater than `1` you can place position offset between their start and end:

```
ROOT
 |- P
 |- UL
    |- LI
    |  |- f^o|o  ^ has path: [ 1, 0, 1 ]   | has path: [ 1, 0, 2 ]
    |- LI
       |- b^a|r  ^ has path: [ 1, 1, 1 ]   | has path: [ 1, 1, 2 ]
```

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

<a id="member-root">

### `root: ModelRootElement` _(readonly)_

Root of the position path.

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

<a id="member-stickiness">

### `stickiness: ModelPositionStickiness` _(inherited)_

Position stickiness. See [`ModelPositionStickiness`](module_engine_model_position-ModelPositionStickiness.md).

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

<a id="member-textNode">

### `textNode: ModelText | null` _(readonly)_

Returns [text node](module_engine_model_text-ModelText.md) instance in which this position is placed or `null` if this position is not in a text node.

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

#### Static properties

<a id="static-member-_createAfter">

### `_createAfter: ( item: ModelDocumentFragment | ModelItem, stickiness: ModelPositionStickiness ) => ModelLivePosition` _(internal)_

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

#### Related:

* ModelPosition.\_createAfter

<a id="static-member-_createAt">

### `_createAt: ( itemOrPosition: ModelDocumentFragment | ModelPosition | ModelItem, offset: ModelPositionOffset, stickiness: ModelPositionStickiness ) => ModelLivePosition` _(internal)_

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

#### Related:

* ModelPosition.\_createAt

<a id="static-member-_createBefore">

### `_createBefore: ( item: ModelDocumentFragment | ModelItem, stickiness: ModelPositionStickiness ) => ModelLivePosition` _(internal)_

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

#### Related:

* ModelPosition.\_createBefore

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( root, path, stickiness, model? )`

Creates a live position.

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

#### Parameters

* `root: ModelRootElement`

* `path: Array<number>`

* `stickiness: ModelPositionStickiness`

  Defaults to `'toNone'`

* `model?: Model`

#### Related:

* [ModelPosition](module_engine_model_position-ModelPosition.md)

<a id="function-clone">

### `clone() → this` _(inherited)_

Returns a new position that is equal to current position.

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

#### Returns

* `this`

<a id="function-compareWith">

### `compareWith( otherPosition ) → ModelPositionRelation` _(inherited)_

Checks whether this position is before or after given position.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `otherPosition: ModelPosition`

#### Returns

* `ModelPositionRelation`

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

### `detach() → void`

Unbinds all events previously bound by `ModelLivePosition`. Use it whenever you don't need `ModelLivePosition` instance anymore (i.e. when leaving scope in which it was declared or before re-assigning variable that was referring to it).

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

#### Returns

* `void`

<a id="function-findAncestor">

### `findAncestor( parentName ) → ModelElement | null` _(inherited)_

Returns the parent element of the given name. Returns null if the position is not inside the desired parent.

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

#### Parameters

* `parentName: string`

  The name of the parent element to find.

#### Returns

* `ModelElement | null`

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

### `getAncestors() → Array<ModelElement | ModelDocumentFragment>` _(inherited)_

Returns ancestors array of this position, that is this position's parent and its ancestors.

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

#### Returns

* `Array<ModelElement | ModelDocumentFragment>`

  Array with ancestors.

<a id="function-getCommonAncestor">

### `getCommonAncestor( position ) → ModelElement | ModelDocumentFragment | null` _(inherited)_

Returns an [`ModelElement`](module_engine_model_element-ModelElement.md) or [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md) which is a common ancestor of both positions. The [roots](#member-root) of these two positions must be identical.

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

#### Parameters

* `position: ModelPosition`

  The second position.

#### Returns

* `ModelElement | ModelDocumentFragment | null`

<a id="function-getCommonPath">

### `getCommonPath( position ) → Array<number>` _(inherited)_

Returns the slice of two position [paths](#member-path) which is identical. The [roots](#member-root) of these two paths must be identical.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `position: ModelPosition`

  The second position.

#### Returns

* `Array<number>`

  The common path.

<a id="function-getLastMatchingPosition">

### `getLastMatchingPosition( skip, options ) → ModelPosition` _(inherited)_

Gets the farthest position which matches the callback using [TreeWalker](module_engine_model_treewalker-ModelTreeWalker.md).

For example:

```typescript
getLastMatchingPosition( value => value.type == 'text' );
// <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>

getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } );
// <paragraph>foo[]</paragraph> -> <paragraph>[]foo</paragraph>

getLastMatchingPosition( value => false );
// Do not move the position.
```

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

#### Parameters

* `skip: ( value: ModelTreeWalkerValue ) => boolean`

  Callback function. Gets [`ModelTreeWalkerValue`](module_engine_model_treewalker-ModelTreeWalkerValue.md) and should return `true` if the value should be skipped or `false` if not.

* `options: ModelTreeWalkerOptions`

  Object with configuration options. See [`ModelTreeWalker`](module_engine_model_treewalker-ModelTreeWalker.md).

  Defaults to `{}`

#### Returns

* `ModelPosition`

  The position after the last item which matches the `skip` callback test.

<a id="function-getParentPath">

### `getParentPath() → Array<number>` _(inherited)_

Returns a path to this position's parent. Parent path is equal to position [path](module_engine_model_position-ModelPosition.md#member-path) but without the last item.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Returns

* `Array<number>`

  Path to the parent.

<a id="function-getShiftedBy">

### `getShiftedBy( shift ) → ModelPosition` _(inherited)_

Returns a new instance of `Position`, that has same [parent](#member-parent) but it's offset is shifted by `shift` value (can be a negative value).

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `shift: number`

  Offset shift. Can be a negative value.

#### Returns

* `ModelPosition`

  Shifted position.

<a id="function-getTransformedByOperation">

### `getTransformedByOperation( operation ) → ModelPosition` _(inherited)_

Returns a copy of this position that is transformed by given `operation`.

The new position's parameters are updated accordingly to the effect of the `operation`.

For example, if `n` nodes are inserted before the position, the returned position [`offset`](#member-offset) will be increased by `n`. If the position was in a merged element, it will be accordingly moved to the new element, etc.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `operation: Operation`

  Operation to transform by.

#### Returns

* `ModelPosition`

  Transformed position.

<a id="function-hasSameParentAs">

### `hasSameParentAs( position ) → boolean` _(inherited)_

Checks if two positions are in the same parent.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `position: ModelPosition`

  Position to compare with.

#### Returns

* `boolean`

  `true` if positions have the same parent, `false` otherwise.

<a id="function-is:ELEMENT">

### `is( type ) → this is ModelElement | ModelRootElement` _(inherited)_

Checks whether the object is of type [`ModelElement`](module_engine_model_element-ModelElement.md) or its subclass.

```typescript
element.is( 'element' ); // -> true
element.is( 'node' ); // -> true
element.is( 'model:element' ); // -> true
element.is( 'model:node' ); // -> true

element.is( 'view:element' ); // -> false
element.is( 'documentSelection' ); // -> false
```

Assuming that the object being checked is an element, you can also check its [name](module_engine_model_element-ModelElement.md#member-name):

```typescript
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
```

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

#### Parameters

* `type: 'element' | 'model:element'`

#### Returns

* `this is ModelElement | ModelRootElement`

<a id="function-is:TEXT">

### `is( type ) → this is ModelText` _(inherited)_

Checks whether the object is of type [`ModelText`](module_engine_model_text-ModelText.md).

```typescript
text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'model:$text' ); // -> true
text.is( 'model:node' ); // -> true

text.is( 'view:$text' ); // -> false
text.is( 'documentSelection' ); // -> false
```

**Note:** Until version 20.0.0 this method wasn't accepting `'$text'` type. The legacy `'text'` type is still accepted for backward compatibility.

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

#### Parameters

* `type: '$text' | 'model:$text'`

#### Returns

* `this is ModelText`

<a id="function-is:ROOT_ELEMENT">

### `is( type ) → this is ModelRootElement` _(inherited)_

Checks whether the object is of type [`ModelRootElement`](module_engine_model_rootelement-ModelRootElement.md).

```typescript
rootElement.is( 'rootElement' ); // -> true
rootElement.is( 'element' ); // -> true
rootElement.is( 'node' ); // -> true
rootElement.is( 'model:rootElement' ); // -> true
rootElement.is( 'model:element' ); // -> true
rootElement.is( 'model:node' ); // -> true

rootElement.is( 'view:element' ); // -> false
rootElement.is( 'documentFragment' ); // -> false
```

Assuming that the object being checked is an element, you can also check its [name](module_engine_model_element-ModelElement.md#member-name):

```typescript
rootElement.is( 'rootElement', '$root' ); // -> same as above
```

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

#### Parameters

* `type: 'rootElement' | 'model:rootElement'`

#### Returns

* `this is ModelRootElement`

<a id="function-is:LIVE_RANGE">

### `is( type ) → this is ModelLiveRange` _(inherited)_

Checks whether the object is of type [`ModelLiveRange`](module_engine_model_liverange-ModelLiveRange.md).

```typescript
liveRange.is( 'range' ); // -> true
liveRange.is( 'model:range' ); // -> true
liveRange.is( 'liveRange' ); // -> true
liveRange.is( 'model:liveRange' ); // -> true

liveRange.is( 'view:range' ); // -> false
liveRange.is( 'documentSelection' ); // -> false
```

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

#### Parameters

* `type: 'liveRange' | 'model:liveRange'`

#### Returns

* `this is ModelLiveRange`

<a id="function-is:RANGE">

### `is( type ) → this is ModelRange | ModelLiveRange` _(inherited)_

Checks whether the object is of type [`ModelRange`](module_engine_model_range-ModelRange.md) or its subclass.

```typescript
range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true

range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false
```

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

#### Parameters

* `type: 'range' | 'model:range'`

#### Returns

* `this is ModelRange | ModelLiveRange`

<a id="function-is:LIVE_POSITION">

### `is( type ) → this is ModelLivePosition` _(inherited)_

Checks whether the object is of type [`ModelLivePosition`](module_engine_model_liveposition-ModelLivePosition.md).

```typescript
livePosition.is( 'position' ); // -> true
livePosition.is( 'model:position' ); // -> true
livePosition.is( 'liveposition' ); // -> true
livePosition.is( 'model:livePosition' ); // -> true

livePosition.is( 'view:position' ); // -> false
livePosition.is( 'documentSelection' ); // -> false
```

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

#### Parameters

* `type: 'livePosition' | 'model:livePosition'`

#### Returns

* `this is ModelLivePosition`

<a id="function-is:POSITION">

### `is( type ) → this is ModelPosition | ModelLivePosition` _(inherited)_

Checks whether the object is of type [`ModelPosition`](module_engine_model_position-ModelPosition.md) or its subclass.

```typescript
position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true

position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false
```

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

#### Parameters

* `type: 'position' | 'model:position'`

#### Returns

* `this is ModelPosition | ModelLivePosition`

<a id="function-is:DOCUMENT_FRAGMENT">

### `is( type ) → this is ModelDocumentFragment` _(inherited)_

Checks whether the object is of type [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md).

```typescript
docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true

docFrag.is( 'view:documentFragment' ); // -> false
docFrag.is( 'element' ); // -> false
docFrag.is( 'node' ); // -> false
```

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

#### Parameters

* `type: 'documentFragment' | 'model:documentFragment'`

#### Returns

* `this is ModelDocumentFragment`

<a id="function-is:TEXT_PROXY">

### `is( type ) → this is ModelTextProxy` _(inherited)_

Checks whether the object is of type [`ModelTextProxy`](module_engine_model_textproxy-ModelTextProxy.md).

```typescript
textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'model:$textProxy' ); // -> true

textProxy.is( 'view:$textProxy' ); // -> false
textProxy.is( 'range' ); // -> false
```

**Note:** Until version 20.0.0 this method wasn't accepting `'$textProxy'` type. The legacy `'textProxt'` type is still accepted for backward compatibility.

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

#### Parameters

* `type: '$textProxy' | 'model:$textProxy'`

#### Returns

* `this is ModelTextProxy`

<a id="function-is:ROOT_ELEMENT_NAME">

### `is( type, name ) → boolean` _(inherited)_

Checks whether the object is of type [`ModelRootElement`](module_engine_model_rootelement-ModelRootElement.md) and has the specified `name`.

```typescript
rootElement.is( 'rootElement', '$root' );
```

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'rootElement' | 'model:rootElement'`
* `name: N`

#### Returns

* `boolean`

<a id="function-is:ELEMENT_NAME">

### `is( type, name ) → boolean` _(inherited)_

Checks whether the object is of type [`ModelElement`](module_engine_model_element-ModelElement.md) or its subclass and has the specified `name`.

```typescript
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
text.is( 'element', 'imageBlock' ); -> false
```

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'element' | 'model:element'`
* `name: N`

#### Returns

* `boolean`

<a id="function-is:MARKER">

### `is( type ) → this is Marker` _(inherited)_

Checks whether the object is of type [`Marker`](module_engine_model_markercollection-Marker.md).

```typescript
marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true

marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false
```

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

#### Parameters

* `type: 'marker' | 'model:marker'`

#### Returns

* `this is Marker`

<a id="function-is:DOCUMENT_SELECTION">

### `is( type ) → this is ModelDocumentSelection` _(inherited)_

Checks whether the object is of type [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md).

```typescript
selection.is( 'selection' ); // -> true
selection.is( 'documentSelection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'model:documentSelection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'node' ); // -> false
```

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

#### Parameters

* `type: 'documentSelection' | 'model:documentSelection'`

#### Returns

* `this is ModelDocumentSelection`

<a id="function-is:SELECTION">

### `is( type ) → this is ModelSelection | ModelDocumentSelection` _(inherited)_

Checks whether the object is of type [`ModelSelection`](module_engine_model_selection-ModelSelection.md) or [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md).

```typescript
selection.is( 'selection' ); // -> true
selection.is( 'model:selection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'range' ); // -> false
```

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

#### Parameters

* `type: 'selection' | 'model:selection'`

#### Returns

* `this is ModelSelection | ModelDocumentSelection`

<a id="function-is:NODE">

### `is( type ) → this is ModelNode | ModelText | ModelElement | ModelRootElement` _(inherited)_

Checks whether the object is of type [`ModelNode`](module_engine_model_node-ModelNode.md) or its subclass.

This method is useful when processing model objects that are of unknown type. For example, a function may return a [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md) or a [`ModelNode`](module_engine_model_node-ModelNode.md) that can be either a text node or an element. This method can be used to check what kind of object is returned.

```typescript
someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment
```

Since this method is also available on a range of view objects, you can prefix the type of the object with `model:` or `view:` to check, for example, if this is the model's or view's element:

```typescript
modelElement.is( 'model:element' ); // -> true
modelElement.is( 'view:element' ); // -> false
```

By using this method it is also possible to check a name of an element:

```typescript
imageElement.is( 'element', 'imageBlock' ); // -> true
imageElement.is( 'element', 'imageBlock' ); // -> same as above
imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
```

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

#### Parameters

* `type: 'node' | 'model:node'`

#### Returns

* `this is ModelNode | ModelText | ModelElement | ModelRootElement`

<a id="function-isAfter">

### `isAfter( otherPosition ) → boolean` _(inherited)_

Checks whether this position is after given position.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `otherPosition: ModelPosition`

  Position to compare with.

#### Returns

* `boolean`

  True if this position is after given position.

#### Related:

* [ModelPosition#isBefore](module_engine_model_position-ModelPosition.md#function-isBefore)

<a id="function-isBefore">

### `isBefore( otherPosition ) → boolean` _(inherited)_

Checks whether this position is before given position.

**Note:** watch out when using negation of the value returned by this method, because the negation will also be `true` if positions are in different roots and you might not expect this. You should probably use `a.isAfter( b ) || a.isEqual( b )` or `!a.isBefore( p ) && a.root == b.root` in most scenarios. If your condition uses multiple `isAfter` and `isBefore` checks, build them so they do not use negated values, i.e.:

```typescript
if ( a.isBefore( b ) && c.isAfter( d ) ) {
	// do A.
} else {
	// do B.
}
```

or, if you have only one if-branch:

```typescript
if ( !( a.isBefore( b ) && c.isAfter( d ) ) {
	// do B.
}
```

rather than:

```typescript
if ( !a.isBefore( b ) || && !c.isAfter( d ) ) {
	// do B.
} else {
	// do A.
}
```

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `otherPosition: ModelPosition`

  Position to compare with.

#### Returns

* `boolean`

  True if this position is before given position.

<a id="function-isEqual">

### `isEqual( otherPosition ) → boolean` _(inherited)_

Checks whether this position is equal to given position.

This method is safe to use it on non-existing positions (for example during operational transformation).

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

#### Parameters

* `otherPosition: ModelPosition`

  Position to compare with.

#### Returns

* `boolean`

  True if positions are same.

<a id="function-isTouching">

### `isTouching( otherPosition ) → boolean` _(inherited)_

Checks whether this position is touching given position. Positions touch when there are no text nodes or empty nodes in a range between them. Technically, those positions are not equal but in many cases they are very similar or even indistinguishable.

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

#### Parameters

* `otherPosition: ModelPosition`

  Position to compare with.

#### Returns

* `boolean`

  True if positions touch.

<a id="function-isValid">

### `isValid() → boolean` _(inherited)_

Checks whether the position is valid in current model tree, that is whether it points to an existing place in the model.

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

#### Returns

* `boolean`

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

### `toJSON() → unknown` _(inherited)_

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

#### Returns

* `unknown`

<a id="function-toPosition">

### `toPosition() → ModelPosition`

Creates a [position instance](module_engine_model_position-ModelPosition.md), which is equal to this live position.

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

#### Returns

* `ModelPosition`

<a id="function-_getCombined">

### `_getCombined( source, target ) → ModelPosition` _(internal)_

Returns a new position that is a combination of this position and given positions.

The combined position is a copy of this position transformed by moving a range starting at `source` position to the `target` position. It is expected that this position is inside the moved range.

Example:

```typescript
let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
let source = model.createPositionFromPath( root, [ 2, 2 ] );
let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`
```

Explanation:

We have a position `[ 2, 3, 1 ]` and move some nodes from `[ 2, 2 ]` to `[ 1, 1, 3 ]`. The original position was inside moved nodes and now should point to the new place. The moved nodes will be after positions `[ 1, 1, 3 ]`, `[ 1, 1, 4 ]`, `[ 1, 1, 5 ]`. Since our position was in the second moved node, the transformed position will be in a sub-tree of a node at `[ 1, 1, 4 ]`. Looking at original path, we took care of `[ 2, 3 ]` part of it. Now we have to add the rest of the original path to the transformed path. Finally, the transformed position will point to `[ 1, 1, 4, 1 ]`.

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

#### Parameters

* `source: ModelPosition`

  Beginning of the moved range.

* `target: ModelPosition`

  Position where the range is moved.

#### Returns

* `ModelPosition`

  Combined position.

<a id="function-_getTransformedByDeletion">

### `_getTransformedByDeletion( deletePosition, howMany ) → ModelPosition | null` _(internal)_

Returns a copy of this position that is updated by removing `howMany` nodes starting from `deletePosition`. It may happen that this position is in a removed node. If that is the case, `null` is returned instead.

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

#### Parameters

* `deletePosition: ModelPosition`

  Position before the first removed node.

* `howMany: number`

  How many nodes are removed.

#### Returns

* `ModelPosition | null`

  Transformed position or `null`.

<a id="function-_getTransformedByDetachOperation">

### `_getTransformedByDetachOperation( operation ) → ModelPosition` _(internal)_

Returns a copy of this position transformed by a detach operation.

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

#### Parameters

* `operation: DetachOperation`

#### Returns

* `ModelPosition`

<a id="function-_getTransformedByInsertOperation">

### `_getTransformedByInsertOperation( operation ) → ModelPosition` _(internal)_

Returns a copy of this position transformed by an insert operation.

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

#### Parameters

* `operation: InsertOperation`

#### Returns

* `ModelPosition`

<a id="function-_getTransformedByInsertion">

### `_getTransformedByInsertion( insertPosition, howMany ) → ModelPosition` _(internal)_

Returns a copy of this position that is updated by inserting `howMany` nodes at `insertPosition`.

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

#### Parameters

* `insertPosition: ModelPosition`

  Position where nodes are inserted.

* `howMany: number`

  How many nodes are inserted.

#### Returns

* `ModelPosition`

  Transformed position.

<a id="function-_getTransformedByMergeOperation">

### `_getTransformedByMergeOperation( operation ) → ModelPosition` _(internal)_

Returns a copy of this position transformed by merge operation.

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

#### Parameters

* `operation: MergeOperation`

#### Returns

* `ModelPosition`

<a id="function-_getTransformedByMove">

### `_getTransformedByMove( sourcePosition, targetPosition, howMany ) → ModelPosition` _(internal)_

Returns a copy of this position that is updated by moving `howMany` nodes from `sourcePosition` to `targetPosition`.

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

#### Parameters

* `sourcePosition: ModelPosition`

  Position before the first element to move.

* `targetPosition: ModelPosition`

  Position where moved elements will be inserted.

* `howMany: number`

  How many consecutive nodes to move, starting from `sourcePosition`.

#### Returns

* `ModelPosition`

  Transformed position.

<a id="function-_getTransformedByMoveOperation">

### `_getTransformedByMoveOperation( operation ) → ModelPosition` _(internal)_

Returns a copy of this position transformed by a move operation.

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

#### Parameters

* `operation: MoveOperation`

#### Returns

* `ModelPosition`

<a id="function-_getTransformedBySplitOperation">

### `_getTransformedBySplitOperation( operation ) → ModelPosition` _(internal)_

Returns a copy of this position transformed by a split operation.

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

#### Parameters

* `operation: SplitOperation`

#### Returns

* `ModelPosition`

#### Static methods

<a id="static-function-fromJSON">

### `fromJSON( json, doc ) → ModelPosition` _(inherited)_

Creates a `Position` instance from given plain object (i.e. parsed JSON string).

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

#### Parameters

* `json: any`

  Plain object to be converted to `Position`.

* `doc: ModelDocument`

  Document object that will be position owner.

#### Returns

* `ModelPosition`

  `Position` instance created using given plain object.

<a id="static-function-fromPosition">

### `fromPosition( position, stickiness? ) → ModelLivePosition` _(static)_

Creates a `ModelLivePosition` instance that is equal to position.

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

#### Parameters

* `position: ModelPosition`
* `stickiness?: ModelPositionStickiness`

#### Returns

* `ModelLivePosition`

<a id="static-function-_fromPositionInDocumentFragment">

### `_fromPositionInDocumentFragment( position, model, stickiness? ) → ModelLivePosition` _(internal)_

Creates a `ModelLivePosition` for a position rooted in a [document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md).

Document fragment does not belong to a document, so the live position is bound to the provided `model` and keeps itself in sync with every operation applied to that fragment (e.g. while editing clipboard content).

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

#### Parameters

* `position: ModelPosition`
* `model: Model`
* `stickiness?: ModelPositionStickiness`

#### Returns

* `ModelLivePosition`

<a id="events">

## Events

<a id="event-change">

### `change( eventInfo, oldPosition )`

Fired when `ModelLivePosition` instance is changed due to changes on [`ModelDocument`](module_engine_model_document-ModelDocument.md).

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `oldPosition: ModelPosition`

  Position equal to this live position before it got changed.

---

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