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 usualNodeList
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.
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.