# ViewDocumentSelection

class

Class representing the document selection in the view.

Its instance is available in [`Document#selection`](module_engine_view_document-ViewDocument.md#member-selection).

It is similar to [`ViewSelection`](module_engine_view_selection-ViewSelection.md) but it has a read-only API and can be modified only by the writer available in the [`View#change()`](module_engine_view_view-EditingView.md#function-change) block (so via [`ViewDowncastWriter#setSelection()`](module_engine_view_downcastwriter-ViewDowncastWriter.md#function-setSelection:NODE_OFFSET)).

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

<a id="properties">

## Properties

<a id="member-anchor">

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

Selection anchor. Anchor may be described as a position where the selection starts. Together with [focus](#member-focus) they define the direction of selection, which is important when expanding/shrinking selection. Anchor is always the start or end of the most recent added range. It may be a bit unintuitive when there are multiple ranges in selection.

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

<a id="member-editableElement">

### `editableElement: ViewEditableElement | null` _(readonly)_

[ViewEditableElement](module_engine_view_editableelement-ViewEditableElement.md) instance that contains this selection, or `null` if the selection is not inside an editable element.

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

<a id="member-fakeSelectionLabel">

### `fakeSelectionLabel: string` _(readonly)_

Returns fake selection label.

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

<a id="member-focus">

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

Selection focus. Focus is a position where the selection ends.

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

<a id="member-isBackward">

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

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

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

<a id="member-isCollapsed">

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

Returns whether the selection is collapsed. Selection is collapsed when there is exactly one range which is collapsed.

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

<a id="member-isFake">

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

Returns true if selection instance is marked as `fake`.

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

<a id="member-rangeCount">

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

Returns number of ranges in selection.

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

<a id="member-_ranges">

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

Used for the compatibility with the [`isEqual`](module_engine_view_selection-ViewSelection.md#function-isEqual) method.

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

<a id="member-_selection">

### `_selection: ViewSelection` _(private)_

Selection is used internally (`ViewDocumentSelection` is a proxy to that selection).

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

<a id="methods">

## Methods

<a id="function-constructor:SELECTABLE">

### `constructor( selectable?, options? )`

Creates new ViewDocumentSelection instance.

```typescript
// Creates empty selection without ranges.
const selection = new ViewDocumentSelection();

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

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

// Creates selection from the other selection.
const otherSelection = writer.createSelection();
const selection = new ViewDocumentSelection( otherSelection );

// Creates selection at the given position.
const position = writer.createPositionAt( root, offset );
const selection = new ViewDocumentSelection( position );
```

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

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

Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

```typescript
// Creates fake selection with label.
const selection = new ViewDocumentSelection( range, { fake: true, label: 'foo' } );
```

See also: [`constructor( node, placeOrOffset, options )`](#function-constructor:NODE_OFFSET).

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

#### Parameters

* `selectable?: ViewPosition | ViewRange | ViewSelection | ViewDocumentSelection | Iterable<ViewRange> | null`
* `options?: ViewSelectionOptions`

<a id="function-constructor:NODE_OFFSET">

### `constructor( selectable, placeOrOffset, options? )`

Creates new ViewDocumentSelection instance.

```typescript
// Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( 'paragraph' );
const selection = new ViewDocumentSelection( 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 = new ViewDocumentSelection( paragraph, 'in' );

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

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

```typescript
// Creates backward selection.
const selection = new ViewDocumentSelection( element, 'in', { backward: true } );
```

Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM (and be properly handled by screen readers).

```typescript
// Creates fake selection with label.
const selection = new ViewDocumentSelection( element, 'in', { fake: true, label: 'foo' } );
```

See also: [`constructor( selectable, options )`](#function-constructor:SELECTABLE).

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

#### Parameters

* `selectable: ViewNode`
* `placeOrOffset: ViewPlaceOrOffset`
* `options?: ViewSelectionOptions`

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

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

Returns copy of the first position in the selection. First position is the position that [is before](module_engine_view_position-ViewPosition.md#function-isBefore) any other position in the selection ranges. Returns `null` if no ranges are added to selection.

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

#### Returns

* `ViewPosition | null`

<a id="function-getFirstRange">

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

Returns copy of the first range in the selection. First range is the one which [start](module_engine_view_range-ViewRange.md#member-start) position [is before](module_engine_view_position-ViewPosition.md#function-isBefore) start position of all other ranges (not to confuse with the first range added to the selection). Returns `null` if no ranges are added to selection.

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

#### Returns

* `ViewRange | null`

<a id="function-getLastPosition">

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

Returns copy of the last position in the selection. Last position is the position that [is after](module_engine_view_position-ViewPosition.md#function-isAfter) any other position in the selection ranges. Returns `null` if no ranges are added to selection.

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

#### Returns

* `ViewPosition | null`

<a id="function-getLastRange">

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

Returns copy of the last range in the selection. Last range is the one which [end](module_engine_view_range-ViewRange.md#member-end) position [is after](module_engine_view_position-ViewPosition.md#function-isAfter) end position of all other ranges (not to confuse with the last range added to the selection). Returns `null` if no ranges are added to selection.

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

#### Returns

* `ViewRange | null`

<a id="function-getRanges">

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

Returns an iterable that contains copies of all ranges added to the selection.

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

#### Returns

* `IterableIterator<ViewRange>`

<a id="function-getSelectedElement">

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

Returns the selected element. [Element](module_engine_view_element-ViewElement.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/view/documentselection.ts#L279)

#### Returns

* `ViewElement | null`

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

### `is( type ) → this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement` _(inherited)_

Checks whether this object is of type [`ViewElement`](module_engine_view_element-ViewElement.md) or its subclass.

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

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

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

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

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

#### Parameters

* `type: 'element' | 'view:element'`

#### Returns

* `this is ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement`

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

### `is( type ) → this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement` _(inherited)_

Checks whether this object is of type [`ViewContainerElement`](module_engine_view_containerelement-ViewContainerElement.md) or its subclass.

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

containerElement.is( 'model:element' ); // -> false
containerElement.is( 'documentFragment' ); // -> false
```

Assuming that the object being checked is a container element, you can also check its [name](module_engine_view_containerelement-ViewContainerElement.md#member-name):

```typescript
containerElement.is( 'element', 'div' ); // -> true if this is a div container element
containerElement.is( 'contaienrElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false
```

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

#### Parameters

* `type: 'containerElement' | 'view:containerElement'`

#### Returns

* `this is ViewContainerElement | ViewEditableElement | ViewRootEditableElement`

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

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

Checks whether this object is of type [`ViewAttributeElement`](module_engine_view_attributeelement-ViewAttributeElement.md).

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

attributeElement.is( 'model:element' ); // -> false
attributeElement.is( 'documentFragment' ); // -> false
```

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

```typescript
attributeElement.is( 'element', 'b' ); // -> true if this is a bold element
attributeElement.is( 'attributeElement', 'b' ); // -> same as above
text.is( 'element', 'b' ); -> false
```

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

#### Parameters

* `type: 'attributeElement' | 'view:attributeElement'`

#### Returns

* `this is ViewAttributeElement`

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

### `is( type ) → this is ViewEditableElement | ViewRootEditableElement` _(inherited)_

Checks whether this object is of type [`ViewEditableElement`](module_engine_view_editableelement-ViewEditableElement.md) or its subclass.

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

editableElement.is( 'model:element' ); // -> false
editableElement.is( 'documentFragment' ); // -> false
```

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

```typescript
editableElement.is( 'element', 'div' ); // -> true if this is a div element
editableElement.is( 'editableElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false
```

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

#### Parameters

* `type: 'editableElement' | 'view:editableElement'`

#### Returns

* `this is ViewEditableElement | ViewRootEditableElement`

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

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

Checks whether this object is of type [`ViewUIElement`](module_engine_view_uielement-ViewUIElement.md).

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

uiElement.is( 'model:element' ); // -> false
uiElement.is( 'documentFragment' ); // -> false
```

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

```typescript
uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
uiElement.is( 'uiElement', 'span' ); // -> same as above
text.is( 'element', 'span' ); -> false
```

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

#### Parameters

* `type: 'uiElement' | 'view:uiElement'`

#### Returns

* `this is ViewUIElement`

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

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

Checks whether this object is of type [`ViewTextProxy`](module_engine_view_textproxy-ViewTextProxy.md).

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

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

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

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

#### Parameters

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

#### Returns

* `this is ViewTextProxy`

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

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

hecks whether this object is of type [`ViewDocumentFragment`](module_engine_view_documentfragment-ViewDocumentFragment.md).

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

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

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

#### Parameters

* `type: 'documentFragment' | 'view:documentFragment'`

#### Returns

* `this is ViewDocumentFragment`

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

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

Checks whether this object is of type [`ViewText`](module_engine_view_text-ViewText.md).

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

text.is( 'model:$text' ); // -> false
text.is( 'element' ); // -> false
text.is( 'range' ); // -> false
```

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

#### Parameters

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

#### Returns

* `this is ViewText`

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

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

Checks whether this object is of type [`ViewRootEditableElement`](module_engine_view_rooteditableelement-ViewRootEditableElement.md).

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

rootEditableElement.is( 'model:element' ); // -> false
rootEditableElement.is( 'documentFragment' ); // -> false
```

Assuming that the object being checked is a root editable element, you can also check its [name](module_engine_view_rooteditableelement-ViewRootEditableElement.md#member-name):

```typescript
rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element
rootEditableElement.is( 'rootElement', 'div' ); // -> same as above
text.is( 'element', 'div' ); -> false
```

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

#### Parameters

* `type: 'rootElement' | 'view:rootElement'`

#### Returns

* `this is ViewRootEditableElement`

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

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

Checks whether this object is of type [`ViewRawElement`](module_engine_view_rawelement-ViewRawElement.md).

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

rawElement.is( 'model:element' ); // -> false
rawElement.is( 'documentFragment' ); // -> false
```

Assuming that the object being checked is a raw element, you can also check its [name](module_engine_view_rawelement-ViewRawElement.md#member-name):

```typescript
rawElement.is( 'img' ); // -> true if this is an img element
rawElement.is( 'rawElement', 'img' ); // -> same as above
text.is( 'img' ); -> false
```

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

#### Parameters

* `type: 'rawElement' | 'view:rawElement'`

#### Returns

* `this is ViewRawElement`

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

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

Checks whether this object is of type [`ViewEmptyElement`](module_engine_view_emptyelement-ViewEmptyElement.md).

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

emptyElement.is( 'model:element' ); // -> false
emptyElement.is( 'documentFragment' ); // -> false
```

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

```typescript
emptyElement.is( 'element', 'img' ); // -> true if this is a img element
emptyElement.is( 'emptyElement', 'img' ); // -> same as above
text.is( 'element', 'img' ); -> false
```

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

#### Parameters

* `type: 'emptyElement' | 'view:emptyElement'`

#### Returns

* `this is ViewEmptyElement`

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

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

Checks whether this object is of type [`ViewPosition`](module_engine_view_position-ViewPosition.md).

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

position.is( 'model:position' ); // -> false
position.is( 'element' ); // -> false
position.is( 'range' ); // -> false
```

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

#### Parameters

* `type: 'position' | 'view:position'`

#### Returns

* `this is ViewPosition`

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

### `is( type ) → this is ViewSelection | ViewDocumentSelection` _(inherited)_

Checks whether this object is of type [`ViewSelection`](module_engine_view_selection-ViewSelection.md) or [`ViewDocumentSelection`](module_engine_view_documentselection-ViewDocumentSelection.md).

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

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

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

#### Parameters

* `type: 'selection' | 'view:selection'`

#### Returns

* `this is ViewSelection | ViewDocumentSelection`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

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

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'containerElement' | 'view:containerElement'`
* `name: N`

#### Returns

* `boolean`

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

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

Checks whether the object is of type [`ViewEmptyElement`](module_engine_view_emptyelement-ViewEmptyElement.md) has the specified `name`.

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'emptyElement' | 'view:emptyElement'`
* `name: N`

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

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

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'uiElement' | 'view:uiElement'`
* `name: N`

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'rawElement' | 'view:rawElement'`
* `name: N`

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'editableElement' | 'view:editableElement'`
* `name: N`

#### Returns

* `boolean`

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

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

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

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

#### Type parameters

* `N: extends string`

#### Parameters

* `type: 'attributeElement' | 'view:attributeElement'`
* `name: N`

#### Returns

* `boolean`

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

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

Checks whether this object is of type [`ViewDocumentSelection`](module_engine_view_documentselection-ViewDocumentSelection.md).

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

docSelection.is( 'model:documentSelection' ); // -> false
docSelection.is( 'element' ); // -> false
docSelection.is( 'node' ); // -> false
```

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

#### Parameters

* `type: 'documentSelection' | 'view:documentSelection'`

#### Returns

* `this is ViewDocumentSelection`

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

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

Checks whether this object is of type [`ViewRange`](module_engine_view_range-ViewRange.md).

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

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

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

#### Parameters

* `type: 'range' | 'view:range'`

#### Returns

* `this is ViewRange`

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

### `is( type ) → this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement` _(inherited)_

Checks whether this object is of type [`ViewNode`](module_engine_view_node-ViewNode.md) or its subclass.

This method is useful when processing view objects that are of unknown type. For example, a function may return a [`ViewDocumentFragment`](module_engine_view_documentfragment-ViewDocumentFragment.md) or a [`ViewNode`](module_engine_view_node-ViewNode.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 model 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
viewElement.is( 'view:element' ); // -> true
viewElement.is( 'model:element' ); // -> false
```

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

```typescript
imgElement.is( 'element', 'img' ); // -> true
imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise
```

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

#### Parameters

* `type: 'node' | 'view:node'`

#### Returns

* `this is ViewText | ViewNode | ViewElement | ViewAttributeElement | ViewContainerElement | ViewEditableElement | ViewEmptyElement | ViewRawElement | ViewRootEditableElement | ViewUIElement`

<a id="function-isEqual">

### `isEqual( otherSelection ) → boolean`

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

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

#### Parameters

* `otherSelection: ViewSelection | ViewDocumentSelection`

  Selection to compare with.

#### Returns

* `boolean`

  `true` if selections are equal, `false` otherwise.

<a id="function-isSimilar">

### `isSimilar( otherSelection ) → boolean`

Checks whether this selection is similar to given selection. Selections are similar if they have same directions, same number of ranges, and all [trimmed](module_engine_view_range-ViewRange.md#function-getTrimmed) ranges from one selection are equal to any trimmed range from other selection.

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

#### Parameters

* `otherSelection: ViewSelection | ViewDocumentSelection`

  Selection to compare with.

#### Returns

* `boolean`

  `true` if selections are similar, `false` otherwise.

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

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

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

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

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

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

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

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

#### Type parameters

* `TEvent: extends BaseEvent`

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

#### Parameters

* `emitter: Emitter`

  The object that fires the event.

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-off">

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

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

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

#### Parameters

* `event: string`

  The name of the event.

* `callback: Function`

  The function to stop being called.

#### Returns

* `void`

<a id="function-on">

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

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

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

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

#### Type parameters

* `TEvent: extends BaseEvent`

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

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-once">

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

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

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

#### Type parameters

* `TEvent: extends BaseEvent`

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

#### Parameters

* `event: TEvent[ 'name' ]`

  The name of the event.

* `callback: GetCallback<TEvent>`

  The function to be called on event.

* `options?: GetCallbackOptions<TEvent>`

  Additional options.

#### Returns

* `void`

<a id="function-stopDelegating">

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

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

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

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

#### Parameters

* `event?: string`

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

* `emitter?: Emitter`

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

#### Returns

* `void`

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

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

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

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

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

#### Parameters

* `emitter?: Emitter`

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

* `event?: string`

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

* `callback?: Function`

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

#### Returns

* `void`

<a id="function-toJSON">

### `toJSON() → unknown`

Converts `ViewDocumentSelection` instance to plain object and returns it.

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

#### Returns

* `unknown`

  `ViewDocumentSelection` instance converted to plain object.

<a id="function-_setFocus">

### `_setFocus( itemOrPosition, offset? ) → void` _(internal)_

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

The location can be specified in the same form as [view.createPositionAt()](module_engine_view_view-EditingView.md#function-createPositionAt) parameters.

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

#### Parameters

* `itemOrPosition: ViewPosition | ViewItem`

* `offset?: ViewPositionOffset`

  Offset or one of the flags. Used only when first parameter is a [view item](module_engine_view_item-ViewItem.md).

#### Returns

* `void`

#### Fires

* [change](#event-change)

<a id="function-_setTo">

### `_setTo( args ) → void` _(internal)_

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

```typescript
// Sets selection to the given range.
const range = writer.createRange( start, end );
documentSelection._setTo( range );

// Sets selection to given ranges.
const ranges = [ writer.createRange( start1, end2 ), writer.createRange( start2, end2 ) ];
documentSelection._setTo( range );

// Sets selection to the other selection.
const otherSelection = writer.createSelection();
documentSelection._setTo( otherSelection );

// Sets collapsed selection at the given position.
const position = writer.createPositionAt( root, offset );
documentSelection._setTo( position );

// Sets collapsed selection at the position of given item and offset.
documentSelection._setTo( paragraph, offset );
```

Creates a range inside an [element](module_engine_view_element-ViewElement.md) which starts before the first child of that element and ends after the last child of that element.

```typescript
documentSelection._setTo( paragraph, 'in' );
```

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

```typescript
documentSelection._setTo( paragraph, 'on' );

// Clears selection. Removes all ranges.
documentSelection._setTo( null );
```

`Selection#_setTo()` method allow passing additional options (`backward`, `fake` and `label`) as the last argument.

```typescript
// Sets selection as backward.
documentSelection._setTo( range, { backward: true } );
```

Fake selection does not render as browser native selection over selected elements and is hidden to the user. This way, no native selection UI artifacts are displayed to the user and selection over elements can be represented in other way, for example by applying proper CSS class.

Additionally fake's selection label can be provided. It will be used to des cribe fake selection in DOM (and be properly handled by screen readers).

```typescript
// Creates fake selection with label.
documentSelection._setTo( range, { fake: true, label: 'foo' } );
```

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

#### Parameters

* `args: [ selectable: ViewNode, placeOrOffset: ViewPlaceOrOffset, options?: ViewSelectionOptions ] | [ selectable?: ViewPosition | ViewRange | ViewSelection | ViewDocumentSelection | Iterable<ViewRange> | null, options?: ViewSelectionOptions ]`

#### Returns

* `void`

#### Fires

* [change](#event-change)

<a id="events">

## Events

<a id="event-change">

### `change( eventInfo )`

Fired whenever selection ranges are changed through [Selection API](module_engine_view_documentselection-ViewDocumentSelection.md).

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

---

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