kasperisager / doem

A functional DOM traversal and manipulation library for modern browsers

Døm

A functional DOM traversal and manipulation library for modern browsers

Døm was born out of the need of a minimal set of functional-style DOM utilities that could replace core jQuery in modern browsers. It relies only on the latest native browser APIs, making the library light-weight and fast. Much inspiration was taken from You Don't Need jQuery.

Contents

• Installation
• Usage
• API
• Browser support
• License

Installation

$ yarn add doem

Usage

Try out Døm in your browser

import {find, html, [...]} from 'doem';

const el = find(document, '.foo');
html(el, 'Hello World!');

API

addClass

Add a class to an element.

Parameters

• element Element The element to add the class to.
• name string The name of the class to add.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
addClass(element, 'foo');

<p class=foo>Lorem ipsum</p>

after

Insert HTML after an element.

Parameters

• element Element The element to insert the HTML after.
• html string The HTML to insert after the element.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
after(element, '<p>Dolor sit amet</p>');

<p>Lorem ipsum</p><p>Dolor sit amet</p>

append

Insert HTML at the end of an element.

Parameters

• element Element The element to insert the HTML at the end of.
• html string The HTML to insert at the end of the element.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
append(element, '<b>dolor sit amet</b>');

<p>Lorem ipsum<b>dolor sit amet</b></p>

attr

Get or set the value of an attribute of an element.

Parameters

• element Element The element whose attribute to get or set.
• name string The name of the attribute to get or set.
• value string= The value of the attribute if setting.

Examples

<img title="Lorem ipsum">

const element = find(document, 'img');
attr(element, 'title');
// => 'Lorem ipsum'
attr(element, 'title', 'Dolor sit amet')

<img title="Dolor sit amet">

Returns string The value of the attribute if getting.

before

Insert HTML before an element.

Parameters

• element Element The element to insert the HTML before.
• html string The HTML to insert before the element.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
before(element, '<p>Dolor sit amet</p>');

<p>Dolor sit amet</p><p>Lorem ipsum</p>

children

Get all the children of an element.

Parameters

• element Element The element whose children to get.

Examples

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

const element = find(document, 'ul');
children(element);
// => [<li>Item 1</li>, <li>Item 2</li>]

Returns Array.<Element> The children of the element.

clone

Create a deep copy on an element.

Parameters

• element Element The element to copy.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
element !== clone(element);
// => true

Returns Element The copy of the element.

closest

Get the closest matching descendant of an element.

Parameters

• element Element The element whose descendant to get.
• selector string The selector to match against.

Examples

<ul class="lvl-1">
  <li class="item-1">Item 1
    <ul class="lvl-2">
      <li class="item-2">Item 2</li>
    </ul>
  </li>
</ul>

const element = find(document, '.item-2');
closest(element, 'ul');
// => <ul class="lvl-2">...</ul>

Returns Element The closest matching descendant if found.

contains

Check if an element is a descendant of another element.

Parameters

• element Element The parent element to check against.
• child Element The child element to check for.

Examples

<div class=foo>
  <div class=bar></div>
</div>

const foo = find(document, '.foo');
const bar = find(document, '.bar');
contains(foo, bar);
// => true

Returns boolean True if the child is a descendant of the parent.

css

Get or set the value of a CSS property of an element.

Parameters

• element Element The element whose CSS property to get or set.
• property string The CSS property to get or set.
• value string= The value of the CSS property if setting.

Examples

p {
  color: red;
}

<p>Lorem ipsum</p>

const element = find(document, 'p');
css(element, 'color');
// => rgb(255, 0, 0)
css(element, 'color', 'blue');

<p style="color: blue;">Lorem ipsum</p>

Returns string The value of the CSS property if getting.

data

Get or set the value of a data attribute of an element.

Parameters

• element Element The element whose data attribute to get or set.
• key string The key of the data attribute to get or set.
• value string= The value of the data attribute if setting.

Examples

<p data-foo=bar>Lorem ipsum</p>

const element = find(document, 'p');
data(element, 'foo');
// => 'bar'
data(element, 'foo', 'baz')

<p data-foo=baz>Lorem ipsum</p>

Returns string The value of the data attribute if getting.

empty

Remove all children (including text) from an element.

Parameters

• element Element The element whose children to remove.

Examples

<p>Lorem <b>ipsum</b></p>

const element = find(document, 'p');
empty(element);

<p></p>

find

Find the first element matching a query.

