# ViewUpcastWriter

class

View upcast writer. It provides a set of methods used to manipulate non-semantic view trees.

It should be used only while working on a non-semantic view (e.g. a view created from HTML string on paste). To manipulate a view which was or is being downcasted from the the model use the [downcast writer](module_engine_view_downcastwriter-ViewDowncastWriter.md).

Read more about changing the view in the [Changing the view](../framework/architecture/editing-engine.md#changing-the-view) section of the [Editing engine architecture](../framework/architecture/editing-engine.md) guide.

Unlike `ViewDowncastWriter`, which is available in the [`View#change()`](module_engine_view_view-EditingView.md#function-change) block, `ViewUpcastWriter` can be created wherever you need it:

```typescript
const writer = new ViewUpcastWriter( viewDocument );
const text = writer.createText( 'foo!' );

writer.appendChild( text, someViewElement );
```

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

<a id="properties">

## Properties

<a id="member-document">

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

The view document instance in which this upcast writer operates.

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( document )`

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

#### Parameters

* `document: ViewDocument`

  The view document instance in which this upcast writer operates.

<a id="function-addClass">

### `addClass( className, element ) → void`

Adds specified class to the element.

```typescript
writer.addClass( 'foo', linkElement );
writer.addClass( [ 'foo', 'bar' ], linkElement );
```

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

#### Parameters

* `className: string | Array<string>`

  Single class name or array of class names which will be added.

* `element: ViewElement`

  Element for which class will be added.

#### Returns

* `void`

#### Related:

* [ViewElement#\_addClass](module_engine_view_element-ViewElement.md#function-_addClass)

<a id="function-appendChild">

### `appendChild( items, element ) → number`

Appends a child node or a list of child nodes at the end of this node and sets the parent of these nodes to this element.

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

#### Parameters

* `items: string | ViewItem | Iterable<( string | ViewItem )>`

  Items to be inserted.

* `element: ViewElement | ViewDocumentFragment`

  Element to which items will be appended.

#### Returns

* `number`

  Number of appended nodes.

#### Related:

* [ViewElement#\_appendChild](module_engine_view_element-ViewElement.md#function-_appendChild)

<a id="function-clone">

### `clone( element, deep ) → ViewElement`

Clones the provided element.

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

#### Parameters

* `element: ViewElement`

  Element to be cloned.

* `deep: boolean`

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

  Defaults to `false`

#### Returns

* `ViewElement`

  Clone of this element.

#### Related:

* [ViewElement#\_clone](module_engine_view_element-ViewElement.md#function-_clone)

<a id="function-createDocumentFragment">

### `createDocumentFragment( children? ) → ViewDocumentFragment`

Creates a new [`ViewDocumentFragment`](module_engine_view_documentfragment-ViewDocumentFragment.md) instance.

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

#### Parameters

* `children?: ViewNode | Iterable<ViewNode>`

  A list of nodes to be inserted into the created document fragment.

#### Returns

* `ViewDocumentFragment`

  The created document fragment.

<a id="function-createElement">

### `createElement( name, attrs?, children? ) → ViewElement`

Creates a new [`ViewElement`](module_engine_view_element-ViewElement.md) instance.

Attributes can be passed in various formats:

```typescript
upcastWriter.createElement( 'div', { class: 'editor', contentEditable: 'true' } ); // object
upcastWriter.createElement( 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
upcastWriter.createElement( 'div', mapOfAttributes ); // map
```

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

#### Parameters

* `name: string`

  Node name.

* `attrs?: ViewElementAttributes`

  Collection of attributes.

* `children?: ViewNode | Iterable<ViewNode>`

  A list of nodes to be inserted into created element.

#### Returns

* `ViewElement`

  Created element.

<a id="function-createPositionAfter">

### `createPositionAfter( item ) → ViewPosition`

Creates a new position after given view item.

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

#### Parameters

* `item: ViewItem`

  View item after which the position should be located.

#### Returns

* `ViewPosition`

<a id="function-createPositionAt">

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

Creates position at the given location. The location can be specified as:

* a [position](module_engine_view_position-ViewPosition.md),
* parent element and offset (offset defaults to `0`),
* parent element and `'end'` (sets position at the end of that element),
* [view item](module_engine_view_item-ViewItem.md) and `'before'` or `'after'` (sets position before or after given view item).

This method is a shortcut to other constructors such as:

* [`createPositionBefore`](#function-createPositionBefore),
* [`createPositionAfter`](#function-createPositionAfter),

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

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

* `ViewPosition`

<a id="function-createPositionBefore">

### `createPositionBefore( item ) → ViewPosition`

Creates a new position before given view item.

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

#### Parameters

* `item: ViewItem`

  View item before which the position should be located.

#### Returns

* `ViewPosition`

<a id="function-createRange">

### `createRange( start, end ) → ViewRange`

Creates a range spanning from `start` position to `end` position.

**Note:** This factory method creates it's own [`ViewPosition`](module_engine_view_position-ViewPosition.md) instances basing on passed values.

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

#### Parameters

* `start: ViewPosition`

  Start position.

* `end: ViewPosition`

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

#### Returns

* `ViewRange`

<a id="function-createRangeIn">

### `createRangeIn( element ) → ViewRange`

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.

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

#### Parameters

* `element: ViewElement | ViewDocumentFragment`

  Element which is a parent for the range.

#### Returns

* `ViewRange`

<a id="function-createRangeOn">

### `createRangeOn( item ) → ViewRange`

Creates a range that starts before given [view item](module_engine_view_item-ViewItem.md) and ends after it.

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

#### Parameters

* `item: ViewItem`

#### Returns

* `ViewRange`

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

### `createSelection( selectable?, options? ) → ViewSelection`

Creates a new [`ViewSelection`](module_engine_view_selection-ViewSelection.md) instance.

```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.
const otherSelection = writer.createSelection();
const selection = writer.createSelection( otherSelection );

// Creates selection from the document selection.
const selection = writer.createSelection( editor.editing.view.document.selection );

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

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

```typescript
// Creates backward selection.
const selection = writer.createSelection( 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 = writer.createSelection( range, { fake: true, label: 'foo' } );
```

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

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

#### Parameters

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

#### Returns

* `ViewSelection`

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

### `createSelection( selectable, placeOrOffset, options? ) → ViewSelection`

Creates a new [`ViewSelection`](module_engine_view_selection-ViewSelection.md) instance.

```typescript
// Creates collapsed selection at the position of given item and offset.
const paragraph = writer.createContainerElement( '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`, `fake` and `label`) as the last argument.

```typescript
// Creates backward selection.
const selection = writer.createSelection( 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 = writer.createSelection( element, 'in', { fake: true, label: 'foo' } );
```

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

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

#### Parameters

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

#### Returns

* `ViewSelection`

<a id="function-createText">

### `createText( data ) → ViewText`

Creates a new [`ViewText`](module_engine_view_text-ViewText.md) instance.

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

#### Parameters

* `data: string`

  The text's data.

#### Returns

* `ViewText`

  The created text node.

<a id="function-insertChild">

### `insertChild( index, items, element ) → number`

Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to this element.

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

#### Parameters

* `index: number`

  Offset at which nodes should be inserted.

* `items: ViewItem | Iterable<ViewItem>`

  Items to be inserted.

* `element: ViewElement | ViewDocumentFragment`

  Element to which items will be inserted.

#### Returns

* `number`

  Number of inserted nodes.

#### Related:

* [ViewElement#\_insertChild](module_engine_view_element-ViewElement.md#function-_insertChild)

<a id="function-remove">

### `remove( element ) → Array<ViewNode>`

Removes given element from the view structure. Will not have effect on detached elements.

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

#### Parameters

* `element: ViewNode`

  Element which will be removed.

#### Returns

* `Array<ViewNode>`

  The array containing removed nodes.

<a id="function-removeAttribute">

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

Removes attribute from the element.

```typescript
writer.removeAttribute( 'href', linkElement );
```

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

#### Parameters

* `key: string`

  Attribute key.

* `element: ViewElement`

  Element from which attribute will be removed.

#### Returns

* `void`

#### Related:

* [ViewElement#\_removeAttribute](module_engine_view_element-ViewElement.md#function-_removeAttribute)

<a id="function-removeChildren">

### `removeChildren( index, howMany, element ) → Array<ViewNode>`

Removes the given number of child nodes starting at the given index and set the parent of these nodes to `null`.

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

#### Parameters

* `index: number`

  Offset from which nodes will be removed.

* `howMany: number`

  Number of nodes to remove.

* `element: ViewElement | ViewDocumentFragment`

  Element which children will be removed.

#### Returns

* `Array<ViewNode>`

  The array containing removed nodes.

#### Related:

* [ViewElement#\_removeChildren](module_engine_view_element-ViewElement.md#function-_removeChildren)

<a id="function-removeClass">

### `removeClass( className, element ) → void`

Removes specified class from the element.

```typescript
writer.removeClass( 'foo', linkElement );
writer.removeClass( [ 'foo', 'bar' ], linkElement );
```

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

#### Parameters

* `className: string | Array<string>`

  Single class name or array of class names which will be removed.

* `element: ViewElement`

  Element from which class will be removed.

#### Returns

* `void`

#### Related:

* [ViewElement#\_removeClass](module_engine_view_element-ViewElement.md#function-_removeClass)

<a id="function-removeCustomProperty">

### `removeCustomProperty( key, element ) → boolean`

Removes a custom property stored under the given key.

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

#### Parameters

* `key: string | symbol`

  Name/key of the custom property to be removed.

* `element: ViewElement | ViewDocumentFragment`

  Element from which the custom property will be removed.

#### Returns

* `boolean`

  Returns true if property was removed.

#### Related:

* [ViewElement#\_removeCustomProperty](module_engine_view_element-ViewElement.md#function-_removeCustomProperty)

<a id="function-removeStyle">

### `removeStyle( property, element ) → void`

Removes specified style from the element.

```typescript
writer.removeStyle( 'color', element );  // Removes 'color' style.
writer.removeStyle( [ 'color', 'border-top' ], element ); // Removes both 'color' and 'border-top' styles.
```

**Note**: This method can work with normalized style names if [a particular style processor rule is enabled](module_engine_controller_datacontroller-DataController.md#function-addStyleProcessorRules). See [`StylesMap#remove()`](module_engine_view_stylesmap-StylesMap.md#function-remove) for details.

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

#### Parameters

* `property: string | Array<string>`

  Style property name or names to be removed.

* `element: ViewElement`

  Element from which style will be removed.

#### Returns

* `void`

#### Related:

* [ViewElement#\_removeStyle](module_engine_view_element-ViewElement.md#function-_removeStyle)

<a id="function-rename">

### `rename( newName, element ) → ViewElement | null`

Renames element by creating a copy of a given element but with its name changed and then moving contents of the old element to the new one.

Since this function creates a new element and removes the given one, the new element is returned to keep reference.

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

#### Parameters

* `newName: string`

  New element name.

* `element: ViewElement`

  Element to be renamed.

#### Returns

* `ViewElement | null`

  New element or null if the old element was not replaced (happens for detached elements).

<a id="function-replace">

### `replace( oldElement, newElement ) → boolean`

Replaces given element with the new one in the view structure. Will not have effect on detached elements.

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

#### Parameters

* `oldElement: ViewElement`

  Element which will be replaced.

* `newElement: ViewElement`

  Element which will be inserted in the place of the old element.

#### Returns

* `boolean`

  Whether old element was successfully replaced.

<a id="function-setAttribute">

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

Adds or overwrites element's attribute with a specified key and value.

```typescript
writer.setAttribute( 'href', 'http://ckeditor.com', linkElement );
```

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

#### Parameters

* `key: string`

  Attribute key.

* `value: unknown`

  Attribute value.

* `element: ViewElement`

  Element for which attribute will be set.

#### Returns

* `void`

#### Related:

* [ViewElement#\_setAttribute](module_engine_view_element-ViewElement.md#function-_setAttribute)

<a id="function-setCustomProperty">

### `setCustomProperty( key, value, element ) → void`

Sets a custom property on element. Unlike attributes, custom properties are not rendered to the DOM, so they can be used to add special data to elements.

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

#### Parameters

* `key: string | symbol`

  Custom property name/key.

* `value: unknown`

  Custom property value to be stored.

* `element: ViewElement | ViewDocumentFragment`

  Element for which custom property will be set.

#### Returns

* `void`

#### Related:

* [ViewElement#\_setCustomProperty](module_engine_view_element-ViewElement.md#function-_setCustomProperty)

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

### `setStyle( properties, element ) → void`

Adds style to the element.

```typescript
writer.setStyle( {
	color: 'red',
	position: 'fixed'
}, element );
```

**Note**: This method can work with normalized style names if [a particular style processor rule is enabled](module_engine_controller_datacontroller-DataController.md#function-addStyleProcessorRules). See [`StylesMap#set()`](module_engine_view_stylesmap-StylesMap.md#function-set:KEY_VALUE) for details.

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

#### Parameters

* `properties: Record<string, string>`

  Object with key - value pairs.

* `element: ViewElement`

  Element for which style will be added.

#### Returns

* `void`

#### Related:

* [ViewElement#\_setStyle](module_engine_view_element-ViewElement.md#function-_setStyle:KEY_VALUE)

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

### `setStyle( property, value, element ) → void`

Adds style to the element.

```typescript
writer.setStyle( 'color', 'red', element );
```

**Note**: This method can work with normalized style names if [a particular style processor rule is enabled](module_engine_controller_datacontroller-DataController.md#function-addStyleProcessorRules). See [`StylesMap#set()`](module_engine_view_stylesmap-StylesMap.md#function-set:KEY_VALUE) for details.

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

#### Parameters

* `property: string`

  Property name.

* `value: string`

  Value to set.

* `element: ViewElement`

  Element for which style will be added.

#### Returns

* `void`

#### Related:

* [ViewElement#\_setStyle](module_engine_view_element-ViewElement.md#function-_setStyle:KEY_VALUE)

<a id="function-unwrapElement">

### `unwrapElement( element ) → void`

Removes given element from view structure and places its children in its position. It does nothing if element has no parent.

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

#### Parameters

* `element: ViewElement`

  Element to unwrap.

#### Returns

* `void`

---

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