CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Element (engine/view)

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

class
See source

View element.

The editing engine does not define a fixed semantics of its elements (it is "DTD-free"). This is why the type of the Element need to be defined by the feature developer. When creating an element you should use one of the following methods:

Note that for view elements which are not created from the model, like elements from mutations, paste or data.set it is not possible to define the type of the element. In such cases the UpcastWriter#createElement() method should be used to create generic view elements.

Filtering

Properties

  • readonly

    _classes : undefined | TokenList

    See source

    Set of classes associated with element instance.

    Note that this is just an alias for this._attrs.get( 'class' );

  • readonly

    _styles : undefined | StylesMap

    See source

    Normalized styles.

    Note that this is just an alias for this._attrs.get( 'style' );

  • readonly

    childCount : number

    See source

    Number of element's children.

  • readonly inherited

    document : Document

    See source

    The document instance to which this node belongs.

  • readonly inherited

    index : null | number

    See source

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

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

  • readonly

    isEmpty : boolean

    See source

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

  • readonly

    name : string

    See source

    Name of the element.

  • readonly inherited

    nextSibling : null | Node

    See source

    Node's next sibling, or null if it is the last child.

  • readonly inherited

    parent : null | Element | DocumentFragment

    See source

    Parent element. Null by default. Set by _insertChild.

  • readonly inherited

    previousSibling : null | Node

    See source

    Node's previous sibling, or null if it is the first child.

  • readonly inherited

    root : Element | DocumentFragment

    See source

    Top-most ancestor of the node. If the node has no parent it is the root itself.

  • internal readonly

    _unsafeAttributesToRender : Array<string>

    See source

    A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms implemented in the DomConverter (for instance, shouldRenderAttribute) would filter them out.

    These attributes can be specified as an option when the element is created by the DowncastWriter. To check whether an unsafe an attribute should be permitted, use the shouldRenderUnsafeAttribute method.

  • private readonly

    _attrs : Map<string, string | ElementAttributeValue>

    See source

    Map of attributes, where attributes names are keys and attributes values are values.

  • private readonly

    _children : Array<Node>

    See source

    Array of child nodes.

  • private readonly

    _customProperties : Map<string | symbol, unknown>

    See source

    Map of custom properties. Custom properties can be added to element instance, will be cloned but not rendered into DOM.

Methods

  • internal

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

    See source

    Creates a view element.

    Attributes can be passed in various formats:

    new Element( viewDocument, 'div', { class: 'editor', contentEditable: 'true' } ); // object
new Element( viewDocument, 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
new Element( viewDocument, 'div', mapOfAttributes ); // map

    Parameters

    document : Document

    The document instance to which this element belongs.

    name : string

    Node name.

    [ attrs ] : ElementAttributes

    Collection of attributes.

    [ children ] : Node | Iterable<Node>

    A list of nodes to be inserted into created element.

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • findAncestor( patterns ) → null | Element

    See source

    Returns ancestor element that match specified pattern. Provided patterns should be compatible with Matcher as it is used internally.

    Parameters

    patterns : Array<MatcherPattern | ( element: Element ) => boolean>

    Patterns used to match correct ancestor. See Matcher.

    Returns

    null | Element

    Found element or null if no matching ancestor was found.

    Related:

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • 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.

  • getAttribute( key ) → undefined | string

    See source

    Gets attribute by key. If attribute is not present - returns undefined.

    Parameters

    key : string

    Attribute key.

    Returns

    undefined | string

    Attribute value.

  • getAttributeKeys() → IterableIterator<string>

    See source

    Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.

    Returns

    IterableIterator<string>

    Keys for attributes.

  • getAttributes() → IterableIterator<tuple>

    See source

    Returns iterator that iterates over this element'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 ) → undefined | Node

    See source

    Gets child at the given index.

    Parameters

    index : number

    Index of child.

    Returns

    undefined | Node

    Child node.

  • getChildIndex( node ) → number

    See source

    Gets index of the given child node. Returns -1 if child node is not found.

    Parameters

    node : Node

    Child node.

    Returns

    number

    Index of the child node.

  • getChildren() → IterableIterator<Node>

    See source

    Gets child nodes iterator.

    Returns

    IterableIterator<Node>

    Child nodes iterator.

  • getClassNames() → IterableIterator<string>

    See source

    Returns iterator that contains all class names.

    Returns

    IterableIterator<string>

  • 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

  • getCustomProperties() → IterableIterator<tuple>

    See source

    Returns an iterator which iterates over this element's custom properties. Iterator provides [ key, value ] pairs for each stored property.

    Returns

    IterableIterator<tuple>

  • getCustomProperty( key ) → unknown

    See source

    Returns the custom property value for the given key.

    Parameters

    key : string | symbol

    Returns

    unknown

  • getFillerOffset() → null | number

    See source

    Returns block filler offset or null if block filler is not needed.

    Returns

    null | number

  • getIdentity() → string

    See source

    Returns identity string based on element's name, styles, classes and other attributes. Two elements that are similar will have same identity string. It has the following format:

    'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'

    For example:

    const element = writer.createContainerElement( 'foo', {
	banana: '10',
	apple: '20',
	style: 'color: red; border-color: white;',
	class: 'baz'
} );

// returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"'
element.getIdentity();

    Note: Classes, styles and other attributes are sorted alphabetically.

    Returns

    string

  • getNormalizedStyle( property ) → undefined | StyleValue

    See source

    Returns a normalized style object or single style value.

    For an element with style set to: margin:1px 2px 3em;

    element.getNormalizedStyle( 'margin' ) );

    will return:

    {
	top: '1px',
	right: '2px',
	bottom: '3em',
	left: '2px'    // a normalized value from margin shorthand
}

    and reading for single style value:

    styles.getNormalizedStyle( 'margin-left' );

    Will return a 2px string.

    Note: This method will return normalized values only if a particular style processor rule is enabled. See StylesMap#getNormalized() for details.

    Parameters

    property : string

    Name of CSS property

    Returns

    undefined | StyleValue

  • inherited

    getPath() → Array<number>

    See source

    Gets a path to the node. The path is an array containing indices of consecutive ancestors of this node, beginning from root, down to this node's index.

    const abc = downcastWriter.createText( 'abc' );
