Element

Element is the most general base class from which all element objects (i.e., objects that represent elements) in a Document inherit. It only has methods and properties common to all kinds of elements. More specific classes inherit from Element.

For example, the HTMLElement interface is the base interface for HTML elements. Similarly, the SVGElement interface is the basis for all SVG elements, and the MathMLElement interface is the base interface for MathML elements. Most functionality is specified further down the class hierarchy.

Languages outside the realm of the Web platform, like XUL through the XULElement interface, also implement Element.

Instance properties

Element inherits properties from its parent interface, Node, and by extension that interface's parent, EventTarget.

• Element.activeViewTransition
  • : Returns a ViewTransition instance representing the view transition currently active on an element.
• Element.assignedSlot
  • : Returns a HTMLSlotElement representing the slot the node is inserted in.
• Element.attributes
  • : Returns a NamedNodeMap object containing the assigned attributes of the corresponding HTML element.
• Element.childElementCount
  • : Returns the number of child elements of this element.
• Element.children
  • : Returns the child elements of this element.
• Element.classList
  • : Returns a DOMTokenList containing the list of class attributes.
• Element.className
  • : A string representing the class of the element.
• Element.clientHeight
  • : Returns a number representing the inner height of the element.
• Element.clientLeft
  • : Returns a number representing the width of the left border of the element.
• Element.clientTop
  • : Returns a number representing the width of the top border of the element.
• Element.clientWidth
  • : Returns a number representing the inner width of the element.
• Element.currentCSSZoom
  • : A number indicating the effective zoom size of the element, or 1.0 if the element is not rendered.
• Element.customElementRegistry
  • : The CustomElementRegistry object associated with this element, or null if one has not been set.
• Element.elementTiming
  • : A string reflecting the elementtiming attribute which marks an element for observation in the PerformanceElementTiming API.
• Element.firstElementChild
  • : Returns the first child element of this element.
• Element.id
  • : A string representing the id of the element.
• Element.innerHTML
  • : A string representing the markup of the element's content.
• Element.lastElementChild
  • : Returns the last child element of this element.
• Element.localName
  • : A string representing the local part of the qualified name of the element.
• Element.namespaceURI
  • : The namespace URI of the element, or null if it is no namespace.
• Element.nextElementSibling
  • : An Element, the element immediately following the given one in the tree, or null if there's no sibling node.
• Element.outerHTML
  • : A string representing the markup of the element including its content. When used as a setter, replaces the element with nodes parsed from the given string.
• Element.part
  • : Represents the part identifier(s) of the element (i.e., set using the part attribute), returned as a DOMTokenList.
• Element.prefix
  • : A string representing the namespace prefix of the element, or null if no prefix is specified.
• Element.previousElementSibling
  • : An Element, the element immediately preceding the given one in the tree, or null if there is no sibling element.
• Element.scrollHeight
  • : Returns a number representing the scroll view height of an element.
• Element.scrollLeft
  • : A number representing the left scroll offset of the element.
• Element.scrollLeftMax
  • : Returns a number representing the maximum left scroll offset possible for the element.
• Element.scrollTop
  • : A number representing number of pixels the top of the element is scrolled vertically.
• Element.scrollTopMax
  • : Returns a number representing the maximum top scroll offset possible for the element.
• Element.scrollWidth
  • : Returns a number representing the scroll view width of the element.
• Element.shadowRoot
  • : Returns the open shadow root that is hosted by the element, or null if no open shadow root is present.
• Element.slot
  • : Returns the name of the shadow DOM slot the element is inserted in.
• Element.tagName
  • : Returns a string with the name of the tag for the given element.

Instance properties included from ARIA

The Element interface also includes the following properties.

• Element.ariaAtomic
  • : A string reflecting the aria-atomic attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.
• Element.ariaAutoComplete
  • : A string reflecting the aria-autocomplete attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made.
