Home/CKEditor 5/API

Element (engine/model)

@ckeditor/ckeditor5-engine/src/model/element

class

Hierarchy

Node
- Element

Subclasses

RootElement

See source

Model element. Type of node that has a name and child nodes.

Important: see Node to read about restrictions using Element and Node API.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

childCount : Number

readonly

Number of this element's children.

See source
endOffset : Number | null

readonly inherited

Offset at which this node ends in it's parent. It is equal to the sum of this node's start offset and offset size. Equals to null if the node has no parent.

See source
index : Number | null

readonly inherited

Index of this node in it's parent or null if the node has no parent.

See source

Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
isEmpty : Boolean

readonly

Is true if there are no nodes inside this element, false otherwise.

See source
maxOffset : Number

readonly

Sum of offset sizes of all of this element's children.

See source
name : String

readonly

Element name.

See source
nextSibling : Node | null

readonly inherited

Node's next sibling or null if the node is a last child of it's parent or if the node has no parent.

See source
offsetSize : Number

readonly inherited

Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent. It is important for position. When node has offsetSize greater than 1, position can be placed between that node start and end. offsetSize greater than 1 is for nodes that represents more than one entity, i.e. text node.

See source
parent : Element | DocumentFragment | null

readonly inherited

Parent of this node. It could be Element or DocumentFragment. Equals to null if the node has no parent.

See source
previousSibling : Node | null

readonly inherited

Node's previous sibling or null if the node is a first child of it's parent or if the node has no parent.

See source
root : Node | DocumentFragment

readonly inherited

The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part of DocumentFragment, it's root is equal to that DocumentFragment.

See source
startOffset : Number | null

readonly inherited

Offset at which this node starts in it's parent. It is equal to the sum of offsetSize of all it's previous siblings. Equals to null if node has no parent.

See source

Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
_attrs : Map

private inherited

Attributes set on this node.

See source
_children : NodeList

private

List of children nodes.

See source

Methods

constructor( name, [ attrs ], [ children ] )

protected

Creates a model element.

See source

Note: Constructor of this class shouldn't be used directly in the code. Use the createElement method instead.

Parameters

name : String

Element's name.

[ attrs ] : Object

Element's attributes. See toMap for a list of accepted values.

[ children ] : Node | Iterable.<Node>

One or more nodes to be inserted as children of created element.
findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | null

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

See source

Parameters

parentName : String

The name of the parent element to find.

[ options ] : Object

Options object.

Properties

[ options.includeSelf ] : Boolean

When set to true this node will be also included while searching.

Defaults to false

Returns

Element | null
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array

inherited

Returns ancestors array of this node.

See source

Parameters

options : Object

Options object.

Properties

[ options.includeSelf ] : Boolean

When set to true this node will be also included in parent's array.

Defaults to false

[ options.parentFirst ] : Boolean

When set to true, array will be sorted from node's parent to root element, otherwise root element will be the first item in the array.

Defaults to false

Returns

Array

Array with ancestors.
getAttribute( key ) → *

inherited

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

See source

Parameters

key : String

Key of attribute to look for.

Returns

*

Attribute value or undefined.
getAttributeKeys() → Iterable.<String>

inherited

Returns iterator that iterates over this node's attribute keys.

See source

Returns

Iterable.<String>
getAttributes() → Iterable.<*>

inherited

Returns iterator that iterates over this node's attributes.

See source

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

Returns

Iterable.<*>
getChild( index ) → Node

Gets the child at the given index.

See source

Parameters

index : Number

Index of child.

Returns

Node

Child node.
getChildIndex( node ) → Number

Returns an index of the given child node. Returns null if given node is not a child of this element.

See source

Parameters

node : Node

Child node to look for.

Returns

Number

Child node's index in this element.
getChildStartOffset( node ) → Number

Returns the starting offset of given child. Starting offset is equal to the sum of offset sizes of all node's siblings that are before it. Returns null if given node is not a child of this element.

See source

Parameters

node : Node

Child node to look for.

Returns

Number

Child node's starting offset.
getChildren() → Iterable.<Node>

Returns an iterator that iterates over all of this element's children.

See source

Returns

Iterable.<Node>
getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null

inherited

Returns a Element or DocumentFragment which is a common ancestor of both nodes.

See source

Parameters

node : Node

The second node.

options : Object

Options object.

Properties

[ options.includeSelf ] : Boolean

When set to true both nodes will be considered "ancestors" too. Which means that if e.g. node A is inside B, then their common ancestor will be B.

Defaults to false

Returns

Element | DocumentFragment | null
getNodeByPath( relativePath ) → Node
Returns a descendant node by its path relative to this element.

See source
```
// <this>a<b>c</b></this>
this.getNodeByPath( [ 0 ] );     // -> "a"
this.getNodeByPath( [ 1 ] );     // -> <b>
this.getNodeByPath( [ 1, 0 ] );  // -> "c"
```
Parameters

