Element : Node

Element represents an element in the DOM/document tree.  Element is the base
type for
%%/HTMLElement|HTMLElement%%
and
%%/SVGElement|SVGElement%%.


Spec:
https://dom.spec.whatwg.org/#interface-element

AlternateSpec:
http://dev.w3.org/csswg/cssom-view/#extensions-to-the-element-interface

----
instance.attributes : Array<Attr>


----
instance.clientTop : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-clienttop

----
instance.clientLeft : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-clientleft

----
instance.clientWidth : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-clientwidth

----
instance.clientHeight : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-clientheight


----
instance.dataset : DOMStringMap

Map of custom **'data-'** prefixed attributes on **this**. Attribute names
are converted to camel case.

<htmlexample>
<div id='foo' data-bar-baz='value'></div>
<script>
  var foo = document.getElementById('foo');

  console.log(foo.dataset.barBaz);
</script>
</htmlexample>

ReadOnly:
true


----
instance.childElementCount : Number

Returns the number of direct children of **this**.

----
instance.children : HTMLCollection

The %%/Element|Element%% children in **this**.

Unlike %%/Node#childNodes|Node.childNodes%%, **children**
only returns nodes inside **this** that derive from
%%/Element|Element%% (ie, other node types like %%/Text|Text%% and
%%/Comment|Comment%% will be excluded from **children**
but present in **childNodes**).

<htmlexample>
<div id='parent'>
  Some text
  <span>A span</span>
</div>
<script>
  var parent = document.getElementById('parent');
  console.log('children:');
  for (var i = 0; i < parent.children.length; i++) {
    console.log('  ' + parent.children[i].nodeName);
  }

  console.log('childNodes:');
  for (var i = 0; i < parent.childNodes.length; i++) {
    console.log('  ' + parent.childNodes[i].nodeName);
  }
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-children

----
instance.className : String

Gets or sets the classes of the Element (used for styling via
CSS).  **className** should be a space separated list of classes.
**className** corresponds to the HTML **class** attribute.

See also %%#classList|**classList**%%.

<htmlexample>
<style>
  .bar { color: red; }
  .baz { color: blue; }
</style>
<div id='foo' class='bar'>
  Example of the className property.
</div>
<script>
  var foo = document.getElementById('foo');

  console.log(foo.className);
  foo.className = 'baz';
</script>
</htmlexample>

----
instance.classList : DOMTokenList

**classList** is an object that allows easy manipulation
of the classes in the %%#className|**className**%% property.
See also %%#className|**className**%%.

<htmlexample>
<style>
  .bar { color: red; }
  .baz { font-weight: bold; }
</style>
<div id='foo' class='bar'>
  Example of the classList property.
</div>
<script>
  var foo = document.getElementById('foo');

  console.log(foo.classList.length);
  console.log(foo.className);

  foo.classList.add('baz');

  console.log(foo.classList.length);
  console.log(foo.className); // Notice className updates
</script>
</htmlexample>

----
instance.firstElementChild : Element

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-firstelementchild


----
instance.id : String

A unique name for this element in the document.
You can retrieve an element by **id** using
%%/Document#getElementById|**document.getElementById()**%%.

----
instance.lastElementChild : Element

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-lastelementchild

----
instance.localName : String

----
instance.namespaceURI : String

----
instance.nextElementSibling : Element

----
instance.prefix : String

----
instance.previousElementSibling : Element

----
instance.shadowRoot : ShadowRoot

ReadOnly:
true

----
instance.scrollTop : Number

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-scrolltop

----
instance.scrollLeft : Number

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-scrollleft

----
instance.scrollWidth : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-scrollwidth

----
instance.scrollHeight : Number

ReadOnly:
true

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-scrollheight

----
instance.tagName : String


ReadOnly:
true

Spec:
http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#ID-104682815

----
prototype.append(item0 : String, [item1 : String, [...]]) : undefined

Same as **%%#append_Node_Node_dotdotdot|append%%(new %%/Text|Text%%(item0),
new %%/Text|Text%%(item1), ...)**.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.append('bar', 'baz');

  console.log(parent.childNodes[0]);
  console.log(parent.childNodes[1]);
  console.log(parent.childNodes[2]);
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-append

----
prototype.append(item0 : Node, [item1 : Node, [...]]) : undefined

Inserts the specified nodes at the end of %%Node#childNodes|**this.childNodes**%%.
See also %%#prepend|prepend%%, %%#replaceChildren|replaceChildren%%, and
%%Node#appendChild|Node.appendChild%%.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.append(new Text('bar'), document.createElement('input'));
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-append