const foo = downcastWriter.createText( 'foo' );
const h1 = downcastWriter.createElement( 'h1', null, downcastWriter.createText( 'header' ) );
const p = downcastWriter.createElement( 'p', null, [ abc, foo ] );
const div = downcastWriter.createElement( '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.

  • getStyle( property ) → undefined | string

    See source

    Returns style value for the given property name. If the style does not exist undefined is returned.

    Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#getAsString() for details.

    For an element with style set to 'margin:1px':

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

const element = view.change( writer => {
	const element = writer.createElement();
	writer.setStyle( 'margin', '1px' );
	writer.setStyle( 'margin-bottom', '3em' );

	return element;
} );

element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'

    Parameters

    property : string

    Returns

    undefined | string

  • getStyleNames( [ expand ] ) → Array<string>

    See source

    Returns an array that contains all style names.

    Parameters

    [ expand ] : boolean

    Expand shorthand style properties and return all equivalent style representations.

    Returns

    Array<string>

  • hasAttribute( key, [ token ] ) → boolean

    See source

    Returns a boolean indicating whether an attribute with the specified key exists in the element.

    Parameters

    key : string

    Attribute key.

    [ token ] : string

    Returns

    boolean

    true if attribute with the specified key exists in the element, false otherwise.

  • hasClass( className ) → boolean

    See source

    Returns true if class is present. If more then one class is provided - returns true only when all classes are present.

    element.hasClass( 'foo' ); // Returns true if 'foo' class is present.
element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.

    Parameters

    className : Array<string>

    Returns

    boolean

  • hasStyle( property ) → boolean

    See source

    Returns true if style keys are present. If more then one style property is provided - returns true only when all properties are present.

    element.hasStyle( 'color' ); // Returns true if 'border-top' style is present.
element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.

    Parameters

    property : Array<string>

    Returns

    boolean

  • inherited

    is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

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

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

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

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

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

    Parameters

    type : 'element' | 'view:element'

    Returns

    this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • inherited

    is( type ) → this is ContainerElement | EditableElement | RootEditableElement

    See source

    Checks whether this object is of type ContainerElement or its subclass.

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

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

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

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

    Parameters

    type : 'containerElement' | 'view:containerElement'

    Returns

    this is ContainerElement | EditableElement | RootEditableElement

  • inherited

    is( type ) → this is AttributeElement

    See source

    Checks whether this object is of type AttributeElement.

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

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

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

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

    Parameters

    type : 'attributeElement' | 'view:attributeElement'

    Returns

    this is AttributeElement

  • inherited

    is( type ) → this is RawElement

    See source

    Checks whether this object is of type RawElement.

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

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

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

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

    Parameters

    type : 'rawElement' | 'view:rawElement'

    Returns

    this is RawElement

  • inherited

    is( type ) → this is EmptyElement

    See source

    Checks whether this object is of type EmptyElement.

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

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

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

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

    Parameters

    type : 'emptyElement' | 'view:emptyElement'

    Returns

    this is EmptyElement

  • inherited

    is( type ) → this is EditableElement | RootEditableElement

    See source

    Checks whether this object is of type EditableElement or its subclass.

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

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

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

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

    Parameters

    type : 'editableElement' | 'view:editableElement'

    Returns

    this is EditableElement | RootEditableElement

  • inherited

    is( type ) → this is DocumentFragment

    See source

    hecks whether this object is of type DocumentFragment.

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

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

    Parameters

    type : 'documentFragment' | 'view:documentFragment'

    Returns

    this is DocumentFragment

  • inherited

    is( type ) → this is DocumentSelection

    See source

    Checks whether this object is of type DocumentSelection.

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

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

    Parameters

    type : 'documentSelection' | 'view:documentSelection'

    Returns

    this is DocumentSelection

  • inherited

    is( type ) → this is Selection | DocumentSelection

    See source

    Checks whether this object is of type Selection or DocumentSelection.

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

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

    Parameters

    type : 'selection' | 'view:selection'

    Returns

    this is Selection | DocumentSelection

  • inherited

    is( type ) → this is Range

    See source

    Checks whether this object is of type Range.

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

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

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is Range

  • inherited

    is( type ) → this is Position

    See source

    Checks whether this object is of type Position.

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

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

    Parameters

    type : 'position' | 'view:position'

    Returns

    this is Position

  • inherited

    is( type ) → this is TextProxy

    See source

    Checks whether this object is of type TextProxy.

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

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

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

    Parameters

    type : '$textProxy' | 'view:$textProxy'

    Returns

    this is TextProxy

  • inherited

    is( type ) → this is Text

    See source

    Checks whether this object is of type Text.

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

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

    Parameters

    type : '$text' | 'view:$text'

    Returns

    this is Text

  • inherited

    is( type ) → this is UIElement

    See source

    Checks whether this object is of type UIElement.

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

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

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

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

    Parameters

    type : 'uiElement' | 'view:uiElement'

    Returns

    this is UIElement

  • inherited

    is( type ) → this is RootEditableElement

    See source

    Checks whether this object is of type RootEditableElement.

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

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

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

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

    Parameters

    type : 'rootElement' | 'view:rootElement'

    Returns

    this is RootEditableElement

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

    Checks whether the object is of type EmptyElement has the specified name.

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type, name ) → boolean

    See source

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

    Type parameters

    N : extends string

    Parameters

    type : 'attributeElement' | 'view:attributeElement'
    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.

    Type parameters

    N : extends string

    Parameters

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

    Returns

    boolean

  • inherited

    is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

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

    This method is useful when processing view 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 model objects, you can prefix the type of the object with model: or view: to check, for example, if this is the model's or view's element:

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

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

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

    Parameters

    type : 'node' | 'view:node'

    Returns

    this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

  • 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 in a tree rooted in the document (is a descendant of one of its roots).

    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

  • isSimilar( otherElement ) → boolean

    See source

    Checks if this element is similar to other element. Both elements should have the same name and attributes to be considered as similar. Two similar elements can contain different set of children nodes.

    Parameters

    otherElement : Item

    Returns

    boolean

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

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

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

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

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

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

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

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • shouldRenderUnsafeAttribute( attributeName ) → boolean

    See source

    Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms like shouldRenderAttribute say it should not.

    Unsafe attribute names can be specified when creating an element via DowncastWriter.

    Parameters

    attributeName : string

    The name of the attribute to be checked.

    Returns

    boolean

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

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

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

    Parameters

    [ event ] : string

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

    [ emitter ] : Emitter

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

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

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

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

    Parameters

    [ emitter ] : Emitter

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

    [ event ] : string

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

    [ callback ] : Function

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

    Returns

    void

  • inherited

    toJSON() → unknown

    See source

    Custom toJSON method to solve child-parent circular dependencies.

    Returns

    unknown

    Clone of this object with the parent property removed.

  • internal

    _addClass( className ) → void

    See source

    Adds specified class.

    element._addClass( 'foo' ); // Adds 'foo' class.