Parameters

• scope (Element|Document) The scope to look through.
• query string The query to use for looking up the element.

Examples

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

find(document, 'li');
// => <li>Item 1</li>

Returns Element The element if found.

findAll

Find all elements matching a query.

Parameters

• scope (Element|Document) The scope to look through.
• query string The query to use for looking up the elements.

Examples

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

findAll(document, 'li');
// => [<li>Item 1</li>, <li>Item 2</li>]

Returns Array.<Element> The elements if found.

has

Check if an element has a descendant matching a selector.

Parameters

• element Element The element to check.
• selector string The selector to match against.

Examples

<div class=foo>
  <div class=bar></div>
</div>

const element = find(document, '.foo');
has(element, '.bar');
// => true

Returns boolean True if the element has a descendant matching the selector.

hasClass

Check if an element has a class.

Parameters

• element Element The element to check.
• name string The name of the class to check for.

Examples

<p class=foo>Lorem ipsum</p>

const element = find(document, 'p');
hasClass(element, 'foo');
// => true

Returns boolean True if the element has the class.

height

Get the computed height of a node.

Parameters

• node (Element|Document|Window) The node whose computed height to get.

Examples

div {
  padding: 10px 0 5px;
}
p {
  line-height: 20px;
}

<div>
  <p>Lorem ipsum</p>
</div>

const element = find(document, 'div');
height(element);
// => 35

Returns number The computed height of the node.

html

Get or set the inner HTML of an element.

Parameters

• element Element The element whose inner HTML to get or set.
• content string The content of the inner HTML if setting.

Examples

<p>Lorem <b>ipsum</b></p>

const element = find(document, 'p');
html(element);
// => 'Lorem <b>ipsum</b>''
html(element, 'Dolor sit <b>amet</b>');

<p>Dolor sit <b>amet</b></p>

Returns string The inner HTML of the element if getting.

matches

Check if an element matches a selector.

Parameters

• element Element The element to check.
• selector string The selector to check against.

Examples

<p class=foo>Lorem ipsum</p>

const element = find(document, 'p');
matches(element, 'div.foo');
// => true

Returns boolean True if the element matches the selector.

next

Get the next sibling of an element.

Parameters

• element Element The element whose sibling to get.

Examples

<p class=foo>Lorem ipsum</p>
<p>Dolor sit amet</p>

const element = find(document, '.foo');
next(element);
// => <p>Dolor sit amet</p>

Returns Element The sibling of the element if found.

offset

Get the current coordinates of an element relative to its document

Parameters

• element Element The element whose coordinates to get.

Examples

div {
  margin-lef: 10px;
  line-height: 20px;
}

<div>Lorem ipsum</div>
<div class=foo>Dolor sit amet</div>

const element = find(document, '.foo');
offset(element);
// => {top: 20, left: 10}

Returns {top: number, left: number} The current coordinates of the element.

parent

Get the parent of an element.

Parameters

• element Element The element whose parent to get.

Examples

<div>
  <p>Lorem ipsum</p>
</div>

const element = find(document, 'p');
parent(element);
// => <div>...</div>

Returns Element The parent element if found.

parents

Get all the parents of an element.

Parameters

• element Element The element whose parents to get.

Examples

<div>
  <p>Lorem <b>ipsum</b></p>
</div>

const element = find(document, 'b');
parents(element);
// => [<p>...</p>, <div>...</div>]

Returns Array.<Element> The parents of the element.

position

Get the current coordinates of an element relative to its offset parent.

Parameters

• element Element The element whose coordinates to get.

Examples

div {
  padding: 20px 10px;
}

<div>
  <span>Lorem ipsum</span>
</div>

const element = find(document, 'span');
position(element);
// => {top: 20, left: 10}

Returns {top: number, left: number} The current coordinates of the element.

prepend

Insert HTML at the beginnig of an element.

Parameters

• element Element The element to insert the HTML at the beginning of.
• html string The HTML to insert at the beginning of the element.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
append(element, '<b>Dolor sit amet</b>');

<p><b>Dolor sit amet</b>Lorem ipsum</p>

prev

Get the previous sibling of an element.

Parameters

• element Element The element whose sibling to get.

Examples

<p>Lorem ipsum</p>
<p class=foo>Dolor sit amet</p>

const element = find(document, '.foo');
prev(element);
// => <p>Lorem ipsum</p>

Returns Element The sibling of the element if found.

remove

Remove an element from its parent.