• Element.ariaBrailleLabel
  • : A string reflecting the aria-braillelabel attribute, which defines the braille label of the element.
• Element.ariaBrailleRoleDescription
  • : A string reflecting the aria-brailleroledescription attribute, which defines the ARIA braille role description of the element.
• Element.ariaBusy
  • : A string reflecting the aria-busy attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user.
• Element.ariaChecked
  • : A string reflecting the aria-checked attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state.
• Element.ariaColCount
  • : A string reflecting the aria-colcount attribute, which defines the number of columns in a table, grid, or treegrid.
• Element.ariaColIndex
  • : A string reflecting the aria-colindex attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid.
• Element.ariaColIndexText
  • : A string reflecting the aria-colindextext attribute, which defines a human-readable text alternative of aria-colindex.
• Element.ariaColSpan
  • : A string reflecting the aria-colspan attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
• Element.ariaCurrent
  • : A string reflecting the aria-current attribute, which indicates the element that represents the current item within a container or set of related elements.
• Element.ariaDescription
  • : A string reflecting the aria-description attribute, which defines a string value that describes or annotates the current element.
• Element.ariaDisabled
  • : A string reflecting the aria-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.
• Element.ariaExpanded
  • : A string reflecting the aria-expanded attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed.
• Element.ariaHasPopup
  • : A string reflecting the aria-haspopup attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
• Element.ariaHidden
  • : A string reflecting the aria-hidden attribute, which indicates whether the element is exposed to an accessibility API.
• Element.ariaInvalid
  • : A string reflecting the aria-invalid attribute, which indicates the entered value does not conform to the format expected by the application.
• Element.ariaKeyShortcuts
  • : A string reflecting the aria-keyshortcuts attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
• Element.ariaLabel
  • : A string reflecting the aria-label attribute, which defines a string value that labels the current element.
• Element.ariaLevel
  • : A string reflecting the aria-level attribute, which defines the hierarchical level of an element within a structure.
• Element.ariaLive
  • : A string reflecting the aria-live attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.
• Element.ariaModal
  • : A string reflecting the aria-modal attribute, which indicates whether an element is modal when displayed.
• Element.ariaMultiLine
  • : A string reflecting the aria-multiline attribute, which indicates whether a text box accepts multiple lines of input or only a single line.
• Element.ariaMultiSelectable
  • : A string reflecting the aria-multiselectable attribute, which indicates that the user may select more than one item from the current selectable descendants.
• Element.ariaOrientation
  • : A string reflecting the aria-orientation attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
• Element.ariaPlaceholder
  • : A string reflecting the aria-placeholder attribute, which defines a short hint intended to aid the user with data entry when the control has no value.
• Element.ariaPosInSet
  • : A string reflecting the aria-posinset attribute, which defines an element's number or position in the current set of listitems or treeitems.
• Element.ariaPressed
  • : A string reflecting the aria-pressed attribute, which indicates the current "pressed" state of toggle buttons.
• Element.ariaReadOnly
  • : A string reflecting the aria-readonly attribute, which indicates that the element is not editable, but is otherwise operable.
• Element.ariaRelevant
  • : A string reflecting the aria-relevant attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an aria-live region are relevant and should be announced.
• Element.ariaRequired
  • : A string reflecting the aria-required attribute, which indicates that user input is required on the element before a form may be submitted.
• Element.ariaRoleDescription
  • : A string reflecting the aria-roledescription attribute, which defines a human-readable, author-localized description for the role of an element.
• Element.ariaRowCount
  • : A string reflecting the aria-rowcount attribute, which defines the total number of rows in a table, grid, or treegrid.
• Element.ariaRowIndex
  • : A string reflecting the aria-rowindex attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid.
• Element.ariaRowIndexText
  • : A string reflecting the aria-rowindextext attribute, which defines a human-readable text alternative of aria-rowindex.
• Element.ariaRowSpan
  • : A string reflecting the aria-rowspan attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