element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.

    Parameters

    className : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal

    _appendChild( items ) → number

    See source

    Insert 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.

    Parameters

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

    Items to be inserted.

    Returns

    number

    Number of appended nodes.

    Fires

    Related:

  • internal

    _canMergeAttributesFrom( otherElement ) → boolean

    See source

    Verify if the given element can be merged without conflicts into the element.

    Note that this method is extended by the AttributeElement implementation.

    This method is used by the DowncastWriter while down-casting an AttributeElement to merge it with other AttributeElement.

    Parameters

    otherElement : Element

    Returns

    boolean

    Returns true if elements can be merged.

  • internal

    _canSubtractAttributesOf( otherElement ) → boolean

    See source

    Verify if the given element attributes can be fully subtracted from the element.

    Note that this method is extended by the AttributeElement implementation.

    This method is used by the DowncastWriter while down-casting an AttributeElement to unwrap the AttributeElement.

    Parameters

    otherElement : Element

    Returns

    boolean

    Returns true if elements attributes can be fully subtracted.

  • internal

    _clone( deep ) → this

    See source

    Clones provided element.

    Parameters

    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

    this

    Clone of this element.

  • internal

    _collectAttributesMatch( patterns, match, [ exclude ] ) → boolean

    See source

    Used by the Matcher to collect matching attribute tuples (attribute name and optional token).

    Normalized patterns can be used in following ways:

    • to match any attribute name with any or no value:
    patterns: [
	[ true, true ]
]
    • to match a specific attribute with any value:
    patterns: [
	[ 'required', true ]
]
    • to match an attribute name with a RegExp with any value:
    patterns: [
	[ /h[1-6]/, true ]
]

    - to match a specific attribute with the exact value:

    patterns: [
	[ 'rel', 'nofollow' ]
]

    - to match a specific attribute with a value matching a RegExp:

    patterns: [
	[ 'src', /^https/ ]
]

    - to match an attribute name with a RegExp and the exact value:

    patterns: [
	[ /^data-property-/, 'foobar' ],
]

    - to match an attribute name with a RegExp and match a value with another RegExp:

    patterns: [
	[ /^data-property-/, /^foo/ ]
]

    - to match a specific style property with the value matching a RegExp:

    patterns: [
	[ 'style', 'font-size', /px$/ ]
]

    - to match a specific class (class attribute is tokenized so it matches tokens individually):

    patterns: [
	[ 'class', 'foo' ]
]

    Parameters

    patterns : Array<NormalizedPropertyPattern>

    An array of normalized patterns (tuples of 2 or 3 items depending on if tokenized attribute value match is needed).

    match : Array<tuple>

    An array to populate with matching tuples.

    [ exclude ] : Array<string>

    Array of attribute names to exclude from match.

    Returns

    boolean

    true if element matches all patterns. The matching tuples are pushed to the match array.

  • internal inherited

    _fireChange( type, node, [ data ] = { data.index } ) → void

    See source

    Parameters

    type : ChangeType

    Type of the change.

    node : Node

    Changed node.

    [ data ] : object

    Additional data.

    Properties
    data.index : number

    Returns

    void

    Fires

  • internal

    _getConsumables( [ key ], [ token ] ) → NormalizedConsumables

    See source

    Used by the ViewConsumable to collect the NormalizedConsumables for the element.

    When key and token parameters are provided the output is filtered for the specified attribute and it's tokens and related tokens.

    Parameters

    [ key ] : string

    Attribute name.

    [ token ] : string

    Reference token to collect all related tokens.

    Returns

    NormalizedConsumables

  • internal

    _insertChild( index, items ) → number

    See source

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

    Parameters

    index : number

    Position where nodes should be inserted.

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

    Items to be inserted.

    Returns

    number

    Number of inserted nodes.

    Fires

    Related:

  • internal

    _mergeAttributesFrom( otherElement ) → void

    See source

    Merges attributes of a given element into the element. This includes also tokenized attributes like style and class.

    Note that you should make sure there are no conflicts before merging (see _canMergeAttributesFrom).

    This method is used by the DowncastWriter while down-casting an AttributeElement to merge it with other AttributeElement.

    Parameters

    otherElement : Element

    Returns

    void

  • internal inherited

    _remove() → void

    See source

    Removes node from parent.

    Returns

    void

  • internal

    _removeAttribute( key, [ tokens ] ) → boolean

    See source

    Removes attribute from the element.

    Parameters

    key : string

    Attribute key.

    [ tokens ] : ArrayOrItem<string>

    Attribute value tokens to remove. The whole attribute is removed if not specified.

    Returns

    boolean

    Returns true if an attribute existed and has been removed.

    Fires

    Related:

  • internal

    _removeChildren( index, howMany ) → Array<Node>

    See source

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

    Parameters

    index : number

    Number of the first node to remove.

    howMany : number

    Number of nodes to remove.

    Defaults to 1

    Returns

    Array<Node>

    The array of removed nodes.

    Fires

    Related:

  • internal

    _removeClass( className ) → void

    See source

    Removes specified class.

    element._removeClass( 'foo' );  // Removes 'foo' class.
