min-dom

library5.3.0jsnpmunverified

min-dom is a focused and lightweight JavaScript library, currently at version 5.3.0, providing a collection of essential DOM manipulation utilities. It emphasizes a minimal footprint, weighing approximately 2KB gzipped, making it suitable for environments where bundle size is critical. The library maintains an active release cadence, with recent updates ensuring compatibility and minor feature enhancements. Key differentiators include its small size, its inspiration from the `component` project's utilities, and its provision of common helpers like `assignStyle`, `attr`, `classes`, `clear`, `closest`, `delegate`, `domify`, `event`, `matches`, `query`, and `remove`. It is designed to be library-friendly and ships with TypeScript types for improved developer experience in typed projects.

web-framework http-networking

npm install min-dom

github ↗package ↗

INSTALL

IMPORT

SIG · MIN-DOM

min-dom

web-frameworkjavascriptv5.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

query

✓ import { query } from 'min-dom';

✗ const query = require('min-dom').query;

min-dom is primarily designed for ESM consumption, though CJS is supported.

domify

✓ import { domify } from 'min-dom';

✗ import domify from 'min-dom/lib/domify';

All core utilities are exported as named exports from the main package entry point.

event

✓ import { event } from 'min-dom';

✗ import { on } from 'min-dom.event';

The `event` object bundles `on`, `off`, and `bind` methods for event handling.

closest

✓ import { closest } from 'min-dom';

✗ import { findClosest } from 'min-dom';

Directly imports the `closest` utility, which leverages native `Element.closest`.

This quickstart demonstrates creating elements with `domify`, querying the DOM using `query`, manipulating CSS classes with `classes`, and handling events with `event.on`/`event.off`.

import { domify, query, classes, event } from 'min-dom'; // 1. Create a DOM element from an HTML string const myElement = domify('<div class="container"><p id="greeting">Hello, <span class="name">World</span>!</p><button>Click me</button></div>'); // Append it to the body for demonstration document.body.appendChild(myElement); // 2. Query for elements within the created element const greetingParagraph = query('#greeting', myElement); const nameSpan = query('.name', greetingParagraph); console.log('Greeting paragraph text:', greetingParagraph.textContent); // 3. Manipulate classes classes(myElement).add('active'); classes(myElement).remove('container'); console.log('myElement classes:', myElement.className); // 4. Attach an event listener const button = query('button', myElement); const handler = (e) => { console.log('Button clicked!', e.target.tagName); classes(button).toggle('clicked'); event.off(button, 'click', handler); // Remove after first click }; event.on(button, 'click', handler); // Clean up after a few seconds setTimeout(() => { if (myElement.parentNode) { myElement.parentNode.removeChild(myElement); console.log('Element removed from DOM.'); } }, 3000);

Debug

Known issues

breakingmin-dom v5.0.0 updated its internal dependency to `domify@2`, which may introduce breaking changes if you relied on specific internal behaviors or undocumented APIs of `domify` directly. Always review the `domify` changelog when upgrading `min-dom` across major versions.

fix

Review the changelog for `domify@2` and `min-dom@5.0.0` to understand potential impacts. Test your application thoroughly after upgrading. If you had custom shims or overrides for `domify`, they might need adjustments.

affects: >=5.0.0

gotchaThe `event` utility bundles methods `on`, `off`, and `bind`. When listening for events, you must pass the `event` object itself to access these methods, e.g., `event.on(element, 'click', handler)`. Do not destructure `on` directly from `min-dom` as a top-level export.

fix

Ensure you are calling `event.on`, `event.off`, or `event.bind` rather than attempting to call `on` or `off` directly if you've destructured `event` or are using an incorrect import pattern.

affects: >=1.0.0

gotchaWhen using `query` or `closest`, providing an invalid selector string (e.g., an empty string or malformed selector) can lead to unexpected behavior or errors, as these methods often rely on native browser APIs like `querySelector` or `closest`.

fix

Always validate selector strings before passing them to `query` or `closest`. Ensure they are non-empty and syntactically correct CSS selectors.

affects: >=1.0.0

gotchaThe `domify` function takes an HTML string. If this string contains untrusted user input, it can lead to Cross-Site Scripting (XSS) vulnerabilities, as the HTML will be parsed and potentially inserted into the DOM.

fix

Sanitize any user-provided HTML strings before passing them to `domify`. Consider using a dedicated HTML sanitization library or ensuring that only trusted sources provide the HTML content.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'on')

Attempting to call `on(element, 'event', handler)` directly instead of `event.on(...)`.

fix

Correct your event binding to `import { event } from 'min-dom'; event.on(element, 'event', handler);`

Uncaught SyntaxError: The requested module 'min-dom' does not provide an export named 'default'

Attempting to import `min-dom` with a default import statement (`import MinDom from 'min-dom'`).

fix

Use named imports for all utilities: `import { query, domify } from 'min-dom';`

Element.closest: The selector is not a valid selector.

Passing an invalid or empty string as the selector argument to `closest` or `query`.

fix

Ensure the selector string is a valid CSS selector and not empty. For example, `closest(element, '.my-class')` is correct, but `closest(element, '')` will fail.

Upgrade

Version history

5.3.0latest on npm

Audit

Dependencies

domifyrequiredUsed for converting HTML strings to DOM elements.

min-dashrequiredProvides minimal lodash-inspired utility functions internally.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/bpmn-io/min-dom ↗

packagehttps://www.npmjs.com/package/min-dom ↗