# ModelSelection

class

Selection is a set of [ranges](module_engine_model_range-ModelRange.md). It has a direction specified by its [anchor](#member-anchor) and [focus](#member-focus) (it can be [forward or backward](#member-isBackward)). Additionally, selection may have its own attributes (think – whether text typed in in this selection should have those attributes – e.g. whether you type a bolded text).

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

<a id="properties">

## Properties

<a id="member-anchor">

### `anchor: ModelPosition | null` _(readonly)_

Selection anchor. Anchor is the position from which the selection was started. If a user is making a selection by dragging the mouse, the anchor is where the user pressed the mouse button (the beginning of the selection).

Anchor and [`focus`](#member-focus) define the direction of the selection, which is important when expanding/shrinking selection. The focus moves, while the anchor should remain in the same place.

Anchor is always set to the [start](module_engine_model_range-ModelRange.md#member-start) or [end](module_engine_model_range-ModelRange.md#member-end) position of the last of selection's ranges. Whether it is the `start` or `end` depends on the specified `options.backward`. See the [`setTo()`](#function-setTo) method.

May be set to `null` if there are no ranges in the selection.

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

<a id="member-focus">

### `focus: ModelPosition | null` _(readonly)_

Selection focus. Focus is the position where the selection ends. If a user is making a selection by dragging the mouse, the focus is where the mouse cursor is.

May be set to `null` if there are no ranges in the selection.

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

<a id="member-isBackward">

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

Specifies whether the selection's [`focus`](#member-focus) precedes the selection's [`anchor`](#member-anchor).

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

<a id="member-isCollapsed">

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

Whether the selection is collapsed. Selection is collapsed when there is exactly one range in it and it is collapsed.

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

<a id="member-rangeCount">

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

Returns the number of ranges in the selection.

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

<a id="member-_ranges">

### `_ranges: Array<ModelRange>` _(internal)_

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

<a id="member-_attrs">

### `_attrs: Map<string, unknown>` _(protected)_

List of attributes set on current selection.

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

<a id="member-_lastRangeBackward">

### `_lastRangeBackward: boolean` _(private)_

Specifies whether the last added range was added as a backward or forward range.

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( args )` _(internal)_

Creates a new selection instance based on the given [selectable](module_engine_model_selection-ModelSelectable.md) or creates an empty selection if no arguments were passed.

```typescript
// Creates empty selection without ranges.
const selection = writer.createSelection();

// Creates selection at the given range.
const range = writer.createRange( start, end );
const selection = writer.createSelection( range );

// Creates selection at the given ranges
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
const selection = writer.createSelection( ranges );

// Creates selection from the other selection.
// Note: It doesn't copy selection attributes.
const otherSelection = writer.createSelection();
const selection = writer.createSelection( otherSelection );

// Creates selection from the given document selection.
// Note: It doesn't copy selection attributes.
const documentSelection = model.document.selection;
const selection = writer.createSelection( documentSelection );

// Creates selection at the given position.
const position = writer.createPositionFromPath( root, path );
const selection = writer.createSelection( position );

// Creates selection at the given offset in the given element.
const paragraph = writer.createElement( 'paragraph' );
const selection = writer.createSelection( paragraph, offset );

// Creates a range inside an element which starts before the
// first child of that element and ends after the last child of that element.
const selection = writer.createSelection( paragraph, 'in' );

// Creates a range on an item which starts before the item and ends
// just after the item.
const selection = writer.createSelection( paragraph, 'on' );
```

Selection's constructor allow passing additional options (`'backward'`) as the last argument.

```typescript
// Creates backward selection.
const selection = writer.createSelection( range, { backward: true } );
```

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

#### Parameters

* `args: [ ] | [ selectable: ModelNode, placeOrOffset: ModelPlaceOrOffset, options?: object ] | [ selectable?: ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange> | null, options?: object ]`

<a id="function-containsEntireContent">

### `containsEntireContent( element ) → boolean`

Checks whether the selection contains the entire content of the given element. This means that selection must start at a position [touching](module_engine_model_position-ModelPosition.md#function-isTouching) the element's start and ends at position touching the element's end.

By default, this method will check whether the entire content of the selection's current root is selected. Useful to check if e.g. the user has just pressed `Ctrl` + `A`.

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

#### Parameters

* `element: ModelElement`

  Defaults to `...`

#### Returns

* `boolean`

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

### `getAttribute( key ) → unknown`

Gets an attribute value for given key or `undefined` if that attribute is not set on the selection.

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

#### Parameters

* `key: string`

  Key of attribute to look for.

#### Returns

* `unknown`

  Attribute value or `undefined`.

<a id="function-getAttributeKeys">

### `getAttributeKeys() → IterableIterator<string>`

Returns iterable that iterates over this selection's attribute keys.

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

#### Returns

* `IterableIterator<string>`

<a id="function-getAttributes">

### `getAttributes() → IterableIterator<[ string, unknown ]>`

Returns iterable that iterates over this selection's attributes.

Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value. This format is accepted by native `Map` object and also can be passed in `Node` constructor.

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

#### Returns

* `IterableIterator<[ string, unknown ]>`

<a id="function-getFirstPosition">

### `getFirstPosition() → ModelPosition | null`

Returns the first position in the selection. First position is the position that [is before](module_engine_model_position-ModelPosition.md#function-isBefore) any other position in the selection.

Returns `null` if there are no ranges in selection.

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

#### Returns

* `ModelPosition | null`

<a id="function-getFirstRange">

### `getFirstRange() → ModelRange | null`

Returns a copy of the first range in the selection. First range is the one which [start](module_engine_model_range-ModelRange.md#member-start) position [is before](module_engine_model_position-ModelPosition.md#function-isBefore) start position of all other ranges (not to confuse with the first range added to the selection).

Returns `null` if there are no ranges in selection.

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

#### Returns

* `ModelRange | null`

<a id="function-getLastPosition">

### `getLastPosition() → ModelPosition | null`

Returns the last position in the selection. Last position is the position that [is after](module_engine_model_position-ModelPosition.md#function-isAfter) any other position in the selection.

Returns `null` if there are no ranges in selection.

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

#### Returns

* `ModelPosition | null`

<a id="function-getLastRange">

### `getLastRange() → ModelRange | null`

Returns a copy of the last range in the selection. Last range is the one which [end](module_engine_model_range-ModelRange.md#member-end) position [is after](module_engine_model_position-ModelPosition.md#function-isAfter) end position of all other ranges (not to confuse with the range most recently added to the selection).

Returns `null` if there are no ranges in selection.

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

#### Returns

* `ModelRange | null`

<a id="function-getRanges">

### `getRanges() → IterableIterator<ModelRange>`

Returns an iterable object that iterates over copies of selection ranges.

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

#### Returns

* `IterableIterator<ModelRange>`

<a id="function-getSelectedBlocks">

### `getSelectedBlocks() → IterableIterator<ModelElement>`

Gets elements of type ["block"](module_engine_model_schema-ModelSchema.md#function-isBlock) touched by the selection.

This method's result can be used for example to apply block styling to all blocks covered by this selection.

**Note:** `getSelectedBlocks()` returns blocks that are nested in other non-block elements but will not return blocks nested in other blocks.

In this case the function will return exactly all 3 paragraphs (note: `<blockQuote>` is not a block itself):

```xml
<paragraph>[a</paragraph>
<blockQuote>
	<paragraph>b</paragraph>
</blockQuote>
<paragraph>c]d</paragraph>
```

In this case the paragraph will also be returned, despite the collapsed selection:

```xml
<paragraph>[]a</paragraph>
```

In such a scenario, however, only blocks A, B & E will be returned as blocks C & D are nested in block B:

```xml
[<blockA></blockA>
<blockB>
	<blockC></blockC>
	<blockD></blockD>
</blockB>
<blockE></blockE>]
```

If the selection is inside a block all the inner blocks (A & B) are returned:

```xml
<block>
	<blockA>[a</blockA>
	<blockB>b]</blockB>
</block>
```

**Special case**: Selection ignores first and/or last blocks if nothing (from user perspective) is selected in them.

```xml
// Selection ends and the beginning of the last block.
<paragraph>[a</paragraph>
<paragraph>b</paragraph>
<paragraph>]c</paragraph> // This block will not be returned

// Selection begins at the end of the first block.
<paragraph>a[</paragraph> // This block will not be returned
<paragraph>b</paragraph>
<paragraph>c]</paragraph>

// Selection begings at the end of the first block and ends at the beginning of the last block.
<paragraph>a[</paragraph> // This block will not be returned
<paragraph>b</paragraph>
<paragraph>]c</paragraph> // This block will not be returned
```

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

#### Returns

* `IterableIterator<ModelElement>`

<a id="function-getSelectedElement">

### `getSelectedElement() → ModelElement | null`

Returns the selected element. [Element](module_engine_model_element-ModelElement.md) is considered as selected if there is only one range in the selection, and that range contains exactly one element. Returns `null` if there is no selected element.

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

#### Returns

* `ModelElement | null`

<a id="function-hasAttribute">

### `hasAttribute( key ) → boolean`

Checks if the selection has an attribute for given key.

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

#### Parameters

* `key: string`

  Key of attribute to check.

#### Returns

* `boolean`

  `true` if attribute with given key is set on selection, `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: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: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: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: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: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: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: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: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: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: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-isEqual">

### `isEqual( otherSelection ) → boolean`

Checks whether this selection is equal to the given selection. Selections are equal if they have the same directions, the same number of ranges and all ranges from one selection equal to ranges from the another selection.

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

#### Parameters

* `otherSelection: ModelSelection | ModelDocumentSelection`

  Selection to compare with.

#### Returns

* `boolean`

  `true` if selections are equal, `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-removeAttribute">

### `removeAttribute( key ) → void`

Removes an attribute with given key from the selection.

If given attribute was set on the selection, fires the [event-change:range](#event-change:range) event with removed attribute key.

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

#### Parameters

* `key: string`

  Key of attribute to remove.

#### Returns

* `void`

#### Fires

* [change:attribute](#event-change:attribute)

<a id="function-setAttribute">

### `setAttribute( key, value ) → void`

Sets attribute on the selection. If attribute with the same key already is set, it's value is overwritten.

If the attribute value has changed, fires the [event-change:range](#event-change:range) event with the attribute key.

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

#### Parameters

* `key: string`

  Key of attribute to set.

* `value: unknown`

  Attribute value.

#### Returns

* `void`

#### Fires

* [change:attribute](#event-change:attribute)

<a id="function-setFocus">

### `setFocus( itemOrPosition, offset? ) → void`

Moves [`focus`](#member-focus) to the specified location.

The location can be specified in the same form as [writer.createPositionAt()](module_engine_model_writer-ModelWriter.md#function-createPositionAt) parameters.

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

#### Parameters

* `itemOrPosition: ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

  Offset or one of the flags. Used only when first parameter is a [model item](module_engine_model_item-ModelItem.md).

#### Returns

* `void`

#### Fires

* [change:range](#event-change:range)

<a id="function-setTo">

### `setTo( args ) → void`

Sets this selection's ranges and direction to the specified location based on the given [selectable](module_engine_model_selection-ModelSelectable.md).

```typescript
// Removes all selection's ranges.
selection.setTo( null );

// Sets selection to the given range.
const range = writer.createRange( start, end );
selection.setTo( range );

// Sets selection to given ranges.
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
selection.setTo( ranges );

// Sets selection to other selection.
// Note: It doesn't copy selection attributes.
const otherSelection = writer.createSelection();
selection.setTo( otherSelection );

// Sets selection to the given document selection.
// Note: It doesn't copy selection attributes.
const documentSelection = new ModelDocumentSelection( doc );
selection.setTo( documentSelection );

// Sets collapsed selection at the given position.
const position = writer.createPositionFromPath( root, path );
selection.setTo( position );

// Sets collapsed selection at the position of the given node and an offset.
selection.setTo( paragraph, offset );
```

Creates a range inside an [element](module_engine_model_element-ModelElement.md) which starts before the first child of

* that element and ends after the last child of that element.

```typescript
selection.setTo( paragraph, 'in' );
```

Creates a range on an [item](module_engine_model_item-ModelItem.md) which starts before the item and ends just after the item.

```typescript
selection.setTo( paragraph, 'on' );
```

`Selection#setTo()` method allows passing additional options (`backward`) as the last argument.

```typescript
// Sets backward selection.
const selection = writer.createSelection( range, { backward: true } );
```

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

#### Parameters

* `args: [ selectable: ModelNode, placeOrOffset: ModelPlaceOrOffset, options?: object ] | [ selectable?: ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange> | null, options?: object ]`

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

Converts `Selection` to plain object and returns it.

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

#### Returns

* `unknown`

  `Selection` converted to plain object.

<a id="function-_checkRange">

### `_checkRange( range ) → void` _(protected)_

Checks if given range intersects with ranges that are already in the selection. Throws an error if it does.

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

#### Parameters

* `range: ModelRange`

#### Returns

* `void`

<a id="function-_popRange">

### `_popRange() → void` _(protected)_

Removes most recently added range from the selection.

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

#### Returns

* `void`

<a id="function-_pushRange">

### `_pushRange( range ) → void` _(protected)_

Adds given range to internal [ranges array](#member-_ranges). Throws an error if given range is intersecting with any range that is already stored in this selection.

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

#### Parameters

* `range: ModelRange`

#### Returns

* `void`

<a id="function-_removeAllRanges">

### `_removeAllRanges() → void` _(protected)_

Deletes ranges from internal range array. Uses [\_popRange](#function-_popRange) to ensure proper ranges removal.

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

#### Returns

* `void`

<a id="function-_replaceAllRanges">

### `_replaceAllRanges( ranges ) → void` _(protected)_

Replaces all the ranges by the given ones. Uses [\_popRange](#function-_popRange) and [\_pushRange](#function-_pushRange) to ensure proper ranges removal and addition.

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

#### Parameters

* `ranges: Array<ModelRange>`

#### Returns

* `void`

<a id="function-_setRanges">

### `_setRanges( newRanges, isLastBackward ) → void` _(protected)_

Replaces all ranges that were added to the selection with given array of ranges. Last range of the array is treated like the last added range and is used to set [`anchor`](#member-anchor) and [`focus`](#member-focus). Accepts a flag describing in which direction the selection is made.

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

#### Parameters

* `newRanges: Iterable<ModelRange>`

  Ranges to set.

* `isLastBackward: boolean`

  Flag describing if last added range was selected forward - from start to end (`false`) or backward - from end to start (`true`).

  Defaults to `false`

#### Returns

* `void`

#### Fires

* [change:range](#event-change:range)

<a id="events">

## Events

<a id="event-change:attribute">

### `change:attribute( eventInfo, directChange = { directChange.attributeKeys, directChange.directChange } )`

Fired when selection attribute changed.

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `directChange: object`

  In case of [`ModelSelection`](module_engine_model_selection-ModelSelection.md) class it is always set to `true` which indicates that the selection change was caused by a direct use of selection's API. The [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md), however, may change because its attributes were directly changed through the [writer](module_engine_model_writer-ModelWriter.md) or because its position was changed in the model and its attributes were refreshed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

  Properties

  * `directChange.attributeKeys: Array<string>`
  * `directChange.directChange: boolean`

<a id="event-change:range">

### `change:range( eventInfo, directChange = { directChange.directChange } )`

Fired when selection range(s) changed.

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `directChange: object`

  In case of [`ModelSelection`](module_engine_model_selection-ModelSelection.md) class it is always set to `true` which indicates that the selection change was caused by a direct use of selection's API. The [`ModelDocumentSelection`](module_engine_model_documentselection-ModelDocumentSelection.md), however, may change because its position was directly changed through the [writer](module_engine_model_writer-ModelWriter.md) or because its position was changed because the structure of the model has been changed (which means an indirect change). The indirect change does not occur in case of normal (detached) selections because they are "static" (as "not live") which mean that they are not updated once the document changes.

  Properties

  * `directChange.directChange: boolean`

---

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