element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.

    Parameters

    className : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal

    _removeCustomProperty( key ) → boolean

    See source

    Removes the custom property stored under the given key.

    Parameters

    key : string | symbol

    Returns

    boolean

    Returns true if property was removed.

    Related:

  • internal

    _removeStyle( property ) → void

    See source

    Removes specified style.

    element._removeStyle( 'color' );  // Removes 'color' style.
element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.

    Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#remove() for details.

    Parameters

    property : ArrayOrItem<string>

    Returns

    void

    Fires

    Related:

  • internal

    _setAttribute( key, value, overwrite ) → void

    See source

    Adds or overwrite attribute with a specified key and value.

    Parameters

    key : string

    Attribute key.

    value : unknown

    Attribute value.

    overwrite : boolean

    Whether tokenized attribute should override the attribute value or just add a token.

    Defaults to true

    Returns

    void

    Fires

    Related:

  • internal

    _setCustomProperty( key, value ) → void

    See source

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

    Parameters

    key : string | symbol
    value : unknown

    Returns

    void

    Related:

  • internal

    _setStyle( properties ) → void

    See source

    Adds style to the element.

    element._setStyle( {
	color: 'red',
	position: 'fixed'
} );

    Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

    Parameters

    properties : Record<string, string>

    Object with key - value pairs.

    Returns

    void

    Fires

    Related:

  • internal

    _setStyle( property, value ) → void

    See source

    Adds style to the element.

    element._setStyle( 'color', 'red' );

    Note: This method can work with normalized style names if a particular style processor rule is enabled. See StylesMap#set() for details.

    Parameters

    property : string

    Property name.

    value : string

    Value to set.

    Returns

    void

    Fires

    Related:

  • internal

    _subtractAttributesOf( otherElement ) → void

    See source

    Removes (subtracts) corresponding attributes of the given element from the element. This includes also tokenized attributes like style and class. All attributes, classes and styles from given element should be present inside the element being unwrapped.

    Note that you should make sure all attributes could be subtracted before subtracting them (see _canSubtractAttributesOf).

    This method is used by the DowncastWriter while down-casting an AttributeElement to unwrap the AttributeElement.

    Parameters

    otherElement : Element

    Returns

    void

  • private

    _parseAttributes( [ attrs ] ) → Map<string, string | ElementAttributeValue>

    See source

    Parses attributes provided to the element constructor before they are applied to an element. If attributes are passed as an object (instead of Iterable), the object is transformed to the map. Attributes with null value are removed. Attributes with non-String value are converted to String.

    Parameters

    [ attrs ] : ElementAttributes

    Attributes to parse.

    Returns

    Map<string, string | ElementAttributeValue>

    Parsed attributes.

Events

  • inherited

    change( eventInfo, changedNode, [ data ] )

    See source

    Fired when list of elements children, attributes or text changes.

    Change event is bubbled – it is fired on all ancestors.

    All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

    If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node
    [ data ] : object

  • inherited

    change:attributes( eventInfo, changedNode, [ data ] )

    See source

    Fired when list of elements children, attributes or text changes.

    Change event is bubbled – it is fired on all ancestors.

    All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

    If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node
    [ data ] : object

  • inherited

    change:children( eventInfo, changedNode, [ data ] )

    See source

    Fired when list of elements children, attributes or text changes.

    Change event is bubbled – it is fired on all ancestors.

    All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

    If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node
    [ data ] : object

  • inherited

    change:text( eventInfo, changedNode, [ data ] )

    See source

    Fired when list of elements children, attributes or text changes.

    Change event is bubbled – it is fired on all ancestors.

    All change events as the first parameter receive the node that has changed (the node for which children, attributes or text changed).

    If change:children event is fired, there is an additional second parameter, which is an object with additional data related to change.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    changedNode : Node
    [ data ] : object