relativePath : Array.<Number>

Path of the node to find, relative to this element.

Returns

Node

`getPath() → Array.<Number>`

inherited

Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node, beginning from root, down to this node's starting offset. The path can be used to create Position instance.

See source

const abc = new Text( 'abc' );
const foo = new Text( 'foo' );
const h1 = new Element( 'h1', null, new Text( 'header' ) );
const p = new Element( 'p', null, [ abc, foo ] );
const div = new Element( 'div', null, [ h1, p ] );
foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
h1.getPath(); // Returns [ 0 ].
div.getPath(); // Returns [].

Returns

Array.<Number>: The path.

hasAttribute( key ) → Boolean

inherited

Checks if the node has an attribute with given key.

See source

Parameters

key : String

Key of attribute to check.

Returns

Boolean

true if attribute with given key is set on node, false otherwise.
is( type, [ name ] ) → Boolean
Checks whether this object is of the given.

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

element.is( 'view:element' ); // -> false
element.is( 'documentSelection' ); // -> false
```
Assuming that the object being checked is an element, you can also check its name:
```
element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
element.is( 'element', 'imageBlock' ); // -> same as above
text.is( 'element', 'imageBlock' ); -> false
```
Check the entire list of model objects which implement the is() method.

Parameters

type : String

Type to check.

[ name ] : String

Element name.

Returns

Boolean
isAfter( node ) → Boolean

inherited

Returns whether this node is after given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

See source

Parameters

node : Node

Node to compare with.

Returns

Boolean
isAttached() → Boolean

inherited

Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).

See source

Returns

Boolean
isBefore( node ) → Boolean

inherited

Returns whether this node is before given node. false is returned if nodes are in different trees (for example, in different DocumentFragments).

See source

Parameters

node : Node

Node to compare with.

Returns

Boolean

`offsetToIndex( offset ) → Number`

Returns index of a node that occupies given offset. If given offset is too low, returns 0. If given offset is too high, returns index after last child.

See source

const textNode = new Text( 'foo' );
const pElement = new Element( 'p' );
const divElement = new Element( [ textNode, pElement ] );
divElement.offsetToIndex( -1 ); // Returns 0, because offset is too low.
divElement.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
divElement.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
divElement.offsetToIndex( 2 ); // Returns 0.
divElement.offsetToIndex( 3 ); // Returns 1.
divElement.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.

Parameters

offset : Number: Offset to look for.

Returns

Number

toJSON() → Object

inherited

Converts Node to plain object and returns it.

See source

Returns

Object

Node converted to plain object.
_appendChild( nodes )

protected
Inserts one or more nodes at the end of this element.

See source
Parameters

nodes : Item | Iterable.<Item>

Nodes to be inserted.

Related:
- Writer#append
_clearAttributes()

protected inherited
Removes all attributes from the node.

See source
Related:
- Writer#clearAttributes
_clone() → Node

protected inherited

Creates a copy of this node, that is a node with exactly same attributes, and returns it.

See source

Returns

Node

Node with same attributes as this node.
_insertChild( index, items )

protected
Inserts one or more nodes at the given index and sets parent of these nodes to this element.

See source
Parameters

index : Number

Index at which nodes should be inserted.

items : Item | Iterable.<Item>

Items to be inserted.

Related:
- Writer#insert
_remove()

protected inherited
Removes this node from it's parent.

See source
Related:
- Writer#remove
_removeAttribute( key ) → Boolean

protected inherited
Removes an attribute with given key from the node.

See source
Parameters

key : String

Key of attribute to remove.

Returns

Boolean

true if the attribute was set on the element, false otherwise.

Related:
- Writer#removeAttribute
_removeChildren( index, [ howMany ] ) → Array.<Node>

protected
Removes one or more nodes starting at the given index and sets parent of these nodes to null.

See source
Parameters

index : Number

Index of the first node to remove.

[ howMany ] : Number

Number of nodes to remove.

Defaults to 1

Returns

Array.<Node>

Array containing removed nodes.

Related:
- Writer#remove
_setAttribute( key, value )

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

See source
Parameters

key : String

Key of attribute to set.

value : *

Attribute value.

Related:
- Writer#setAttribute
_setAttributesTo( [ attrs ] )

protected inherited
Removes all attributes from the node and sets given attributes.

See source
Parameters

[ attrs ] : Object

Attributes to set. See toMap for a list of accepted values.

Related:
- Writer#setAttributes

Static methods

fromJSON( json ) → Element

static

Creates an Element instance from given plain object (i.e. parsed JSON string). Converts Element children to proper nodes.

See source

Parameters

json : Object

Plain object to be converted to Element.

Returns

Element

Element instance created using given plain object.

Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.

Element (engine/model)

Filtering

Properties

childCount : Numbermodule:engine/model/element~Element#childCount

endOffset : Number | nullmodule:engine/model/element~Element#endOffset

index : Number | nullmodule:engine/model/element~Element#index

isEmpty : Booleanmodule:engine/model/element~Element#isEmpty

maxOffset : Numbermodule:engine/model/element~Element#maxOffset

name : Stringmodule:engine/model/element~Element#name

nextSibling : Node | nullmodule:engine/model/element~Element#nextSibling

offsetSize : Numbermodule:engine/model/element~Element#offsetSize

parent : Element | DocumentFragment | nullmodule:engine/model/element~Element#parent

previousSibling : Node | nullmodule:engine/model/element~Element#previousSibling

root : Node | DocumentFragmentmodule:engine/model/element~Element#root

startOffset : Number | nullmodule:engine/model/element~Element#startOffset

_attrs : Mapmodule:engine/model/element~Element#_attrs

_children : NodeListmodule:engine/model/element~Element#_children

Methods

constructor( name, [ attrs ], [ children ] )module:engine/model/element~Element#constructor

Parameters

findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | nullmodule:engine/model/element~Element#findAncestor

Parameters

Returns

getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Arraymodule:engine/model/element~Element#getAncestors

Parameters

Returns

getAttribute( key ) → *module:engine/model/element~Element#getAttribute

Parameters

Returns

getAttributeKeys() → Iterable.<String>module:engine/model/element~Element#getAttributeKeys

Returns

getAttributes() → Iterable.<*>module:engine/model/element~Element#getAttributes

Returns

getChild( index ) → Nodemodule:engine/model/element~Element#getChild

Parameters

Returns

getChildIndex( node ) → Numbermodule:engine/model/element~Element#getChildIndex

Parameters

Returns

getChildStartOffset( node ) → Numbermodule:engine/model/element~Element#getChildStartOffset

Parameters

Returns

getChildren() → Iterable.<Node>module:engine/model/element~Element#getChildren

Returns

getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | nullmodule:engine/model/element~Element#getCommonAncestor

Parameters

Returns

getNodeByPath( relativePath ) → Nodemodule:engine/model/element~Element#getNodeByPath

Parameters

Returns

getPath() → Array.<Number>module:engine/model/element~Element#getPath

Returns

hasAttribute( key ) → Booleanmodule:engine/model/element~Element#hasAttribute

Parameters

Returns

is( type, [ name ] ) → Booleanmodule:engine/model/element~Element#is

Parameters

Returns

isAfter( node ) → Booleanmodule:engine/model/element~Element#isAfter

Parameters

Returns

isAttached() → Booleanmodule:engine/model/element~Element#isAttached

Returns

isBefore( node ) → Booleanmodule:engine/model/element~Element#isBefore

Parameters

Returns

offsetToIndex( offset ) → Numbermodule:engine/model/element~Element#offsetToIndex

Parameters

Returns

toJSON() → Objectmodule:engine/model/element~Element#toJSON

Returns

_appendChild( nodes )module:engine/model/element~Element#_appendChild

Parameters

Related:

_clearAttributes()module:engine/model/element~Element#_clearAttributes

Related:

_clone() → Nodemodule:engine/model/element~Element#_clone

Returns

_insertChild( index, items )module:engine/model/element~Element#_insertChild

Parameters

`childCount : Number`

`endOffset : Number | null`

`index : Number | null`

`isEmpty : Boolean`

`maxOffset : Number`

`name : String`

`nextSibling : Node | null`

`offsetSize : Number`

`parent : Element | DocumentFragment | null`

`previousSibling : Node | null`

`root : Node | DocumentFragment`

`startOffset : Number | null`

`_attrs : Map`

`_children : NodeList`

`constructor( name, [ attrs ], [ children ] )`

`findAncestor( parentName, [ options ] = { [options.includeSelf] } ) → Element | null`

`getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array`

`getAttribute( key ) → *`

`getAttributeKeys() → Iterable.<String>`

`getAttributes() → Iterable.<*>`

`getChild( index ) → Node`

`getChildIndex( node ) → Number`

`getChildStartOffset( node ) → Number`

`getChildren() → Iterable.<Node>`

`getCommonAncestor( node, options = { [options.includeSelf] } ) → Element | DocumentFragment | null`

`getNodeByPath( relativePath ) → Node`

`getPath() → Array.<Number>`

`hasAttribute( key ) → Boolean`

`is( type, [ name ] ) → Boolean`

`isAfter( node ) → Boolean`

`isAttached() → Boolean`

`isBefore( node ) → Boolean`

`offsetToIndex( offset ) → Number`

`toJSON() → Object`

`_appendChild( nodes )`

`_clearAttributes()`

`_clone() → Node`

`_insertChild( index, items )`

`_remove()`

`_removeAttribute( key ) → Boolean`

`_removeChildren( index, [ howMany ] ) → Array.<Node>`

`_setAttribute( key, value )`

`_setAttributesTo( [ attrs ] )`

`fromJSON( json ) → Element`