----
prototype.prepend(item0 : String, [item1 : String, [...]]) : undefined

Same as **%%#prepend_Node_Node_dotdotdot|prepend%%(new %%/Text|Text%%(item0),
new %%/Text|Text%%(item1), ...)**.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.prepend('bar', 'baz');

  console.log(parent.childNodes[0]);
  console.log(parent.childNodes[1]);
  console.log(parent.childNodes[2]);
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-prepend

----
prototype.prepend(item0 : Node, [item1 : Node, [...]]) : undefined

Inserts the specified nodes at the start of %%Node#childNodes|**this.childNodes**%%.
See also %%#append|append%%, %%#replaceChildren|replaceChildren%%, and
%%Node#insertBefore|Node.insertBefore%%.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.prepend(new Text('bar'), document.createElement('input'));
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-prepend

----
prototype.replaceChildren(item0 : String, [item1 : String, [...]]) : undefined

Same as **%%#replaceChildren_Node_Node_dotdotdot|replaceChildren%%(new %%/Text|Text%%(item0),
new %%/Text|Text%%(item1), ...)**.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.replaceChildren('bar', 'baz');
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-replacechildren

----
prototype.replaceChildren(item0 : Node, [item1 : Node, [...]]) : undefined

Removes all items from %%Node#childNodes|**this.childNodes**%% and replaces them
with the specified nodes.
See also %%#append|append%%, %%#prepend|prepend%%,
%%Node#insertBefore|Node.insertBefore%%,
%%Node#removeChild|Node.removeChild%%, and
%%Node#replaceChild|Node.replaceChild%%.

<htmlexample>
<div id='parent'><span id='foo'>foo</span></div>
<script>
  var parent = document.getElementById('parent');
  parent.replaceChildren(new Text('bar'), document.createElement('input'));
</script>
</htmlexample>

Spec:
https://dom.spec.whatwg.org/#dom-parentnode-replacechildren

----
prototype.createShadowRoot() : ShadowRoot

Spec:
http://w3c.github.io/webcomponents/spec/shadow/#widl-Element-createShadowRoot-ShadowRoot

----
prototype.getAttribute(name : String) : String

----
prototype.getAttributeNS(namespaceURI : String, localName : String) : String

----
prototype.getDestinationInsertionPoints() : NodeList

Spec:
http://w3c.github.io/webcomponents/spec/shadow/#widl-Element-getDestinationInsertionPoints-NodeList

----
prototype.getElementsByTagName(name : String) : NodeList

Returns a list of descendants of **this** that match the specified
tag name.

See also
%%#getElementsByTagNameNS|**getElementsByTagNameNS()**%%,
%%#getElementsByClassName|**getElementsByClassName()**%%,
%%#querySelector|**querySelector()**%%,
and
%%#querySelectorAll|**querySelectorAll()**%%.

<htmlexample>
<div>
  <div id='foo'>
    <a>Anchor inside foo.</a>
    <div>
      <a>Nested anchor.</a>
    </div>
  </div>
  <a>Anchor outside foo.</a>
</div>
<script>
  var foo = document.getElementById('foo');
  var anchors = foo.getElementsByTagName('a');

  console.log(anchors.length);
  for (var i = 0; i < anchors.length; i++) {
    console.log(anchors[i].innerText);
  }
</script>
</htmlexample>

----
prototype.getElementsByTagNameNS(namespaceURI : String, localName : String) : NodeList

----
prototype.getElementsByClassName(classNames : String) : NodeList

Returns a list of descendants of **this** that match the specified
class name.

See also
%%#getElementsByTagName|**getElementsByTagName()**%%,
%%#querySelector|**querySelector()**%%,
and
%%#querySelectorAll|**querySelectorAll()**%%.

<htmlexample>
<div>
  <div id='foo'>
    <a class='bar'>'bar' inside foo.</a>
    <div class='bar baz'>
      <a>Nested anchor.</a>
    </div>
  </div>
  <a class='bar'>'bar' outside foo.</a>
</div>
<script>
  var foo = document.getElementById('foo');
  var bars = foo.getElementsByClassName('bar');

  console.log(bars.length);
  for (var i = 0; i < bars.length; i++) {
    console.log(bars[i].tagName);
  }
</script>
</htmlexample>


----
prototype.hasAttribute(name : String) : Boolean

----
prototype.hasAttributeNS(namespaceURI : String, localName : String) : Boolean

----
prototype.hasAttributes() : Boolean


----
prototype.removeAttribute(name : String) : undefined