• Element.ariaSelected
  • : A string reflecting the aria-selected attribute, which indicates the current "selected" state of elements that have a selected state.
• Element.ariaSetSize
  • : A string reflecting the aria-setsize attribute, which defines the number of items in the current set of listitems or treeitems.
• Element.ariaSort
  • : A string reflecting the aria-sort attribute, which indicates if items in a table or grid are sorted in ascending or descending order.
• Element.ariaValueMax
  • : A string reflecting the aria-valueMax attribute, which defines the maximum allowed value for a range widget.
• Element.ariaValueMin
  • : A string reflecting the aria-valueMin attribute, which defines the minimum allowed value for a range widget.
• Element.ariaValueNow
  • : A string reflecting the aria-valueNow attribute, which defines the current value for a range widget.
• Element.ariaValueText
  • : A string reflecting the aria-valuetext attribute, which defines the human-readable text alternative of aria-valuenow for a range widget.
• Element.role
  • : A string reflecting the explicitly set role attribute, which provides the semantic role of the element.

Instance properties reflected from ARIA element references

The properties reflect the elements specified by id reference in the corresponding attributes, but with some caveats. See Reflected element references in the Reflected attributes guide for more information.

• Element.ariaActiveDescendantElement
  • : An element that represents the current active element when focus is on a composite widget, combobox, textbox, group, or application. Reflects the aria-activedescendant attribute.
• Element.ariaControlsElements
  • : An array of elements whose contents or presence are controlled by the element it is applied to. Reflects the aria-controls attribute.
• Element.ariaDescribedByElements
  • : An array of elements that contain the accessible description for the element it is applied to. Reflects the aria-describedby attribute.
• Element.ariaDetailsElements
  • : An array of elements that provide accessible details for the element it is applied to. Reflects the aria-details attribute.
• Element.ariaErrorMessageElements
  • : An array of elements that provide an error message for the element it is applied to. Reflects the aria-errormessage attribute.
• Element.ariaFlowToElements
  • : An array of elements that identify the next element (or elements) in an alternate reading order of content, overriding the general default reading order at the user's discretion. Reflects the aria-flowto attribute.
• Element.ariaLabelledByElements
  • : An array of elements that provide the accessible name for the element it is applied to. Reflects the aria-labelledby attribute.
• Element.ariaOwnsElements
  • : An array of elements owned by the element this is applied to. This is used to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship. Reflects the aria-owns attribute.

Instance methods

Element inherits methods from its parents Node, and its own parent, EventTarget.

• Element.after()
  • : Inserts a set of Node objects or strings in the children list of the Element's parent, just after the Element.
• Element.animate()
  • : A shortcut method to create and run an animation on an element. Returns the created Animation object instance.
• Element.ariaNotify()
  • : Specifies that a given string of text should be announced by a screen reader.
• Element.append()
  • : Inserts a set of Node objects or strings after the last child of the element.
• Element.attachShadow()
  • : Attaches a shadow DOM tree to the specified element and returns a reference to its ShadowRoot.
• Element.before()
  • : Inserts a set of Node objects or strings in the children list of the Element's parent, just before the Element.
• Element.checkVisibility()
  • : Returns whether an element is expected to be visible or not based on configurable checks.
• Element.closest()
  • : Returns the Element which is the closest ancestor of the current element (or the current element itself) which matches the selectors given in parameter.
• Element.computedStyleMap()
  • : Returns a StylePropertyMapReadOnly interface which provides a read-only representation of a CSS declaration block that is an alternative to CSSStyleDeclaration.
• Element.getAnimations()
  • : Returns an array of Animation objects currently active on the element.
• Element.getAttribute()
  • : Retrieves the value of the named attribute from the current node and returns it as a string.
• Element.getAttributeNames()
  • : Returns an array of attribute names from the current element.
• Element.getAttributeNode()
  • : Retrieves the node representation of the named attribute from the current node and returns it as an Attr.
