Documentation Class: $Element

new $Element()

Used to represent an element in better-dom

Extends

$Node

Methods

addClass(className)

Add class(es) to element

Parameters:

Name	Type	Argument	Description
`className`	String	<repeatable>	class name to add

Returns:

Self

Type: $Element

Example

link.addClass("foo", "bar");

after(contents)

Insert HTMLString or $Element after the current element

Parameters:

Name	Type	Argument	Description
`contents`	Mixed	<repeatable>	HTMLString, $Element, Array.<$Element> or functor

Returns:

Self

Type: $Element

Example

var link = DOM.create("a");                   // <a></a>
link.after(DOM.create("b"));                  // <a></a><b></b>
link.after(DOM.create("i"), DOM.create("u")); // <a></a><b></b><i></i><u></u>

append(contents)

Append HTMLString or $Element to the current element

Parameters:

Name	Type	Argument	Description
`contents`	Mixed	<repeatable>	HTMLString, $Element, Array.<$Element> or functor

Returns:

Self

Type: $Element

Example

var link = DOM.create("a>`foo`");              // <a>foo</a>
link.append(DOM.create("b"));                  // <a>foo<b></b></a>
link.append(DOM.create("i"), DOM.create("u")); // <a>foo<b></b><i></i><u></u></a>

before(contents)

Insert HTMLString or $Element before the current element

Parameters:

Name	Type	Argument	Description
`contents`	Mixed	<repeatable>	HTMLString, $Element, Array.<$Element> or functor

Returns:

Self

Type: $Element

Example

var link = DOM.create("a");                    // <a></a>
link.before(DOM.create("b"));                  // <b></b><a></a>
link.before(DOM.create("i"), DOM.create("u")); // <i></i><u></u><b></b><a></a>

child(index)

Return child element by index filtered by optional selector

Parameters:

Name	Type	Description
`index`	Number	child index

Returns:

A matched child element

Type: $Element

Example

ul.child(0);  // => the first <li>
ul.child(2);  // => 3th child <li>
ul.child(-1); // => last child <li>

children( [selector])

Fetch children elements filtered by optional selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	css selector

Returns:

An array of all matched elements

Type: Array.<$Element>

Example

ul.children();       // => array with all child <li>
ul.children(".foo"); // => array with of child <li> with class "foo"

clone(deepCopy)

Clone element

Parameters:

Name	Type	Description
`deepCopy`	Boolean	`true` when all children should also be cloned, otherwise `false`

Inherited From:

$Node#clone

Returns:

A clone of the current element

Type: $Node

Example

ul.clone(true);  // => clone of <ul> with all it's children
ul.clone(false); // => clone of <ul> element ONLY

closest( [selector])

Find the closest ancestor of the current element (or the current element itself) which matches selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	CSS selector

Returns:

Matched element

Type: $Element

Example

var div = DOM.create("div.foo>div.bar>a"); // <div class="foo"><div class="bar"><a></a></div></div>
var link = div.find("a");                  // => <a>
link.closest();                            // => <div class="bar">
link.closest("a");                         // => itself
link.closest(".bar");                      // => <div class="bar">
link.closest(".foo");                      // => <div class="foo">

contains(element)

Check if an element is inside of the current context

Parameters:

Name	Type	Description
`element`	$Node	Element to check

Inherited From:

$Node#contains

Returns:

true if success and false otherwise

Type: Boolean

Example

DOM.contains(DOM.find("body")); // => true
DOM.find("body").contains(DOM); // => false

css(name [, value])

CSS properties accessor for an element

Parameters:

Name	Type	Argument	Description
`name`	String \| Object		Style property name or key/value object
`value`	String \| function	<optional>	Style property value or functor

Returns:

Property value or self

Type: String | $Element

Example

link.css("color");                 // => element color property
link.css("box-sizing");            // => value of "box-sizing" (no vendor prefix needed)
link.css("color", "red");          // update element color
link.css("animation-delay", "1s"); // update animation-delay (no vendor prefix needed)

empty()

Clears all children

Returns:

Self

