CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Element (engine/model)

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

class
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

Properties

  • readonly

    childCount : number

    See source

    Number of this element's children.

  • readonly inherited

    document : null | Document

    See source

    Document that owns this root element.

  • readonly inherited

    endOffset : null | number

    See source

    Offset at which this node ends in its 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.

  • readonly inherited

    index : null | number

    See source

    Index of this node in its parent or null if the node has no parent.

  • readonly

    isEmpty : boolean

    See source

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

  • readonly

    maxOffset : number

    See source

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

  • readonly

    name : string

    See source

    Element name.

  • readonly inherited

    nextSibling : null | Node

    See source

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

  • readonly inherited

    offsetSize : number

    See source

    Offset size of this node.

    Represents how much "offset space" is occupied by the node in its 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. a text node.

  • readonly inherited

    parent : null | Element | DocumentFragment

    See source

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

  • readonly inherited

    previousSibling : null | Node

    See source

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

  • readonly inherited

    root : Node | DocumentFragment

    See source

    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.

  • readonly inherited

    rootName : undefined | string

    See source

    Unique root name used to identify this root element by Document.

  • readonly inherited

    startOffset : null | number

    See source

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

  • internal inherited

    _index : null | number

    See source

    Index of this node in its parent or null if the node has no parent.

  • internal inherited

    _startOffset : null | number

    See source

    Offset at which this node starts in its parent or null if the node has no parent.

  • private readonly

    _children : NodeList

    See source

    List of children nodes.