• Element.getAttributeNodeNS()
  • : Retrieves the node representation of the attribute with the specified name and namespace, from the current node and returns it as an Attr.
• Element.getAttributeNS()
  • : Retrieves the value of the attribute with the specified namespace and name from the current node and returns it as a string.
• Element.getBoundingClientRect()
  • : Returns the size of an element and its position relative to the viewport.
• Element.getBoxQuads()
  • : Returns a list of DOMQuad objects representing the CSS fragments of the node.
• Element.getClientRects()
  • : Returns a collection of rectangles that indicate the bounding rectangles for each line of text in a client.
• Element.getElementsByClassName()
  • : Returns a live HTMLCollection that contains all descendants of the current element that possess the list of classes given in the parameter.
• Element.getElementsByTagName()
  • : Returns a live HTMLCollection containing all descendant elements, of a particular tag name, from the current element.
• Element.getElementsByTagNameNS()
  • : Returns a live HTMLCollection containing all descendant elements, of a particular tag name and namespace, from the current element.
• Element.getHTML()
  • : Returns the DOM content of the element as an HTML string, optionally including any shadow DOM.
• Element.hasAttribute()
  • : Returns a boolean value indicating if the element has the specified attribute or not.
• Element.hasAttributeNS()
  • : Returns a boolean value indicating if the element has the specified attribute, in the specified namespace, or not.
• Element.hasAttributes()
  • : Returns a boolean value indicating if the element has one or more HTML attributes present.
• Element.hasPointerCapture()
  • : Indicates whether the element on which it is invoked has pointer capture for the pointer identified by the given pointer ID.
• Element.insertAdjacentElement()
  • : Inserts a given element node at a given position relative to the element it is invoked upon.
• Element.insertAdjacentHTML()
  • : Parses the text as HTML or XML and inserts the resulting nodes into the tree in the position given.
• Element.insertAdjacentText()
  • : Inserts a given text node at a given position relative to the element it is invoked upon.
• Element.matches()
  • : Returns a boolean value indicating whether or not the element would be selected by the specified selector string.
• Element.moveBefore()
  • : Moves a given Node inside the invoking node as a direct child, before a given reference node, without removing and then inserting the node.
• Element.prepend()
  • : Inserts a set of Node objects or strings before the first child of the element.
• Element.pseudo()
  • : Returns a CSSPseudoElement object representing the CSS pseudo-element of the specified type associated with the element.
• Element.querySelector()
  • : Returns the first Node which matches the specified selector string relative to the element.
• Element.querySelectorAll()
  • : Returns a NodeList of nodes which match the specified selector string relative to the element.
• Element.releasePointerCapture()
  • : Releases (stops) pointer capture that was previously set for a specific PointerEvent.
• Element.remove()
  • : Removes the element from the children list of its parent.
• Element.removeAttribute()
  • : Removes the named attribute from the current node.
• Element.removeAttributeNode()
  • : Removes the node representation of the named attribute from the current node.
• Element.removeAttributeNS()
  • : Removes the attribute with the specified name and namespace, from the current node.
• Element.replaceChildren()
  • : Replaces the existing children of a Node with a specified new set of children.
• Element.replaceWith()
  • : Replaces the element in the children list of its parent with a set of Node objects or strings.
• Element.requestFullscreen()
  • : Asynchronously asks the browser to make the element fullscreen.
• Element.requestPointerLock()
  • : Allows you to asynchronously ask for the pointer to be locked on the given element.
• Element.scroll()
  • : Scrolls to a particular set of coordinates inside a given element.
• Element.scrollBy()
  • : Scrolls an element by the given amount.
• Element.scrollIntoView()
  • : Scrolls the page until the element gets into the view.
• Element.scrollIntoViewIfNeeded()
  • : Scrolls the current element into the visible area of the browser window if it's not already within the visible area of the browser window. Use the standard Element.scrollIntoView() instead.
• Element.scrollTo()
  • : Scrolls to a particular set of coordinates inside a given element.
