sweet-dom
A DOM library for developers who don't want a DOM library.
Less than 2 KB of minified runtime code. Peanuts.
Modern JavaScript has improved so much, old IE is out of the picture and the need for a comprehensive DOM library is decreasing.
If you are comfortable with writing vanilla DOM but wouldn't mind just a tiny bit of sugar on top - this is for you.
A good pick for small vanilla projects or for working with existing DOM (e.g browser extension).
Could also be handy as a secondary pocket tool alongside your main components library, for those cases you do need some vanilla DOM (e.g. handling Ref elements and protals with React).
What's in the box?
-
Element Selection
$()
$$()
$id()
$class()
$tag()
- Element Creation
- Element Utils
-
Element Insertion
insert().before()
insert().after()
-
Event Binding
bindEvent()
bindEventOnce()
Installation
$ npm install --save sweet-dom
or grab the iife and drop it like it's hot.
Usage
import {createElm, bindEvent} from 'sweet-dom';
API
Element Selection
-
$
- an alias fordocument.querySelector()
-
$$
- an alias fordocument.querySelectorAll()
-
$id
- A shortcut fordocument.getElementById()
-
$class
- A shortcut fordocument.getElementsByClassName()
-
$tag
- A shortcut fordocument.getElementsByTagName()
The methods that return multiple elements,
$$
,$class
,$tag
- returns an array of elements instead of live-collections or node-lists.
All methods except
$id
also accepts a second argument: the context element to query (the default isdocument
).
const elm = $('#my-id');
const elms = $$('.my-classname');
const elm = $id('my-id');
const elms = $class('my-classname');
const elms = $tag('div');
// within context
const elms = $tag('div', containerElm);
Element Creation
createElm(selector, content1, content2, ...contentN)
Returns HTMLElement
selector
- Required
A string descriptor of an element. Supports a tag-name, an ID and classnames of the following format:
'tag#id.classname1.classname2'
// Results: <tag id="id" classname="classname1 classname2" />
const selector = 'input#first-name.form-field.required-field';
createElm(selector)
// <input id="first-name" classname="form-field required-field" />
...contents
- Optional
The created element's children, spread as arguments. Accepts HTML elements, nodes and strings.
// single
const contents = 'Click'
createElm('button', contents)
// <button>Click</button>
// multiple
createElm('button', iconElm, 'Click')
// spread arrays
const contents = [iconElm, 'Click']
createElm('button', ...contents)
//<button> ☻ Click</button>
createFrag(...contents?)
Returns DocumentFragment
...contents
Accepts HTML elements, nodes and strings.
Example:
createFrag(elm1, elm2, 'some string', elm3)
Element Utils
setStyle(elm, styleObject)
Sets an element inline style.
setStyle(divElm, {
height: '75px',
width: '200px',
});
/*
<div style="height: 75px; width: 200px;" />
*/
setAttributes(elm, attrObject)
Sets multiple attributes on an element.
setAttributes(inputElm, {
type: 'number',
name: 'age',
});
/*
<input type="number" name="age" />
*/
Element Insertion
For placing elements.
insert(elm)
.before(anotherElm)
.after(anotherElm)
Both methods accept an element or a query selector string. To insert multiple elements pass in a fragment with children (see createFrag) not an array of elements.
.before(anotherElm)
insert(elmA).before(elmB)
// <elmA>
// <elmB>
.after(anotherElm)
insert(elm).after('#logo')
// <div id="logo">
// <elm>
Event Binding
bindEvent()
bindEventOnce()
A wrapper around addEventListener()
.
Accepts the event-target as first argument and the rest are the same arguments as the vanilla addEventListener
.
Returns a remove-listener function
const unBindClick = bindEvent(elm, 'click', (ev) => {...})
// or:
const unBindClick = bindEventOnce(elm, 'click', (ev) => {...})
unBindClick();
Development
TDD
npm run dev
- Vitest + watch
Browser Playground
npm run play
- Open file in the browser:
./playground/playground.html
Check Stuff
-
npm run lint
- Eslint check issues -
npm run types
- TypeScript type checking -
npm run test
- Vitest (for build) -
npm run checks
- lint + types + test (all)
Publish a new version
-
version
script Note:
If something fromdist
folder is git tracked - add" && git add dist"
to end of the script$ npm version major|minor|patch
triggers:
-
preversion
- Runs thechecks
script -
version
- Runs thebuild
script-
prebuild
- Delete"dist"
folder -
build
- Rollup build for production -
postbuild
- Delete temporary declaration folder inside"dist"
-
-
postversion
- Git push + tags
-
-
$ npm publish
triggers:
-
prepublishOnly
- Runs thechecks
script
-