README

spatie-dom

A small DOM querying and manipulation library.

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Install

You can install the package via yarn:

yarn add spatie-dom

Usage

Querying the DOM

The DOM can be queried with query and queryAll, which are wrappers around querySelector and querySelectorAll.

Querying an element in document:

<div id="app"></div>

const app = query('#app'); // Returns a `HTMLElement`

Querying a collection of elements:

queryAll returns a plain array instead of the usual NodeList collection

<div id="main">
    <article></article>
    <article></article>
</div>

const articles = queryAll('#main > article'); // Returns an array `Array<HTMLElement>`

query and queryAll also accept a scope as their second argument (by default, the scope is document).

<div id="main">
    <h1>Header</h1>
</div>

const main = query('#main'); // Returns a `HTMLElement`
const header = query('h1', main); // Also returns a `HTMLElement`

Retrieving 'props'

Props are DOM attributes that exist to be consumed by scripts. Props behave just like attributes, except they get parsed as JSON if prefixed by a :.

This syntax is heavily based on what Vue uses for component props

<div
    id="component"
    my-prop="foo"
    :config='{ "url": "bar" }'
></div>

import { query, prop, props } from  'spatie-dom';

const el = query('#component');

prop(el, 'myProp'); // 'foo'
prop(el, 'config'); // { url: 'bar' }

props(el); // { myProp: 'foo', config: { url: 'bar' }}

Firing events based on the DOM state

The whenReady function calls a function:

immediately if the DOM is loaded;
otherwise after the document DOMContentLoaded event

import { whenReady } from  'spatie-dom';

whenReady(() => console.log('Ready!'));

The whenLoaded function calls a function:

immediately if the DOM and all subresources (scripts, images,...) are loaded;
otherwise after the window load event

import { whenLoaded } from  'spatie-dom';

whenLoaded(() => console.log('Loaded!'));

Reading the DOM

There are several functions to read data from the dom.

With attribute you can retrieve an attribute, and with data you can retrieve a data attribute.

<div id="element" data-foo="bar"></div>

import { attribute, data, query };

const el = query('#element');

// Retrieve an attribute
attribute('id', el); // 'element'

// Retrieve an attribute with a fallback value
attribute('class', el, 'active'); // 'active'

// Retrieve a data attribute
data('foo', el); // 'bar'

// Retrieve a data attribute with a fallback value
data('baz', el, 'qux'); // 'qux'

Full API

Attribute

function attribute(name: string, el: HTMLElement, fallback: string = ''): string

Data

function data(name: string, el: HTMLElement, fallback: string = ''): string

On

function on(event: string, subject: HTMLElement, handler: Function): string

Props

function prop(el: HTMLElement, name: string, fallback: any = null): any;

function props(el: HTMLElement): Object;

Query

function query(selector: string): HTMLElement | null;
function query(selector: string, scope: HTMLElement | Document): HTMLElement | null;

function queryAll(selector: string): Array<HTMLElement>;
function queryAll(selector: string, scope: HTMLElement | Document): Array<HTMLElement>;

When

function whenReady(callback: Function): void

function whenLoaded(callback: Function): void

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ npm run test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please contact Sebastian De Deyne instead of using the issue tracker.

Credits

About Spatie