• Element.setAttribute()
  • : Sets the value of a named attribute of the current node.
• Element.setAttributeNode()
  • : Sets the node representation of the named attribute from the current node.
• Element.setAttributeNodeNS()
  • : Sets the node representation of the attribute with the specified name and namespace, from the current node.
• Element.setAttributeNS()
  • : Sets the value of the attribute with the specified name and namespace, from the current node.
• Element.setCapture()
  • : Sets up mouse event capture, redirecting all mouse events to this element.
• Element.setHTML()
  • : Parses and sanitizes a string of HTML into a document fragment, which then replaces the element's original subtree in the DOM.
• Element.setHTMLUnsafe()
  • : Parses a string of HTML into a document fragment, without sanitization, which then replaces the element's original subtree in the DOM. The HTML string may include declarative shadow roots, which would be parsed as template elements if the HTML was set using Element.innerHTML.
• Element.setPointerCapture()
  • : Designates a specific element as the capture target of future pointer events.
• Element.startViewTransition()
  • : Starts a new same-document (SPA) element-scoped view transition and returns a ViewTransition object to represent it.
• Element.toggleAttribute()
  • : Toggles a boolean attribute, removing it if it is present and adding it if it is not present, on the specified element.

Events

Listen to these events using addEventListener() or by assigning an event listener to the oneventname property of this interface.

• afterscriptexecute
  • : Fired when a script has been executed.
• beforeinput
  • : Fired when the value of an input element is about to be modified.
• beforematch
  • : Fires on an element that is in the hidden until found state, when the browser is about to reveal its content because the user has found the content through the "find in page" feature or through fragment navigation.
• beforescriptexecute
  • : Fired when a script is about to be executed.
• beforexrselect
  • : Fired before WebXR select events (select, selectstart, selectend) are dispatched.
• contentvisibilityautostatechange
  • : Fires on any element with content-visibility: auto set on it when it starts or stops being relevant to the user and skipping its contents.
• input
  • : Fires when an element's value is changed as a direct result of a user action.
• securitypolicyviolation
  • : Fired when a Content Security Policy is violated.
• wheel
  • : Fired when the user rotates a wheel button on a pointing device (typically a mouse).

Animation events

• animationcancel
  • : Fired when an animation unexpectedly aborts.
• animationend
  • : Fired when an animation has completed normally.
• animationiteration
  • : Fired when an animation iteration has completed.
• animationstart
  • : Fired when an animation starts.

Clipboard events

• copy
  • : Fired when the user initiates a copy action through the browser's user interface.
• cut
  • : Fired when the user initiates a cut action through the browser's user interface.
• paste
  • : Fired when the user initiates a paste action through the browser's user interface.

Composition events

• compositionend
  • : Fired when a text composition system such as an input method editor completes or cancels the current composition session.
• compositionstart
  • : Fired when a text composition system such as an input method editor starts a new composition session.
• compositionupdate
  • : Fired when a new character is received in the context of a text composition session controlled by a text composition system such as an input method editor.

Focus events

• blur
  • : Fired when an element has lost focus.
• focus
  • : Fired when an element has gained focus.
• focusin
  • : Fired when an element has gained focus, after focus.
• focusout
  • : Fired when an element has lost focus, after blur.

Fullscreen events

• fullscreenchange
  • : Sent to an Element when it transitions into or out of fullscreen mode.
• fullscreenerror
  • : Sent to an Element if an error occurs while attempting to switch it into or out of fullscreen mode.

Keyboard events

• keydown
  • : Fired when a key is pressed.
• keypress
  • : Fired when a key that produces a character value is pressed down.
• keyup
  • : Fired when a key is released.

Mouse events

• auxclick
  • : Fired when a non-primary pointing device button (e.g., any mouse button other than the left button) has been pressed and released on an element.
