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

EventTarget

Node

ElementInstance properties
-------------------

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

`Element.assignedSlot` Read only 

Returns a `HTMLSlotElement` representing the `<slot>` the node is inserted in.

`Element.attributes` Read only 

Returns a `NamedNodeMap` object containing the assigned attributes of the corresponding HTML element.

`Element.childElementCount` Read only 

Returns the number of child elements of this element.

`Element.children` Read only 

Returns the child elements of this element.

`Element.classList` Read only 

Returns a `DOMTokenList` containing the list of class attributes.

`Element.className`

A string representing the class of the element.

`Element.clientHeight` Read only 

Returns a number representing the inner height of the element.

`Element.clientLeft` Read only 

Returns a number representing the width of the left border of the element.

`Element.clientTop` Read only 

Returns a number representing the width of the top border of the element.

`Element.clientWidth` Read only 

Returns a number representing the inner width of the element.

`Element.elementTiming` 
Experimental

A string reflecting the `elementtiming` attribute which marks an element for observation in the `PerformanceElementTiming` API.

`Element.firstElementChild` Read only 

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` Read only 

Returns the last child element of this element.

`Element.localName` Read only 

A string representing the local part of the qualified name of the element.

`Element.namespaceURI` Read only 

The namespace URI of the element, or `null` if it is no namespace.

**Note:** In Firefox 3.5 and earlier, HTML elements are in no namespace. In later versions, HTML elements are in the `http://www.w3.org/1999/xhtml` namespace in both HTML and XML trees.

`Element.nextElementSibling` Read only 

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` Read only 

A string representing the namespace prefix of the element, or `null` if no prefix is specified.

`Element.previousElementSibling` Read only 

An `Element`, the element immediately preceding the given one in the tree, or `null` if there is no sibling element.

`Element.scrollHeight` Read only 

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` 
Non-standard
 Read only 

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` 
Non-standard
 Read only 

Returns a number representing the maximum top scroll offset possible for the element.

`Element.scrollWidth` Read only 

Returns a number representing the scroll view width of the element.

`Element.shadowRoot` Read only 

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` Read only 

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.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` 
Experimental

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.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` 
Non-standard

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` 
Experimental

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.

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.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()` 
Experimental

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.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.prepend()`

Inserts a set of `Node` objects or strings before the first child of 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 `pointer event`.

`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 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()` 
Non-standard

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()` 
Non-standard

Deprecated

Sets up mouse event capture, redirecting all mouse events to this element.

`Element.setHTML()` 
Experimental

Parses and sanitizes a string of HTML and inserts into the DOM as a subtree of the element.

`Element.setPointerCapture()`

Designates a specific element as the capture target of future pointer events.

`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` 
Non-standard

Fired when a script has been executed.

`beforematch` 
Experimental

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` 
Non-standard

Fired when a script is about to be executed.

`contentvisibilityautostatechange` 
Experimental

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.

`scroll`

Fired when the document view or an element has been scrolled.

`scrollend`

Fires when the document view has completed scrolling.

`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` 
Deprecated

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` 
Deprecated

Occurs when an element is activated, for instance, through a mouse click or a keypress.

`DOMMouseScroll` 
Deprecated

Non-standard

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` 
Deprecated

Non-standard

Fired when a mouse wheel or similar device is operated.

`MozMousePixelScroll` 
Deprecated

Non-standard

Fired when a mouse wheel or similar device is operated.

`webkitmouseforcechanged` 
Non-standard

Fired each time the amount of pressure changes on the trackpadtouchscreen.

`webkitmouseforcedown` 
Non-standard

Fired after the mousedown event as soon as sufficient pressure has been applied to qualify as a "force click".

`webkitmouseforcewillbegin` 
Non-standard

Fired before the `mousedown` event.

`webkitmouseforceup` 
Non-standard

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` 
Experimental

Fired when a pointer changes any properties that don't fire `pointerdown` or `pointerup` events.

`pointerup`

Fired when a pointer is no longer active.

### Touch events

`gesturechange` 
Non-standard

Fired when digits move during a touch gesture.

`gestureend` 
Non-standard

Fired when there are no longer multiple fingers contacting the touch surface, thus ending the gesture.

`gesturestart` 
Non-standard

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

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

| Specification |
| --- |
| DOM Standard # interface-element |
| Pointer Events # extensions-to-the-element-interface |
| Pointer Lock 2.0 # extensions-to-the-element-interface |
| Fullscreen API Standard # api |
| DOM Parsing and Serialization # extensions-to-the-element-interface |
| CSSOM View Module # extension-to-the-element-interface |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.