Methods

  • internal

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

    See source

    Creates a model element.

    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 ] : NodeAttributes

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

    [ children ] : string | Item | Iterable<( string | Item )>

    One or more nodes to be inserted as children of created element.

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

    See source

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

    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 {}

    Returns

    null | Element

  • inherited

    getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>

    See source

    Returns ancestors array of this node.

    Parameters

    options : object

    Options object.

    Properties
    [ options.includeSelf ] : boolean

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

    [ 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 {}

    Returns

    Array<Node | DocumentFragment>

    Array with ancestors.

  • inherited

    getAttribute( key ) → unknown

    See source

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

    Parameters

    key : string

    Key of attribute to look for.

    Returns

    unknown

    Attribute value or undefined.

  • inherited

    getAttributeKeys() → IterableIterator<string>

    See source

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

    Returns

    IterableIterator<string>

  • inherited

    getAttributes() → IterableIterator<tuple>

    See source

    Returns iterator that iterates over this node's attributes.

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

    Returns

    IterableIterator<tuple>

  • getChild( index ) → null | Node

    See source

    Gets the child at the given index. Returns null if incorrect index was passed.

    Parameters

    index : number

    Index in this element.

    Returns

    null | Node

    Child node.

  • getChildAtOffset( offset ) → null | Node

    See source

    Gets the child at the given offset. Returns null if incorrect index was passed.

    Parameters

    offset : number

    Offset in this element.

    Returns

    null | Node

    Child node.

  • getChildIndex( node ) → null | number

    See source

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

    Parameters

    node : Node

    Child node to look for.

    Returns

    null | number

    Child node's index in this element.

  • getChildStartOffset( node ) → null | number

    See source

    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.

    Parameters

    node : Node

    Child node to look for.

    Returns

    null | number

    Child node's starting offset.

  • getChildren() → IterableIterator<Node>

    See source

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

    Returns

    IterableIterator<Node>

  • inherited

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

    See source

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

    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 {}

    Returns

    null | Element | DocumentFragment

  • getNodeByPath( relativePath ) → Node

    See source

    Returns a descendant node by its path relative to this element.

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

  • inherited

    getPath() → Array<number>

    See source

    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.

    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>

  • inherited

    hasAttribute( key ) → boolean

    See source

    Checks if the node has an attribute with given key.

    Parameters

    key : string

    Key of attribute to check.

    Returns

    boolean

    true if attribute with given key is set on node, false otherwise.

  • inherited

    is( type ) → this is Element | RootElement

    See source

    Checks whether the object is of type Element or its subclass.

    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
text.is( 'element', 'imageBlock' ); -> false

    Parameters

    type : 'element' | 'model:element'

    Returns

    this is Element | RootElement

  • inherited

    is( type ) → this is Text

    See source

    Checks whether the object is of type Text.

    text.is( '$text' ); // -> true
text.is( 'node' ); // -> true
text.is( 'model:$text' ); // -> true
text.is( 'model:node' ); // -> true

text.is( 'view:$text' ); // -> false
text.is( 'documentSelection' ); // -> false

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

    Parameters

    type : '$text' | 'model:$text'

    Returns

    this is Text

  • inherited

    is( type ) → this is RootElement

    See source

    Checks whether the object is of type RootElement.

    rootElement.is( 'rootElement' ); // -> true
rootElement.is( 'element' ); // -> true
rootElement.is( 'node' ); // -> true
rootElement.is( 'model:rootElement' ); // -> true
rootElement.is( 'model:element' ); // -> true
rootElement.is( 'model:node' ); // -> true

rootElement.is( 'view:element' ); // -> false
rootElement.is( 'documentFragment' ); // -> false

    Assuming that the object being checked is an element, you can also check its name:

    rootElement.is( 'rootElement', '$root' ); // -> same as above

    Parameters

    type : 'rootElement' | 'model:rootElement'

    Returns

    this is RootElement

  • inherited

    is( type ) → this is LiveRange

    See source

    Checks whether the object is of type LiveRange.

    liveRange.is( 'range' ); // -> true
liveRange.is( 'model:range' ); // -> true
liveRange.is( 'liveRange' ); // -> true
liveRange.is( 'model:liveRange' ); // -> true

liveRange.is( 'view:range' ); // -> false
liveRange.is( 'documentSelection' ); // -> false

    Parameters

    type : 'liveRange' | 'model:liveRange'

    Returns

    this is LiveRange

  • inherited

    is( type ) → this is DocumentFragment

    See source

    Checks whether the object is of type DocumentFragment.

    docFrag.is( 'documentFragment' ); // -> true
docFrag.is( 'model:documentFragment' ); // -> true

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

    Parameters

    type : 'documentFragment' | 'model:documentFragment'

    Returns

    this is DocumentFragment

  • inherited

    is( type ) → this is Range | LiveRange

    See source

    Checks whether the object is of type Range or its subclass.

    range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true

range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false

    Parameters

    type : 'range' | 'model:range'

    Returns

    this is Range | LiveRange

  • inherited

    is( type ) → this is LivePosition

    See source

    Checks whether the object is of type LivePosition.

    livePosition.is( 'position' ); // -> true
livePosition.is( 'model:position' ); // -> true
livePosition.is( 'liveposition' ); // -> true
livePosition.is( 'model:livePosition' ); // -> true

livePosition.is( 'view:position' ); // -> false
livePosition.is( 'documentSelection' ); // -> false

    Parameters

    type : 'livePosition' | 'model:livePosition'

    Returns

    this is LivePosition

  • inherited

    is( type ) → this is Position | LivePosition

    See source

    Checks whether the object is of type Position or its subclass.

    position.is( 'position' ); // -> true
position.is( 'model:position' ); // -> true

position.is( 'view:position' ); // -> false
position.is( 'documentSelection' ); // -> false

    Parameters

    type : 'position' | 'model:position'

    Returns

    this is Position | LivePosition

  • inherited

    is( type ) → this is Marker

    See source

    Checks whether the object is of type Marker.

    marker.is( 'marker' ); // -> true
marker.is( 'model:marker' ); // -> true

marker.is( 'view:element' ); // -> false
marker.is( 'documentSelection' ); // -> false

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type RootElement and has the specified name.

    rootElement.is( 'rootElement', '$root' );

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'model:rootElement'
    name : N

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type Element or its subclass and has the specified name.

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

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'model:element'
    name : N

    Returns

    boolean

  • inherited

    is( type ) → this is TextProxy

    See source

    Checks whether the object is of type TextProxy.

    textProxy.is( '$textProxy' ); // -> true
textProxy.is( 'model:$textProxy' ); // -> true

textProxy.is( 'view:$textProxy' ); // -> false
textProxy.is( 'range' ); // -> false

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

    Parameters

    type : '$textProxy' | 'model:$textProxy'

    Returns

    this is TextProxy

  • inherited

    is( type ) → this is DocumentSelection

    See source

    Checks whether the object is of type DocumentSelection.

    selection.is( 'selection' ); // -> true
selection.is( 'documentSelection' ); // -> true
selection.is( 'model:selection' ); // -> true
selection.is( 'model:documentSelection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'element' ); // -> false
selection.is( 'node' ); // -> false

    Parameters

    type : 'documentSelection' | 'model:documentSelection'

    Returns

    this is DocumentSelection

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether the object is of type Selection or DocumentSelection.

    selection.is( 'selection' ); // -> true
selection.is( 'model:selection' ); // -> true

selection.is( 'view:selection' ); // -> false
selection.is( 'range' ); // -> false

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is Selection | DocumentSelection

  • inherited

    is( type ) → this is Node | Text | Element | RootElement

    See source

    Checks whether the object is of type Node or its subclass.

    This method is useful when processing model objects that are of unknown type. For example, a function may return a DocumentFragment or a Node that can be either a text node or an element. This method can be used to check what kind of object is returned.

    someObject.is( 'element' ); // -> true if this is an element
someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
someObject.is( 'documentFragment' ); // -> true if this is a document fragment

    Since this method is also available on a range of view objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:

    modelElement.is( 'model:element' ); // -> true
modelElement.is( 'view:element' ); // -> false

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

    imageElement.is( 'element', 'imageBlock' ); // -> true
imageElement.is( 'element', 'imageBlock' ); // -> same as above
imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is Node | Text | Element | RootElement

  • inherited

    isAfter( node ) → boolean

    See source

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean

  • inherited

    isAttached() → boolean

    See source

    Returns true if the node is inside a document root that is attached to the document.

    Returns

    boolean

  • inherited

    isBefore( node ) → boolean

    See source

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

    Parameters

    node : Node

    Node to compare with.

    Returns

    boolean

  • offsetToIndex( offset ) → number

    See source

    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.

    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

    Returns

    number

  • toJSON() → unknown

    See source

    Converts Element instance to plain object and returns it. Takes care of converting all of this element's children.

    Returns

    unknown

    Element instance converted to plain object.

  • internal

    _appendChild( nodes ) → void

    See source

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

    Parameters

    nodes : string | Item | Iterable<( string | Item )>

    Nodes to be inserted.

    Returns

    void

    Related:

  • internal inherited

    _clearAttributes() → void

    See source

    Removes all attributes from the node.

    Returns

    void

    Related:

  • internal

    _clone( deep ) → Element

    See source

    Creates a copy of this 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.

    Parameters

    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 false

    Returns

    Element

  • internal

    _insertChild( index, items ) → void

    See source

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

    Parameters

    index : number

    Index at which nodes should be inserted.

    items : string | Item | Iterable<( string | Item )>

    Items to be inserted.

    Returns

    void

    Related:

  • internal inherited

    _remove() → void

    See source

    Removes this node from its parent.

    Returns

    void

    Related:

  • internal inherited

    _removeAttribute( key ) → boolean

    See source

    Removes an attribute with given key from the node.

    Parameters

    key : string

    Key of attribute to remove.

    Returns

    boolean

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

    Related:

  • internal

    _removeChildren( index, howMany ) → Array<Node>

    See source

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

    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:

  • internal

    _removeChildrenArray( nodes ) → void

    See source

    Removes children nodes provided as an array and sets the parent of these nodes to null.

    These nodes do not need to be direct siblings.

    This method is faster than removing nodes one by one, as it recalculates offsets only once.

    Parameters

    nodes : Array<Node>

    Array of nodes.

    Returns

    void

  • internal inherited

    _setAttribute( key, value ) → void

    See source

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

    Parameters

    key : string

    Key of attribute to set.

    value : unknown

    Attribute value.

    Returns

    void

    Related:

  • internal inherited

    _setAttributesTo( attrs ) → void

    See source

    Removes all attributes from the node and sets given attributes.

    Parameters

    attrs : NodeAttributes

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

    Returns

    void

    Related:

Static methods

  • static

    fromJSON( json ) → Element

    See source

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

    Parameters

    json : any

    Plain object to be converted to Element.

    Returns

    Element

    Element instance created using given plain object.