Parameters

• element Element The element to remove.

Examples

<p>Lorem <b>ipsum</b></p>

const element = find(document, 'b');
remove(element);

<p>Lorem </p>

removeAttr

Remove an attribute from an element.

Parameters

• element Element The element whose attribute to remove.
• name string The name of the attribute to remove.

Examples

<img title="Lorem ipsum">

const element = find(document, 'img');
removeAttr(element, 'title');

<img>

removeClass

Remove a class from an element.

Parameters

• element Element The element to remove the class from.
• name string The name of the class to remove.

Examples

<p class="foo bar">Lorem ipsum</p>

const element = find(document, 'p');
removeClass(element, 'foo');

<p class=bar>Lorem ipsum</p>

removeData

Remove a data attribute from an element.

Parameters

• element Element The element whose data attribute to remove.
• key string The key of the data attribute to remove.

Examples

<p data-foo=bar>Lorem ipsum</p>

const element = find(document, 'p');
removeData(element, 'foo');

<p>Lorem ipsum</p>

replace

Replace an element with HTML.

Parameters

• element Element The element to replace with HTML.
• html string The HTML to replace the element with.

Examples

<p>Lorem <b>ipsum<b></p>

const element = find(document, 'b');
replace(element, '<i>ipsum</i>');

<p>Lorem <i>ipsum<i></p>

siblings

Get all the siblings of an element.

Parameters

• element Element The element whose siblings to get.

Examples

<ul>
  <li>Item 1</li>
  <li class=foo>Item 2</li>
  <li>Item 3</li>
</ul>

const element = find(document, '.foo');
siblings(element);
// => [<li>Item 1</li>, <li>Item 2</li>]

Returns Array.<Element> The siblings of the element.

style

Get the computed style of an element.

Parameters

• element Element The element whose computed style to get.

Examples

p {
  color: red;
}

<p style="float: right;">Lorem ipsum</p>

const element = find(document, 'p');
style(element);
// => CSSStyleDeclaration { color: 'rgb(255, 0, 0)', float: 'right', ... }

Returns CSSStyleDeclaration The computed style of the element.

tag

Get the tag name of the element.

Parameters

• element Element The element whose tag name to get.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
tag(element);
// => 'p'

Returns string The tag name of the element.

text

Get or set the text content of an element.

Parameters

• element Element The element whose text content to get or set.
• content string= The text content if setting.

Examples

<p>Lorem <b>ipsum</b></p>

const element = find(document, 'p');
text(element);
// => 'Lorem ipsum'
text(element, 'Lorem ipsum');

<p>Lorem ipsum</p>

Returns string The text content if getting.

toggleClass

Toggle a class on an element.

Parameters

• element Element The element to toggle the class on.
• name string The name of the class to toggle.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
toggleClass(element, 'foo');

<p class=foo>Lorem ipsum</p>

toggleClass(element, 'foo');

<p>Lorem ipsum</p>

unwrap

Remove the parent of an element.

Parameters

• element Element The element whose parent to remove.

Examples

<div>
  <p class=foo>Lorem ipsum</p>
  <p>Dolor sit amet</p>
</div>

const element = find(document, '.foo');
unwrap(element);

<p class=foo>Lorem ipsum</p>
<p>Dolor sit amet</p>

val

Get or set the value of an element.

Parameters

• element Element The element whose value to get or set.
• value string= The value of the element if setting.

Examples

<input value=foo></input>

const element = find(document, 'input');
val(element);
// => 'foo'
val(element, 'bar');

<input value=bar></input>

Returns string The value of the element if getting.

width

Get the computed width of a node.

Parameters

• node (Element|Document|Window) The node whose computed width to get.

Examples

div {
  padding: 0 10px;
}
p {
  width: 40px;
}

<div>
  <p>Lorem ipsum</p>
</div>

const element = find(document, 'div');
width(element);
// => 60

Returns number The computed width of the node.

wrap

Wrap an HTML structure around an element.

Parameters

• element Element The element to wrap the HTML structure around.
• html string The HTML structure to wrap around the element.

Examples

<p>Lorem ipsum</p>

const element = find(document, 'p');
wrap(element, '<div></div>');

<div>
  <p>Lorem ipsum</p>
</div>

Browser support

Latest ✔	Latest ✔	11+ ✔	Latest ✔	6.1+ ✔

License

Copyright © 2016 Kasper Kronborg Isager. Licensed under the terms of the MIT license.