----
prototype.removeAttributeNS(namespaceURI : String, localName : String) : undefined

----
prototype.setAttribute(name : String, value : String) : undefined

----
prototype.setAttributeNS(namespaceURI : String, qualifiedName : String, value : String) : undefined

----
prototype.querySelector(selector : String) : Element

Returns the first **Element** that matches the CSS **selector**.

See also
%%#querySelectorAll|**querySelectorAll()**%%,
%%#getElementsByTagName|**getElementsByTagName()**%%,
and
%%#getElementsByClassName|**getElementsByClassName()**%%.

<htmlexample>
<span id='foo'>foo1</span>
<span class='bar'>
  <span class='baz'>baz1</span>
</span>
<span class='baz'>baz2</span>
<script>
  var foo = document.querySelector('#foo');
  console.log(foo.innerHTML);

  var baz = document.querySelector('.baz');
  console.log(baz.innerHTML);

  var baz2 = document.querySelector('body > .baz');
  console.log(baz2.innerHTML);
</script>
</htmlexample>

Spec:
http://www.w3.org/TR/selectors-api/#queryselector


----
prototype.querySelectorAll(cssSelector : String) : NodeList

Returns a **NodeList** containing the **Element**s in the document that
match the CSS selector.

See also
%%#querySelector|**querySelector()**%%,
%%#getElementsByTagName|**getElementsByTagName()**%%,
and
%%#getElementsByClassName|**getElementsByClassName()**%%.

<htmlexample>
<body>
  <span id='foo'>foo1</span>
  <span class='bar'>
    <span class='baz'>baz1</span>
  </span>
  <span class='baz'>baz2</span>
</body>
<script>
  var all = document.querySelectorAll('#foo, .baz');
  console.log(all.length);
  for (var i = 0; i < all.length; i++) {
    console.log(all[i].innerHTML);
  };
</script>
</htmlexample>

Spec:
http://www.w3.org/TR/selectors-api/#queryselectorall


----
prototype.getClientRects() : ClientRectList

Returns a list of rectangles where **this** is in the document.

This method is similar to
%%#getBoundingClientRect|**getBoundingClientRect()**%%
except it will return a %%/ClientRect|ClientRect%% for each
part of the element
(eg,
text elements split on multiple lines will return a list with
**length** > 1).

<htmlexample>
<div style='width: 120px'>
<span id='foo'>This is a string of wrapping text</span>
</div>
<script>
  var foo = document.getElementById('foo');

  var clientRects = foo.getClientRects();

  console.log('length = ' + clientRects.length);

  for (var i = 0; i < clientRects.length; i++) {
    console.log('clientRect[' + i + '] = ');
    console.log(JSON.stringify(clientRects[i], null, ' '));
    console.log();
  }
</script>
</htmlexample>

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-getclientrects

----
prototype.getBoundingClientRect() : ClientRect

Returns the rectangular bounds of **this** relative to the
viewport. If this is a text element that is split on multiple lines,
the rectangle will be enlarged to contain all portions.
Use %%#getClientRects|**getClientRects()**%% to get the rectangles
of each portion.

<htmlexample>
<span id='foo'>This is a string of text</span>
<script>
  var foo = document.getElementById('foo');

  var boundingClientRect = foo.getBoundingClientRect();

  console.log(JSON.stringify(boundingClientRect, null, ' '));
</script>
</htmlexample>



Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-getboundingclientrect

----
prototype.releasePointerCapture(id : Number) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-Element-releasePointerCapture-void-long-pointerId

----
prototype.requestFullscreen([options: { \
    navigationUI : String /* One of 'auto', 'show', or 'hide'. */ \
  }]) : Promise<undefined>

Enters fullscreen mode where **this** fills the entire screen. See also %%/Document#exitFullscreen|**document.exitFullscreen()**%%.

<htmlexample>
<div style="background: pink;">
  Element
  <button id="enter">Enter Fullscreen</button>
  <button id="exit">Exit Fullscreen</button>
</div>
<script>
document.querySelector('#enter').onclick = async () => {
  const div = document.querySelector('div');
  if (div.requestFullscreen) {
    await div.requestFullscreen();
  }
  else if (div.webkitRequestFullscreen) {
    div.webkitRequestFullscreen();
  }
};
document.querySelector('#exit').onclick = async () => {
  if (document.exitFullscreen) {
    await document.exitFullscreen();
  }
  else if (document.webkitExitFullscreen) {
    document.webkitExitFullscreen();
  }
};
</script>
</htmlexample>

Spec:
https://fullscreen.spec.whatwg.org/#dom-element-requestfullscreen


