# ModelWriter

class

The model can only be modified by using the writer. It should be used whenever you want to create a node, modify child nodes, attributes or text, set the selection's position and its attributes.

The instance of the writer is only available in the [`change()`](module_engine_model_model-Model.md#function-change) or [`enqueueChange()`](module_engine_model_model-Model.md#function-enqueueChange:DEFAULT_BATCH).

```typescript
model.change( writer => {
	writer.insertText( 'foo', paragraph, 'end' );
} );
```

Note that the writer should never be stored and used outside of the `change()` and `enqueueChange()` blocks.

Note that writer's methods do not check the [`ModelSchema`](module_engine_model_schema-ModelSchema.md). It is possible to create incorrect model structures by using the writer. Read more about in ["Who checks the schema?"](../framework/deep-dive/schema.md#who-checks-the-schema).

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

<a id="properties">

## Properties

<a id="member-batch">

### `batch: Batch` _(readonly)_

The batch to which this writer will add changes.

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

<a id="member-model">

### `model: Model` _(readonly)_

Instance of the model on which this writer operates.

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( model, batch )` _(internal)_

Creates a writer instance.

**Note:** It is not recommended to use it directly. Use [`Model#change()`](module_engine_model_model-Model.md#function-change) or [`Model#enqueueChange()`](module_engine_model_model-Model.md#function-enqueueChange:DEFAULT_BATCH) instead.

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

#### Parameters

* `model: Model`
* `batch: Batch`

<a id="function-addMarker">

### `addMarker( name, options = { options.affectsData?, options.range, options.usingOperation } ) → Marker`

Adds a [marker](module_engine_model_markercollection-Marker.md). Marker is a named range, which tracks changes in the document and updates its range automatically, when model tree changes.

As the first parameter you can set marker name.

The required `options.usingOperation` parameter lets you decide if the marker should be managed by operations or not. See [marker class description](module_engine_model_markercollection-Marker.md) to learn about the difference between markers managed by operations and not-managed by operations.

The `options.affectsData` parameter, which defaults to `false`, allows you to define if a marker affects the data. It should be `true` when the marker change changes the data returned by the [`editor.getData()`](module_core_editor_editor-Editor.md#function-getData) method. When set to `true` it fires the [`change:data`](module_engine_model_document-ModelDocument.md#event-change:data) event. When set to `false` it fires the [`change`](module_engine_model_document-ModelDocument.md#event-change) event.

Create marker directly base on marker's name:

```typescript
addMarker( markerName, { range, usingOperation: false } );
```

Create marker using operation:

```typescript
addMarker( markerName, { range, usingOperation: true } );
```

Create marker that affects the editor data:

```typescript
addMarker( markerName, { range, usingOperation: false, affectsData: true } );
```

Note: For efficiency reasons, it's best to create and keep as little markers as possible.

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

#### Parameters

* `name: string`

  Name of a marker to create - must be unique.

* `options: object`

  Properties

  * `options.affectsData?: boolean`

    Flag indicating that the marker changes the editor data.

  * `options.range: ModelRange`

    Marker range.

  * `options.usingOperation: boolean`

    Flag indicating that the marker should be added by MarkerOperation. See [`managedUsingOperations`](module_engine_model_markercollection-Marker.md#member-managedUsingOperations).

#### Returns

* `Marker`

  Marker that was set.

#### Related:

* [Marker](module_engine_model_markercollection-Marker.md)

<a id="function-addRoot">

### `addRoot( rootName, elementName ) → ModelRootElement`

Adds a new root to the document (or re-attaches a [detached root](#function-detachRoot)).

Throws an error, if trying to add a root that is already added and attached.

**Note:** The default `elementName` value is `'$root'`. When the editor uses a custom root [`modelElement`](module_core_editor_editorconfig-RootConfig.md#member-modelElement), pass the configured model element name explicitly so the added root matches the schema the features expect. See the [Custom root elements](../framework/deep-dive/schema.md#custom-root-elements) section of the [Schema deep-dive](../framework/deep-dive/schema.md) guide for more details.

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

#### Parameters

* `rootName: string`

  Name of the added root.

* `elementName: string`

  The element name. Defaults to `'$root'` which also has some basic schema defined (e.g. `$block` elements are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.

  Defaults to `'$root'`

#### Returns

* `ModelRootElement`

  The added root element.

<a id="function-append">

### `append( item, parent ) → void`

Inserts item at the end of the given parent.

```typescript
const paragraph = writer.createElement( 'paragraph' );
writer.append( paragraph, root );
```

Note that if the item already has parent it will be removed from the previous parent.

If you want to move [range](module_engine_model_range-ModelRange.md) instead of an [item](module_engine_model_item-ModelItem.md) use [`Writer#move()`](#function-move).

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

#### Parameters

* `item: ModelDocumentFragment | ModelItem`

  Item or document fragment to insert.

* `parent: ModelElement | ModelDocumentFragment`

#### Returns

* `void`

<a id="function-appendElement:WITH_ATTRIBUTES">

### `appendElement( name, attributes, parent ) → void`

Creates element with specified attributes and inserts it at the end of the parent.

```typescript
writer.appendElement( 'paragraph', { alignment: 'center' }, root );
```

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

#### Parameters

* `name: string`

  Name of the element.

* `attributes: ModelNodeAttributes`

  Elements attributes.

* `parent: ModelElement | ModelDocumentFragment`

#### Returns

* `void`

<a id="function-appendElement:WITHOUT_ATTRIBUTES">

### `appendElement( name, parent ) → void`

Creates element and inserts it at the end of the parent.

```typescript
writer.appendElement( 'paragraph', root );
```

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

#### Parameters

* `name: string`

  Name of the element.

* `parent: ModelElement | ModelDocumentFragment`

#### Returns

* `void`

<a id="function-appendText:WITH_ATTRIBUTES">

### `appendText( text, attributes, parent ) → void`

Creates text node with specified attributes and inserts it at the end of the parent.

```typescript
writer.appendText( 'foo', { bold: true }, paragraph );
```

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

#### Parameters

* `text: string`

  Text data.

* `attributes: ModelNodeAttributes`

  Text attributes.

* `parent: ModelElement | ModelDocumentFragment`

#### Returns

* `void`

<a id="function-appendText:WITHOUT_ATTRIBUTES">

### `appendText( text, parent ) → void`

Creates text node and inserts it at the end of the parent.

```typescript
writer.appendText( 'foo', paragraph );
```

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

#### Parameters

* `text: string`

  Text data.

* `parent: ModelElement | ModelDocumentFragment`

#### Returns

* `void`

<a id="function-clearAttributes">

### `clearAttributes( itemOrRange ) → void`

Removes all attributes from all elements in the range or from the given item.

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

#### Parameters

* `itemOrRange: ModelRange | ModelItem`

  Model item or range from which all attributes will be removed.

#### Returns

* `void`

<a id="function-cloneElement">

### `cloneElement( element, deep ) → ModelElement`

Creates a copy of the element and returns it. Created element has the same name and attributes as the original element. If clone is deep, the original element's children are also cloned. If not, then empty element is returned.

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

#### Parameters

* `element: ModelElement`

  The element to clone.

* `deep: boolean`

  If set to `true` clones element and all its children recursively. When set to `false`, element will be cloned without any child.

  Defaults to `true`

#### Returns

* `ModelElement`

<a id="function-createDocumentFragment">

### `createDocumentFragment() → ModelDocumentFragment`

Creates a new [document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md).

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

#### Returns

* `ModelDocumentFragment`

  Created document fragment.

<a id="function-createElement">

### `createElement( name, attributes? ) → ModelElement`

Creates a new [element](module_engine_model_element-ModelElement.md).

```typescript
writer.createElement( 'paragraph' );
writer.createElement( 'paragraph', { alignment: 'center' } );
```

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

#### Parameters

* `name: string`

  Name of the element.

* `attributes?: ModelNodeAttributes`

  Elements attributes.

#### Returns

* `ModelElement`

  Created element.

<a id="function-createPositionAfter">

### `createPositionAfter( item ) → ModelPosition`

Shortcut for [`Model#createPositionAfter()`](module_engine_model_model-Model.md#function-createPositionAfter).

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

#### Parameters

* `item: ModelItem`

  Item after which the position should be placed.

#### Returns

* `ModelPosition`

<a id="function-createPositionAt">

### `createPositionAt( itemOrPosition, offset? ) → ModelPosition`

Shortcut for [`Model#createPositionAt()`](module_engine_model_model-Model.md#function-createPositionAt).

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

#### Parameters

* `itemOrPosition: ModelDocumentFragment | 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

* `ModelPosition`

<a id="function-createPositionBefore">

### `createPositionBefore( item ) → ModelPosition`

Shortcut for [`Model#createPositionBefore()`](module_engine_model_model-Model.md#function-createPositionBefore).

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

#### Parameters

* `item: ModelItem`

  Item after which the position should be placed.

#### Returns

* `ModelPosition`

<a id="function-createPositionFromPath">

### `createPositionFromPath( root, path, stickiness? ) → ModelPosition`

Shortcut for [`Model#createPositionFromPath()`](module_engine_model_model-Model.md#function-createPositionFromPath).

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

#### Parameters

* `root: ModelElement | ModelDocumentFragment`

  Root of the position.

* `path: readonly Array<number>`

  Position path. See [`path`](module_engine_model_position-ModelPosition.md#member-path).

* `stickiness?: ModelPositionStickiness`

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

#### Returns

* `ModelPosition`

<a id="function-createRange">

### `createRange( start, end? ) → ModelRange`

Shortcut for [`Model#createRange()`](module_engine_model_model-Model.md#function-createRange).

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

#### Parameters

* `start: ModelPosition`

  Start position.

* `end?: ModelPosition`

  End position. If not set, range will be collapsed at `start` position.

#### Returns

* `ModelRange`

<a id="function-createRangeIn">

### `createRangeIn( element ) → ModelRange`

Shortcut for [`Model#createRangeIn()`](module_engine_model_model-Model.md#function-createRangeIn).

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

#### Parameters

* `element: ModelElement | ModelDocumentFragment`

  Element which is a parent for the range.

#### Returns

* `ModelRange`

<a id="function-createRangeOn">

### `createRangeOn( element ) → ModelRange`

Shortcut for [`Model#createRangeOn()`](module_engine_model_model-Model.md#function-createRangeOn).

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

#### Parameters

* `element: ModelItem`

  Element which is a parent for the range.

#### Returns

* `ModelRange`

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

### `createSelection( selectable?, options? = { options.backward? } ) → ModelSelection`

Shortcut for [`Model#createSelection()`](module_engine_model_model-Model.md#function-createSelection:SELECTABLE).

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

#### Parameters

* `selectable?: ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange> | null`

* `options?: object`

  Properties

  * `options.backward?: boolean`

#### Returns

* `ModelSelection`

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

### `createSelection( selectable, placeOrOffset, options? = { options.backward? } ) → ModelSelection`

Shortcut for [`Model#createSelection()`](module_engine_model_model-Model.md#function-createSelection:NODE_OFFSET).

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

#### Parameters

* `selectable: ModelNode`

* `placeOrOffset: ModelPlaceOrOffset`

* `options?: object`

  Properties

  * `options.backward?: boolean`

#### Returns

* `ModelSelection`

<a id="function-createText">

### `createText( data, attributes? ) → ModelText`

Creates a new [text node](module_engine_model_text-ModelText.md).

```typescript
writer.createText( 'foo' );
writer.createText( 'foo', { bold: true } );
```

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

#### Parameters

* `data: string`

  Text data.

* `attributes?: ModelNodeAttributes`

  Text attributes.

#### Returns

* `ModelText`

  Created text node.

<a id="function-detachRoot">

### `detachRoot( rootOrName ) → void`

Detaches the root from the document.

All content and markers are removed from the root upon detaching. New content and new markers cannot be added to the root, as long as it is detached.

A root cannot be fully removed from the document, it can be only detached. A root is permanently removed only after you re-initialize the editor and do not specify the root in the initial data.

A detached root can be re-attached using [`addRoot`](#function-addRoot).

Throws an error if the root does not exist or the root is already detached.

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

#### Parameters

* `rootOrName: string | ModelRootElement`

  Name of the detached root.

#### Returns

* `void`

<a id="function-insert">

### `insert( item, itemOrPosition, offset ) → void`

Inserts item on given position.

```typescript
const paragraph = writer.createElement( 'paragraph' );
writer.insert( paragraph, position );
```

Instead of using position you can use parent and offset:

```typescript
const text = writer.createText( 'foo' );
writer.insert( text, paragraph, 5 );
```

You can also use `end` instead of the offset to insert at the end:

```typescript
const text = writer.createText( 'foo' );
writer.insert( text, paragraph, 'end' );
```

Or insert before or after another element:

```typescript
const paragraph = writer.createElement( 'paragraph' );
writer.insert( paragraph, anotherParagraph, 'after' );
```

These parameters works the same way as [`writer.createPositionAt()`](#function-createPositionAt).

Note that if the item already has parent it will be removed from the previous parent.

Note that you cannot re-insert a node from a document to a different document or a document fragment. In this case, `model-writer-insert-forbidden-move` is thrown.

If you want to move [range](module_engine_model_range-ModelRange.md) instead of an [item](module_engine_model_item-ModelItem.md) use [`Writer#move()`](#function-move).

**Note:** For a paste-like content insertion mechanism see [`model.insertContent()`](module_engine_model_model-Model.md#function-insertContent).

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

#### Parameters

* `item: ModelDocumentFragment | ModelItem`

  Item or document fragment to insert.

* `itemOrPosition: ModelDocumentFragment | ModelPosition | ModelItem`

* `offset: ModelPositionOffset`

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

  Defaults to `0`

#### Returns

* `void`

<a id="function-insertElement:WITH_ATTRIBUTES">

### `insertElement( name, attributes, itemOrPosition, offset? ) → void`

Creates and inserts element with specified attributes on given position.

```typescript
writer.insertElement( 'paragraph', { alignment: 'center' }, position );
```

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

```typescript
// Inserts paragraph in the root at offset 5:
writer.insertElement( 'paragraph', { alignment: 'center' }, root, 5 );
// Inserts paragraph at the end of a blockquote:
writer.insertElement( 'paragraph', { alignment: 'center' }, blockquote, 'end' );
// Inserts after an image:
writer.insertElement( 'paragraph', { alignment: 'center' }, image, 'after' );
```

These parameters works the same way as [`writer.createPositionAt()`](#function-createPositionAt).

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

#### Parameters

* `name: string`

  Name of the element.

* `attributes: ModelNodeAttributes`

  Elements attributes.

* `itemOrPosition: ModelDocumentFragment | ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

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

#### Returns

* `void`

<a id="function-insertElement:WITHOUT_ATTRIBUTES">

### `insertElement( name, itemOrPosition, offset? ) → void`

Creates and inserts element on given position. You can optionally set attributes:

```typescript
writer.insertElement( 'paragraph', position );
```

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

```typescript
// Inserts paragraph in the root at offset 5:
writer.insertElement( 'paragraph', root, 5 );
// Inserts paragraph at the end of a blockquote:
writer.insertElement( 'paragraph', blockquote, 'end' );
// Inserts after an image:
writer.insertElement( 'paragraph', image, 'after' );
```

These parameters works the same way as [`writer.createPositionAt()`](#function-createPositionAt).

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

#### Parameters

* `name: string`

  Name of the element.

* `itemOrPosition: ModelDocumentFragment | ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

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

#### Returns

* `void`

<a id="function-insertText:WITH_ATTRIBUTES">

### `insertText( text, attributes?, itemOrPosition?, offset? ) → void`

Creates and inserts text with specified attributes on given position.

```typescript
writer.insertText( 'foo', { bold: true }, position );
```

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

```typescript
// Inserts 'foo' in paragraph, at offset 5:
writer.insertText( 'foo', { bold: true }, paragraph, 5 );
// Inserts 'foo' at the end of a paragraph:
writer.insertText( 'foo', { bold: true }, paragraph, 'end' );
// Inserts 'foo' after an image:
writer.insertText( 'foo', { bold: true }, image, 'after' );
```

These parameters work in the same way as [`writer.createPositionAt()`](#function-createPositionAt).

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

#### Parameters

* `text: string`

  Text data.

* `attributes?: ModelNodeAttributes`

  Text attributes.

* `itemOrPosition?: ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

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

#### Returns

* `void`

<a id="function-insertText:WITHOUT_ATTRIBUTES">

### `insertText( text, itemOrPosition?, offset? ) → void`

Creates and inserts text on given position.

```typescript
writer.insertText( 'foo', position );
```

Instead of using position you can use parent and offset or define that text should be inserted at the end or before or after other node:

```typescript
// Inserts 'foo' in paragraph, at offset 5:
writer.insertText( 'foo', paragraph, 5 );
// Inserts 'foo' at the end of a paragraph:
writer.insertText( 'foo', paragraph, 'end' );
// Inserts 'foo' after an image:
writer.insertText( 'foo', image, 'after' );
```

These parameters work in the same way as [`writer.createPositionAt()`](#function-createPositionAt).

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

#### Parameters

* `text: string`

  Text data.

* `itemOrPosition?: ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

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

#### Returns

* `void`

<a id="function-merge">

### `merge( position ) → void`

Merges two siblings at the given position.

Node before and after the position have to be an element. Otherwise `writer-merge-no-element-before` or `writer-merge-no-element-after` error will be thrown.

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

#### Parameters

* `position: ModelPosition`

  Position between merged elements.

#### Returns

* `void`

<a id="function-move">

### `move( range, itemOrPosition, offset? ) → void`

Moves all items in the source range to the target position.

```typescript
writer.move( sourceRange, targetPosition );
```

Instead of the target position you can use parent and offset or define that range should be moved to the end or before or after chosen item:

```typescript
// Moves all items in the range to the paragraph at offset 5:
writer.move( sourceRange, paragraph, 5 );
// Moves all items in the range to the end of a blockquote:
writer.move( sourceRange, blockquote, 'end' );
// Moves all items in the range to a position after an image:
writer.move( sourceRange, image, 'after' );
```

These parameters work the same way as [`writer.createPositionAt()`](#function-createPositionAt).

Note that items can be moved only within the same tree. It means that you can move items within the same root (element or document fragment) or between [documents roots](module_engine_model_document-ModelDocument.md#member-roots), but you cannot move items from document fragment to the document or from one detached element to another. Use [`insert`](#function-insert) in such cases.

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

#### Parameters

* `range: ModelRange`

  Source range.

* `itemOrPosition: ModelPosition | ModelItem`

* `offset?: ModelPositionOffset`

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

#### Returns

* `void`

<a id="function-overrideSelectionGravity">

### `overrideSelectionGravity() → string`

Temporarily changes the [gravity](module_engine_model_documentselection-ModelDocumentSelection.md#member-isGravityOverridden) of the selection from left to right.

The gravity defines from which direction the selection inherits its attributes. If it's the default left gravity, then the selection (after being moved by the user) inherits attributes from its left-hand side. This method allows to temporarily override this behavior by forcing the gravity to the right.

For the following model fragment:

```xml
<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
```

* Default gravity: selection will have the `bold` and `linkHref` attributes.
* Overridden gravity: selection will have `bold` attribute.

**Note**: It returns an unique identifier which is required to restore the gravity. It guarantees the symmetry of the process.

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

#### Returns

* `string`

  The unique id which allows restoring the gravity.

<a id="function-remove">

### `remove( itemOrRange ) → void`

Removes given model [item](module_engine_model_item-ModelItem.md) or [range](module_engine_model_range-ModelRange.md).

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

#### Parameters

* `itemOrRange: ModelRange | ModelItem`

  Model item or range to remove.

#### Returns

* `void`

<a id="function-removeAttribute">

### `removeAttribute( key, itemOrRange ) → void`

Removes an attribute with given key from a [model item](module_engine_model_item-ModelItem.md) or from a [range](module_engine_model_range-ModelRange.md).

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

#### Parameters

* `key: string`

  Attribute key.

* `itemOrRange: ModelRange | ModelItem`

  Model item or range from which the attribute will be removed.

#### Returns

* `void`

<a id="function-removeMarker">

### `removeMarker( markerOrName ) → void`

Removes given [marker](module_engine_model_markercollection-Marker.md) or marker with given name. The marker is removed accordingly to how it has been created, so if the marker was created using operation, it will be destroyed using operation.

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

#### Parameters

* `markerOrName: string | Marker`

  Marker or marker name to remove.

#### Returns

* `void`

<a id="function-removeSelectionAttribute">

### `removeSelectionAttribute( keyOrIterableOfKeys ) → void`

Removes attribute(s) with given key(s) from the selection.

Remove one attribute:

```typescript
writer.removeSelectionAttribute( 'italic' );
```

Remove multiple attributes:

```typescript
writer.removeSelectionAttribute( [ 'italic', 'bold' ] );
```

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

#### Parameters

* `keyOrIterableOfKeys: string | Iterable<string>`

  Key of the attribute to remove or an iterable of attribute keys to remove.

#### Returns

* `void`

<a id="function-rename">

### `rename( element, newName ) → void`

Renames the given element.

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

#### Parameters

* `element: ModelElement | ModelDocumentFragment`

  The element to rename.

* `newName: string`

  New element name.

#### Returns

* `void`

<a id="function-restoreSelectionGravity">

### `restoreSelectionGravity( uid ) → void`

Restores [`overrideSelectionGravity`](#function-overrideSelectionGravity) gravity to default.

Restoring the gravity is only possible using the unique identifier returned by [`overrideSelectionGravity`](#function-overrideSelectionGravity). Note that the gravity remains overridden as long as won't be restored the same number of times it was overridden.

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

#### Parameters

* `uid: string`

  The unique id returned by [`overrideSelectionGravity`](#function-overrideSelectionGravity).

#### Returns

* `void`

<a id="function-setAttribute">

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

Sets value of the attribute with given key on a [model item](module_engine_model_item-ModelItem.md) or on a [range](module_engine_model_range-ModelRange.md).

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

#### Parameters

* `key: string`

  Attribute key.

* `value: unknown`

  Attribute new value.

* `itemOrRange: ModelRange | ModelItem`

  Model item or range on which the attribute will be set.

#### Returns

* `void`

<a id="function-setAttributes">

### `setAttributes( attributes, itemOrRange ) → void`

Sets values of attributes on a [model item](module_engine_model_item-ModelItem.md) or on a [range](module_engine_model_range-ModelRange.md).

```typescript
writer.setAttributes( {
	bold: true,
	italic: true
}, range );
```

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

#### Parameters

* `attributes: ModelNodeAttributes`

  Attributes keys and values.

* `itemOrRange: ModelRange | ModelItem`

  Model item or range on which the attributes will be set.

#### Returns

* `void`

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

### `setSelection( selectable, options? = { options.backward? } ) → void`

Sets the document's selection (ranges and direction) to the specified location based on the given [selectable](module_engine_model_selection-ModelSelectable.md) or creates an empty selection if no arguments were passed.

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

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

// Sets selection to other selection.
const otherSelection = writer.createSelection();
writer.setSelection( otherSelection );

// Sets selection to the given document selection.
const documentSelection = model.document.selection;
writer.setSelection( documentSelection );

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

// Removes all selection's ranges.
writer.setSelection( null );
```

`Writer#setSelection()` allow passing additional options (`backward`) as the last argument.

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

Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.

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

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

#### Parameters

* `selectable: ModelPosition | ModelRange | ModelSelection | ModelDocumentSelection | Iterable<ModelRange> | null`

* `options?: object`

  Properties

  * `options.backward?: boolean`

#### Returns

* `void`

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

### `setSelection( selectable, placeOrOffset, options? = { options.backward? } ) → void`

Sets the document's selection (ranges and direction) to the specified location based on the given [selectable](module_engine_model_selection-ModelSelectable.md) or creates an empty selection if no arguments were passed.

```typescript
// Sets collapsed selection at the position of the given node and an offset.
writer.setSelection( 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
writer.setSelection( 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
writer.setSelection( paragraph, 'on' );
```

`Writer#setSelection()` allow passing additional options (`backward`) as the last argument.

```typescript
// Sets selection as backward.
writer.setSelection( element, 'in', { backward: true } );
```

Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.

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

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

#### Parameters

* `selectable: ModelNode`

* `placeOrOffset: ModelPlaceOrOffset`

* `options?: object`

  Properties

  * `options.backward?: boolean`

#### Returns

* `void`

<a id="function-setSelectionAttribute:OBJECT">

### `setSelectionAttribute( objectOrIterable ) → void`

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

Using key-value object:

```typescript
writer.setSelectionAttribute( { italic: true, bold: false } );
```

Using iterable object:

```typescript
writer.setSelectionAttribute( new Map( [ [ 'italic', true ] ] ) );
```

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

#### Parameters

* `objectOrIterable: ModelNodeAttributes`

  Object / iterable of key => value attribute pairs.

#### Returns

* `void`

<a id="function-setSelectionAttribute:KEY_VALUE">

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

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

```typescript
writer.setSelectionAttribute( 'italic', true );
```

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

#### Parameters

* `key: string`

  Key of the attribute to set.

* `value: unknown`

  Attribute value.

#### Returns

* `void`

<a id="function-setSelectionFocus">

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

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

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

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

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

<a id="function-split">

### `split( position, limitElement? ) → object`

Splits elements starting from the given position and going to the top of the model tree as long as given `limitElement` is reached. When `limitElement` is not defined then only the parent of the given position will be split.

The element needs to have a parent. It cannot be a root element nor a document fragment. The `writer-split-element-no-parent` error will be thrown if you try to split an element with no parent.

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

#### Parameters

* `position: ModelPosition`

  Position of split.

* `limitElement?: ModelNode | ModelDocumentFragment`

  Stop splitting when this element will be reached.

#### Returns

* `object`

  Split result with properties:

  * `position` - Position between split elements.
  * `range` - Range that stars from the end of the first split element and ends at the beginning of the first copy element.

<a id="function-unwrap">

### `unwrap( element ) → void`

Unwraps children of the given element – all its children are moved before it and then the element is removed. Throws error if you try to unwrap an element which does not have a parent.

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

#### Parameters

* `element: ModelElement`

  Element to unwrap.

#### Returns

* `void`

<a id="function-updateMarker">

### `updateMarker( markerOrName, options? = { options.affectsData?, options.range?, options.usingOperation? } ) → void`

Adds, updates or refreshes a [marker](module_engine_model_markercollection-Marker.md). Marker is a named range, which tracks changes in the document and updates its range automatically, when model tree changes. Still, it is possible to change the marker's range directly using this method.

As the first parameter you can set marker name or instance. If none of them is provided, new marker, with a unique name is created and returned.

**Note**: If you want to change the [view element](module_engine_view_element-ViewElement.md) of the marker while its data in the model remains the same, use the dedicated [`reconvertMarker`](module_engine_controller_editingcontroller-EditingController.md#function-reconvertMarker) method.

The `options.usingOperation` parameter lets you change if the marker should be managed by operations or not. See [marker class description](module_engine_model_markercollection-Marker.md) to learn about the difference between markers managed by operations and not-managed by operations. It is possible to change this option for an existing marker.

The `options.affectsData` parameter, which defaults to `false`, allows you to define if a marker affects the data. It should be `true` when the marker change changes the data returned by the [`editor.getData()`](module_core_editor_editor-Editor.md#function-getData) method. When set to `true` it fires the [`change:data`](module_engine_model_document-ModelDocument.md#event-change:data) event. When set to `false` it fires the [`change`](module_engine_model_document-ModelDocument.md#event-change) event.

Update marker directly base on marker's name:

```typescript
updateMarker( markerName, { range } );
```

Update marker using operation:

```typescript
updateMarker( marker, { range, usingOperation: true } );
updateMarker( markerName, { range, usingOperation: true } );
```

Change marker's option (start using operations to manage it):

```typescript
updateMarker( marker, { usingOperation: true } );
```

Change marker's option (inform the engine, that the marker does not affect the data anymore):

```typescript
updateMarker( markerName, { affectsData: false } );
```

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

#### Parameters

* `markerOrName: string | Marker`

  Name of a marker to update, or a marker instance.

* `options?: object`

  If options object is not defined then marker will be refreshed by triggering downcast conversion for this marker with the same data.

  Properties

  * `options.affectsData?: boolean`

    Flag indicating that the marker changes the editor data.

  * `options.range?: ModelRange`

    Marker range to update.

  * `options.usingOperation?: boolean`

    Flag indicated whether the marker should be added by MarkerOperation. See [`managedUsingOperations`](module_engine_model_markercollection-Marker.md#member-managedUsingOperations).

#### Returns

* `void`

#### Related:

* [Marker](module_engine_model_markercollection-Marker.md)

<a id="function-wrap">

### `wrap( range, elementOrString ) → void`

Wraps the given range with the given element or with a new element (if a string was passed).

**Note:** range to wrap should be a "flat range" (see [`Range#isFlat`](module_engine_model_range-ModelRange.md#member-isFlat)). If not, an error will be thrown.

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

#### Parameters

* `range: ModelRange`

  Range to wrap.

* `elementOrString: string | ModelElement`

  Element or name of element to wrap the range with.

#### Returns

* `void`

<a id="function-_addOperationForAffectedMarkers">

### `_addOperationForAffectedMarkers( type, positionOrRange ) → void` _(internal)_

For given action `type` and `positionOrRange` where the action happens, this function finds all affected markers and applies a marker operation with the new marker range equal to the current range. Thanks to this, the marker range can be later correctly processed during undo.

Exposed so that code applying operations directly to the model can reproduce the same marker bookkeeping.

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

#### Parameters

* `type: 'move' | 'merge'`

  Writer action type.

* `positionOrRange: ModelPosition | ModelRange`

  Position or range where the writer action happens.

#### Returns

* `void`

<a id="function-_assertWriterUsedCorrectly">

### `_assertWriterUsedCorrectly() → void` _(private)_

Throws `writer-detached-writer-tries-to-modify-model` error when the writer is used outside of the `change()` block.

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

#### Returns

* `void`

<a id="function-_merge">

### `_merge( position ) → void` _(private)_

Performs merge action in a non-detached tree.

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

#### Parameters

* `position: ModelPosition`

  Position between merged elements.

#### Returns

* `void`

<a id="function-_mergeDetached">

### `_mergeDetached( position ) → void` _(private)_

Performs merge action in a detached tree.

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

#### Parameters

* `position: ModelPosition`

  Position between merged elements.

#### Returns

* `void`

<a id="function-_removeSelectionAttribute">

### `_removeSelectionAttribute( key ) → void` _(private)_

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

#### Parameters

* `key: string`

  Key of the attribute to remove.

#### Returns

* `void`

<a id="function-_setSelectionAttribute">

### `_setSelectionAttribute( key, value ) → void` _(private)_

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

#### Parameters

* `key: string`

  Key of the attribute to remove.

* `value: unknown`

  Attribute value.

#### Returns

* `void`

---

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