LucidDOM.js

Getting started

Install with npm

Install the package from npm, then import its default export in your app. Use a bundler that resolves npm packages.

npm install luciddom

import LucidDOM from 'luciddom';

const app = new LucidDOM(document.querySelector('#app'));

Use unpkg CDN

To use LucidDOM directly in a browser without installing npm dependencies, import its ES module from unpkg:

<div id="app"></div>
<script type="module">
    import LucidDOM from 'https://unpkg.com/luciddom@1.0.1/lucidDOM.js';

    const app = new LucidDOM(document.querySelector('#app'));
</script>

The constructor accepts a parent DOM element. If omitted, it uses the document html tag as parent.

Create elements

Call addElement() on the instance to create an element, set its initial attributes, and append it to the parent.

const card = app.addElement({
    tag: 'article',
    className: 'card',
    id: 'welcome-card',
    value: 'Welcome to LucidDOM'
});

card.styles({ padding: '1rem', backgroundColor: '#fff' });

addElement() returns a handle with on(), off(), styles(), remove(), and addChildren() methods.

Use addChildren() to append a child to the created element. It accepts the same element options, including the required tag.

card.addChildren({
    tag: 'p',
    className: 'card__description',
    value: 'A child element'
});

Select elements

select() finds the first descendant of the configured parent matching a CSS selector and returns a helper handle.

const title = app.select('.page-title');

if (title.current) {
    title.update({ value: 'A new title' });
    title.styles({ color: 'darkslateblue' });
}

The handle exposes the matched element as current. Check that it exists before calling handle methods; the selector result can be null.

Selecting multiple elements

selectAll() returns a handle whose current property is the matching NodeList. Its helper methods apply to every matching element, including styles, events, classes, updates, removal, and child creation.

const cards = app.selectAll('.card');

cards.styles({ color: 'darkslateblue' });
cards.addClass('is-ready');
cards.update({ title: 'Ready' });
cards.on('click', (event) => console.log(event.currentTarget));

// You can still use the native NodeList for per-element logic.
cards.current.forEach((card) => {
    console.log(card.textContent);
});

Update elements

Use the handle returned by select() to set an element's content and supported attributes.

const button = app.select('#save');

button.update({
    value: 'Saved',
    className: 'button button--success',
    ariaLabel: 'Changes saved'
});

For text content, value sets the element's text and its value property. To insert markup, use html instead.

Events

Attach and remove event listeners on the parent instance or on an element handle. Pass the same callback reference to off() that you passed to on().

const saveButton = app.select('#save');

function save() {
    console.log('Saved');
}

saveButton.on('click', save);
saveButton.off('click', save);

Styles and classes

styles() merges an object of inline CSS properties into the parent or selected element. Use camelCase CSS property names.

app.styles({ fontFamily: 'sans-serif' });
app.select('.notice').styles({
    backgroundColor: 'moccasin',
    padding: '0.75rem'
});

Selected element handles also provide addClass(className) and removeClass(className).

API reference

• new LucidDOM(parent?) — create an instance scoped to a parent element; defaults to document.body.
• addElement(options) — create and append an element; returns a handle with event, style, remove, and child-creation methods.
• select(selector) — return a handle for the first matching descendant. Its current may be null.
• selectAll(selector) — return a handle with a current NodeList of matching descendants; handle methods apply to every match.
• on(event, callback) / off(event, callback) — add or remove an event listener on the instance's parent.
• styles(styleObject) — apply inline styles to the instance's parent.
• update(options) — on a select() handle, update supported attributes, text, or HTML.
• addClass(className) / removeClass(className) — on a select() handle, change a class.
• remove() — on a handle returned by creation or selection, remove its element from the DOM.

Element options

addElement() accepts a required tag and optional className, id, value, type, placeholder, name, htmlFor, formAction, formMethod, formTarget, formEnctype, formNoValidate, ariaLabel, title, and html.

Notes and limitations

For setup and a compact usage example, see the README.