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
  • createElm()
  • createFrag()
• Element Utils
  • setStyle()
  • setAttributes()
• 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 for document.querySelector()
• $$ - an alias for document.querySelectorAll()
• $id - A shortcut for document.getElementById()
• $class - A shortcut for document.getElementsByClassName()
• $tag - A shortcut for document.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 is document).

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()
• createFrag()

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()
• setAttributes()

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

1. npm run play
2. 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 from dist folder is git tracked - add " && git add dist" to end of the script

1. $ npm version major|minor|patch

   triggers:

   • preversion - Runs the checks script
   • version - Runs the build script
     • prebuild - Delete "dist" folder
     • build - Rollup build for production
     • postbuild - Delete temporary declaration folder inside "dist"
   • postversion - Git push + tags

    

2. $ npm publish

   triggers:

   • prepublishOnly - Runs the checks script