• click
  • : Fired when a pointing device button (e.g., a mouse's primary button) is pressed and released on a single element.
• contextmenu
  • : Fired when the user attempts to open a context menu.
• dblclick
  • : Fired when a pointing device button (e.g., a mouse's primary button) is clicked twice on a single element.
• DOMActivate
  • : Occurs when an element is activated, for instance, through a mouse click or a keypress.
• DOMMouseScroll
  • : Occurs when mouse wheel or similar device is operated and the accumulated scroll amount is over 1 line or 1 page since last event.
• mousedown
  • : Fired when a pointing device button is pressed on an element.
• mouseenter
  • : Fired when a pointing device (usually a mouse) is moved over the element that has the listener attached.
• mouseleave
  • : Fired when the pointer of a pointing device (usually a mouse) is moved out of an element that has the listener attached to it.
• mousemove
  • : Fired when a pointing device (usually a mouse) is moved while over an element.
• mouseout
  • : Fired when a pointing device (usually a mouse) is moved off the element to which the listener is attached or off one of its children.
• mouseover
  • : Fired when a pointing device is moved onto the element to which the listener is attached or onto one of its children.
• mouseup
  • : Fired when a pointing device button is released on an element.
• mousewheel
  • : Fired when a mouse wheel or similar device is operated.
• MozMousePixelScroll
  • : Fired when a mouse wheel or similar device is operated.
• webkitmouseforcechanged
  • : Fired each time the amount of pressure changes on the trackpad touch screen.
• webkitmouseforcedown
  • : Fired after the mousedown event as soon as sufficient pressure has been applied to qualify as a "force click".
• webkitmouseforcewillbegin
  • : Fired before the mousedown event.
• webkitmouseforceup
  • : Fired after the webkitmouseforcedown event as soon as the pressure has been reduced sufficiently to end the "force click".

Pointer events

• gotpointercapture
  • : Fired when an element captures a pointer using setPointerCapture().
• lostpointercapture
  • : Fired when a captured pointer is released.
• pointercancel
  • : Fired when a pointer event is canceled.
• pointerdown
  • : Fired when a pointer becomes active.
• pointerenter
  • : Fired when a pointer is moved into the hit test boundaries of an element or one of its descendants.
• pointerleave
  • : Fired when a pointer is moved out of the hit test boundaries of an element.
• pointermove
  • : Fired when a pointer changes coordinates.
• pointerout
  • : Fired when a pointer is moved out of the hit test boundaries of an element (among other reasons).
• pointerover
  • : Fired when a pointer is moved into an element's hit test boundaries.
• pointerrawupdate
  • : Fired when a pointer changes any properties that don't fire pointerdown or pointerup events.
• pointerup
  • : Fired when a pointer is no longer active.

Scroll events

• scroll
  • : Fired when the document view or an element has been scrolled.
• scrollend
  • : Fires when the document view has completed scrolling.
• scrollsnapchange
  • : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected.
• scrollsnapchanging
  • : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends.

Touch events

• gesturechange
  • : Fired when digits move during a touch gesture.
• gestureend
  • : Fired when there are no longer multiple fingers contacting the touch surface, thus ending the gesture.
• gesturestart
  • : Fired when multiple fingers contact the touch surface, thus starting a new gesture.
• touchcancel
  • : Fired when one or more touch points have been disrupted in an implementation-specific manner (for example, too many touch points are created).
• touchend
  • : Fired when one or more touch points are removed from the touch surface.
• touchmove
  • : Fired when one or more touch points are moved along the touch surface.
• touchstart
  • : Fired when one or more touch points are placed on the touch surface.

Transition events

• transitioncancel
  • : An Event fired when a CSS transition has been canceled.
• transitionend
  • : An Event fired when a CSS transition has finished playing.
• transitionrun
  • : An Event fired when a CSS transition is created (i.e., when it is added to a set of running transitions), though not necessarily started.
• transitionstart
  • : An Event fired when a CSS transition has started transitioning.

Specifications

Browser compatibility