Type: $Element

Example

var div = DOM.create("div>a+b"); // <div><a></a><b></b></div>
div.empty();                     // <div></div>

find(selector)

Find the first matched element in the current context by a CSS selector

Parameters:

Name	Type	Description
`selector`	String	CSS selector

Inherited From:

$Node#find

Returns:

The first matched element

Type: $Element

Example

var body = DOM.find("body");  // => <body> wrapper
var foo  = body.find(".foo"); // => the first element with class "foo"
foo.find(".bar>span");        // => the first element that matches ".bar>span"

findAll(selector)

Find all matched elements in the current context by a CSS selector

Parameters:

Name	Type	Description
`selector`	String	CSS selector

Inherited From:

$Node#findAll

Returns:

An array of matched elements

Type: Array.<$Element>

Example

DOM.findAll("a");         // => all links in the document
context.findAll("ol>li"); // => all <li> inside of <ol>

fire(type [, detail])

Trigger an event of specific type with optional data

Parameters:

Name	Type	Argument	Description
`type`	String		Type of event
`detail`	Object	<optional>	Custom event data

Inherited From:

$Node#fire

Returns:

true if default event action was NOT prevented

Type: Boolean

Example

link.fire("click");              // fire click event
link.fire("my:event", {a: "b"}); // fire "my:event" with custom data

get(name [, defaultValue])

Get property or attribute value by name

Parameters:

Name	Type	Argument	Description
`name`	String \| Array		Property or attribute name or array of names
`defaultValue`	Object	<optional>	Default value if returned is `null`

Inherited From:

$Node#get

Returns:

Value of property or attribute

Type: Object

Example

link.get("title");       // => property title
link.get("data-custom"); // => custom attribute data-custom

hasClass(className)

Check if element contains a class name

Parameters:

Name	Type	Description
`className`	String	class name to verify

Returns:

true if the element contains the class

Type: Boolean

Example

link.hasClass("foo");

hide( [animationName] [, callback])

Hide an element using CSS3 transition or animation

Parameters:

Name	Type	Argument	Description
`animationName`	String	<optional>	CSS animation name to apply during transition
`callback`	function	<optional>	function that executes when animation is done

Returns:

Self

Type: $Element

Example

link.hide(); // hides element

foo.hide(function() {
  // do something when transition is completed
});

bar.hide("fade", function() {
  // do something when "fade" animation is completed
});

matches(selector)

Check if element matches a specified selector

Parameters:

Name	Type	Description
`selector`	String	css selector for checking

Returns:

true if matches and false otherwise

Type: Boolean

Example

DOM.find("body").matches("html>body"); // => true
DOM.find("body").matches("body>html"); // => false

next( [selector])

Find next sibling element filtered by optional selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	CSS selector

Returns:

Matched element

Type: $Element

Example

var div = DOM.create("div>a+b+i"); // <div><a></a><b></b><i></i></div>
var link = div.child(0);           // <a>
link.next();                       // <b>
link.next("i");                    // <i>

nextAll( [selector])

Find all next sibling elements filtered by optional selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	CSS selector

Returns:

An array of all matched elements

Type: Array.<$Element>

Example

var div = DOM.create("div>a+i+b+i"); // <div><a></a><i></i><b></b><i></i></div>
var link = DOM.child(0);             // <a>
link.nextAll();                      // [<i>, <b>, <i>]
link.nextAll("i");                   // [<i>, <i>]

offset()

Calculates offset of the current element

Returns:

An object with left, top, bottom, right, width and height properties

Type: Object

Example

el.offset(); // => {left: 1, top: 2, right: 3, bottom: 4, width: 2, height: 2}

on(type [, options] [, args], callback)

Bind a DOM event listener

Parameters:

Name	Type	Argument	Description
`type`	String		Event type
`options`	Object \| String	<optional>	Event options object or css selector to match on
`args`	Array	<optional>	Array of handler arguments to pass into the callback
`callback`	function		Event listener callback

Inherited From:

$Node#on

Returns:

Functor to cancel the listener

Type: function

Example