----
prototype.requestPointerLock() : undefined

Locks the pointer (mouse cursor) to **this**. If successful,
%%/Document#onpointerlockchange|document.onpointerlockchange%% will fire and
subsequent pointer moves be sent to **this**. If unable to lock the pointer,
%%/Document#onpointerlockerror|document.onpointerlockerror%% will fire.
Use %%/Document#exitPointerLock|document.exitPointerLock%% to release the pointer.
See also %%/Document#pointerLockElement|document.pointerLockElement%%,
%%/MouseEvent#movementX|MouseEvent.movementX%% and
%%/MouseEvent#movementY|MouseEvent.movementY%%.

<htmlexample>
<button id="request">Request Pointer Lock</button>
<pre id="output" style="background: #eee; height: 100px">
<script>
document.querySelector('#request').onclick = (e) => {
  document.body.requestPointerLock();
  e.stopPropagation();
};
document.body.onclick = () => {
  document.exitPointerLock();
};
document.body.onmousemove = (e) => {
  const output = document.getElementById('output');
  output.textContent = 'hasPointerLock: ' + !!document.pointerLockElement + '\n' +
                       'movementX: ' + e.movementX + '\n' + 
                       'movementY: ' + e.movementY;
};
</script>
</htmlexample>

Spec:
https://w3c.github.io/pointerlock/#dom-element-requestpointerlock

----
prototype.scrollIntoView([top = false : Boolean]) : undefined

Scolls the element into view.

<htmlexample>
<div style='height: 100px; overflow: scroll'>
  <div>A</div><div>B</div><div>C</div><div>D</div>
  <div>E</div><div>F</div><div>G</div><div id='h'>H</div>
</div>
<button onclick='doScroll(true)'>Scroll 'H' to top</button>
<button onclick='doScroll(false)'>Scroll 'H' to bottom</button>
<script>
  var doScroll = function(top) {
    document.getElementById('h').scrollIntoView(top);
  }
</script>
</htmlexample>

Spec:
http://dev.w3.org/csswg/cssom-view/#dom-element-scrollintoview

----
prototype.setPointerCapture(id : Number) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-Element-setPointerCapture-void-long-pointerId

----
event.touchstart : listener(event : TouchEvent) : undefined

Called when the user begins touching the element.

Bubbles:
true

Cancelable:
true

Spec:
http://www.w3.org/TR/touch-events/#dfn-touchstart

----
event.touchend : listener(event : TouchEvent) : undefined

Called when the user stops touching the element.

Bubbles:
true

Cancelable:
true

Spec:
http://www.w3.org/TR/touch-events/#dfn-touchend

----
event.touchmove : listener(event : TouchEvent) : undefined

Called when the user moves while touching the element.

Bubbles:
true

Cancelable:
true

Spec:
http://www.w3.org/TR/touch-events/#dfn-touchmove

----
event.touchcancel : listener(event : TouchEvent) : undefined

Bubbles:
true

Cancelable:
false

Spec:
http://www.w3.org/TR/touch-events/#dfn-touchcancel

----
event.gotpointercapture : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-Element-ongotpointercapture

----
event.lostpointercapture : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-Element-onlostpointercapture

----
event.pointerdown : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerdown

----
event.pointermove : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointermove

----
event.pointerup : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerup

----
event.pointercancel : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointercancel

----
event.pointerover : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerover

----
event.pointerout : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerout

----
event.pointerenter : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerenter

----
event.pointerleave : listener(event : PointerEvent) : undefined

Spec:
http://www.w3.org/TR/pointerevents/#widl-GlobalEventHandlers-onpointerleave

----
event.copy : listener(event : ClipboardEvent) : undefined

Bubbles:
true

Cancelable:
true

Spec:
https://w3c.github.io/clipboard-apis/#clipboard-event-copy

----
event.cut : listener(event : ClipboardEvent) : undefined

Bubbles:
true

Cancelable:
true

Spec:
https://w3c.github.io/clipboard-apis/#clipboard-event-cut

----
event.paste : listener(event : ClipboardEvent) : undefined

Bubbles:
true

Cancelable:
true

Spec:
https://w3c.github.io/clipboard-apis/#clipboard-event-paste

----
event.fullscreenchange : listener(event : Event) : undefined

Spec:
https://fullscreen.spec.whatwg.org/#handler-document-onfullscreenchange

----
event.fullscreenerror : listener(event : Event) : undefined

Spec:
https://fullscreen.spec.whatwg.org/#handler-document-onfullscreenerror