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.

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

You can install the package via yarn:

yarn add spatie-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`

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' }}

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!'));

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'

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

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

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

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

function props(el: HTMLElement): Object;

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

function whenReady(callback: Function): void

function whenLoaded(callback: Function): void

Please see CHANGELOG for more information what has changed recently.

$ npm run test

Please see CONTRIBUTING for details.

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

• Sebastian De Deyne
• All Contributors

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

The MIT License (MIT). Please see License File for more information.