link.on("focus", function() {
    // do something on focus
});

link.on("click", "i", function() {
    // do something on internal <i> click
});

link.on("click", "span", ["currentTarget"], function(span) {
    // <span> is the element was clicked
});

link.on("blur", {once: true}, function() {
    // event fired only once
});

link.on("mousedown", {capture: true}, function() {
    // event fired on capturing phase
});

prepend(contents)

Prepend HTMLString or $Element to the current element

Parameters:

Name	Type	Argument	Description
`contents`	Mixed	<repeatable>	HTMLString, $Element, Array.<$Element> or functor

Returns:

Self

Type: $Element

Example

var link = DOM.create("a>`foo`");               // <a>foo</a>
link.prepend(DOM.create("b"));                  // <a><b></b>foo</a>
link.prepend(DOM.create("i"), DOM.create("u")); // <a><i></i><u></u><b></b>foo</a>

prev( [selector])

Find previous sibling element filtered by optional selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	CSS selector

Returns:

Matched element

Type: $Element

Example

var div = DOM.create("div>b+i+a"); // <div><b></b><i></i><a></a></div>
var link = div.child(-1);          // <a>
link.prev();                       // <i>
link.prev("b");                    // <b>

prevAll( [selector])

Find all previous sibling elements filtered by optional selector

Parameters:

Name	Type	Argument	Description
`selector`	String	<optional>	CSS selector

Returns:

An array of all matched elements

Type: Array.<$Element>

Example

var div = DOM.create("div>a+i+b+i"); // <div><i></i><b></b><i></i><a></a></div>
var link = DOM.child(-1);            // <a>
link.prevAll();                      // [<i>, <b>, <i>]
link.prevAll("b");                   // [<b>]

remove()

Remove current element from the DOM

Returns:

Type: $Element

Example

var foo = DOM.find(".foo");
foo.remove();
DOM.contains(foo); // => false

removeClass(className)

Remove class(es) from element

Parameters:

Name	Type	Argument	Description
`className`	String	<repeatable>	class name to remove

Returns:

Self

Type: $Element

Example

link.removeClass("foo", "bar");

replace(content)

Replace current element with HTMLString or $Element

Parameters:

Name	Type	Description
`content`	Mixed	HTMLString, $Element, Array.<$Element> or functor

Returns:

Self

Type: $Element

Example

var div = DOM.create("div>span>`foo`");      // <div><span>foo</span></div>
div.child(0).replace(DOM.create("b>`bar`")); // <div><b>bar</b></div>

set(name, value)

Set property/attribute value by name

Parameters:

Name	Type	Description
`name`	String \| Object \| Array \| function	property/attribute name
`value`	String \| function	property/attribute value or functor

Inherited From:

$Node#set

Returns:

Self

Type: $Node

Example

link.set("title", "mytitle");   // set title property
link.set("data-custom", "foo"); // set custom attribute data-custom

show( [animationName] [, callback])

Show an element using CSS3 transition or animation

Parameters:

Name	Type	Argument	Description
`animationName`	String	<optional>	CSS animation name to apply during transition
`callback`	function	<optional>	function that executes when animation is done

Returns:

Self

Type: $Element

Example

link.show(); // displays element

foo.show(function() {
  // do something when transition is completed
});

bar.show("fade", function() {
  // do something when "fade" animation is completed
});

toggleClass(className [, force])

Toggle a class on element

Parameters:

Name	Type	Argument	Description
`className`	String		class name to toggle
`force`	Boolean	<optional>	if `true` then adds the className; if `false` - removes it

Returns:

true if the className is now present, and false otherwise.

Type: Boolean

Example

link.toggleClass("foo");
link.toggleClass("bar", true);

value( [content])

Read or write inner content of the element

Parameters:

Name	Type	Argument	Description
`content`	HTMLString	<optional>	Value to set to

Returns:

Self or inner content value

Type: $Element | String

Example

var div = DOM.create("div>a+b"); // <div><a></a><b></b></div>
div.value("inner content");      // <div>inner content</div>
div.value();                     // => "inner content"