{"id":11330,"library":"min-dom","title":"Minimal DOM Utility Toolbelt","description":"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.","status":"active","version":"5.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/bpmn-io/min-dom","tags":["javascript","dom","util","utility","minimal","event","query","jquery","component","typescript"],"install":[{"cmd":"npm install min-dom","lang":"bash","label":"npm"},{"cmd":"yarn add min-dom","lang":"bash","label":"yarn"},{"cmd":"pnpm add min-dom","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for converting HTML strings to DOM elements.","package":"domify","optional":false},{"reason":"Provides minimal lodash-inspired utility functions internally.","package":"min-dash","optional":false}],"imports":[{"note":"min-dom is primarily designed for ESM consumption, though CJS is supported.","wrong":"const query = require('min-dom').query;","symbol":"query","correct":"import { query } from 'min-dom';"},{"note":"All core utilities are exported as named exports from the main package entry point.","wrong":"import domify from 'min-dom/lib/domify';","symbol":"domify","correct":"import { domify } from 'min-dom';"},{"note":"The `event` object bundles `on`, `off`, and `bind` methods for event handling.","wrong":"import { on } from 'min-dom.event';","symbol":"event","correct":"import { event } from 'min-dom';"},{"note":"Directly imports the `closest` utility, which leverages native `Element.closest`.","wrong":"import { findClosest } from 'min-dom';","symbol":"closest","correct":"import { closest } from 'min-dom';"}],"quickstart":{"code":"import { domify, query, classes, event } from 'min-dom';\n\n// 1. Create a DOM element from an HTML string\nconst myElement = domify('<div class=\"container\"><p id=\"greeting\">Hello, <span class=\"name\">World</span>!</p><button>Click me</button></div>');\n\n// Append it to the body for demonstration\ndocument.body.appendChild(myElement);\n\n// 2. Query for elements within the created element\nconst greetingParagraph = query('#greeting', myElement);\nconst nameSpan = query('.name', greetingParagraph);\nconsole.log('Greeting paragraph text:', greetingParagraph.textContent);\n\n// 3. Manipulate classes\nclasses(myElement).add('active');\nclasses(myElement).remove('container');\nconsole.log('myElement classes:', myElement.className);\n\n// 4. Attach an event listener\nconst button = query('button', myElement);\nconst handler = (e) => {\n  console.log('Button clicked!', e.target.tagName);\n  classes(button).toggle('clicked');\n  event.off(button, 'click', handler); // Remove after first click\n};\nevent.on(button, 'click', handler);\n\n// Clean up after a few seconds\nsetTimeout(() => {\n  if (myElement.parentNode) {\n    myElement.parentNode.removeChild(myElement);\n    console.log('Element removed from DOM.');\n  }\n}, 3000);","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"min-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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always validate selector strings before passing them to `query` or `closest`. Ensure they are non-empty and syntactically correct CSS selectors.","message":"When 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Correct your event binding to `import { event } from 'min-dom'; event.on(element, 'event', handler);`","cause":"Attempting to call `on(element, 'event', handler)` directly instead of `event.on(...)`.","error":"TypeError: Cannot read properties of undefined (reading 'on')"},{"fix":"Use named imports for all utilities: `import { query, domify } from 'min-dom';`","cause":"Attempting to import `min-dom` with a default import statement (`import MinDom from 'min-dom'`).","error":"Uncaught SyntaxError: The requested module 'min-dom' does not provide an export named 'default'"},{"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.","cause":"Passing an invalid or empty string as the selector argument to `closest` or `query`.","error":"Element.closest: The selector is not a valid selector."}],"ecosystem":"npm"}