id-dom

Deterministic DOM element getters by ID. Typed, tiny, modern. A small utility for grabbing DOM references safely by id, with predictable behavior.

Features

• Typed getters like button('saveBtn'), input('nameInput'), svg('icon')
• Strict or optional mode (throw vs null)
• Short optional alias via .opt
• Scoped lookups for document, ShadowRoot, DocumentFragment, or an Element
• Centralized error handling with onError and optional warn
• Zero dependencies

This is deliberately not a selector framework. It is a tiny, ID-first primitive for safe DOM wiring.

Install

pnpm add id-dom

Quick start

Two import styles, same root, same behavior. Pick by preference:

// Default-object style. Every typed helper lives under one namespace.
import dom from 'id-dom'

const saveBtn = dom.button('saveBtn')
saveBtn.addEventListener('click', save)

// Named-import style, added in 0.0.5. Makes the dependency surface explicit
// in the import declaration. Tree-shaken identically by modern bundlers
// (esbuild, vite, rollup, webpack 5) since the package ships
// `sideEffects: false`.
import { button, input, div } from 'id-dom'

const saveBtn = button('saveBtn')
const email   = input('email')
const panel   = div('mainPanel')

Optional access never throws for missing or wrong-type elements:

const debug = dom.div.optional('debugPanel')   // default-object style
debug?.append('hello')

import { canvas } from 'id-dom'
const maybeCanvas = canvas.opt('game')          // named style

API

Default export: dom

The default export is a scoped instance using document (when available) with strict behavior:

• missing element → throws
• wrong type or wrong tag → throws
• invalid input → throws

import dom from 'id-dom'

const name = dom.input('nameInput')
const submit = dom.button('submitBtn')

createDom(root, config?)

Create a scoped instance that searches within a specific root:

• document → uses getElementById
• ShadowRoot, DocumentFragment, or Element → uses querySelector(#id) fallback

import { createDom } from 'id-dom'

const d = createDom(document, { mode: 'null', warn: true })
const sidebar = d.div('sidebar')

Config:

type DomMode = 'throw' | 'null'

{
  mode?: DomMode
  warn?: boolean
  onError?: (err: Error, ctx: any) => void
}

byId(id, Type, config?)

Generic typed lookup:

import { byId } from 'id-dom'

const btn = byId('saveBtn', HTMLButtonElement)

Optional variants:

const maybeBtn = byId.optional('saveBtn', HTMLButtonElement)
const maybeBtn2 = byId.opt('saveBtn', HTMLButtonElement)

Behavior:

• valid match → returns the element
• missing element → throws or returns null
• wrong type → throws or returns null
• invalid id → throws or returns null
• invalid Type → throws or returns null

tag(id, tagName, config?)

Tag-based validation when constructor checks are not the right fit:

import { tag } from 'id-dom'

const main = tag('appMain', 'main')
const icon = tag('icon', 'svg', { root: container })

Optional variants:

const maybeMain = tag.optional('appMain', 'main')
const maybeMain2 = tag.opt('appMain', 'main')

Behavior:

• valid tag match → returns the element
• missing element → throws or returns null
• wrong tag → throws or returns null
• invalid id → throws or returns null
• invalid tagName → throws or returns null

Built-in getters

Typed getters available on dom and on any createDom() instance:

• el(id) → HTMLElement
• input(id) → HTMLInputElement
• button(id) → HTMLButtonElement
• textarea(id) → HTMLTextAreaElement
• select(id) → HTMLSelectElement
• form(id) → HTMLFormElement
• div(id) → HTMLDivElement
• span(id) → HTMLSpanElement
• label(id) → HTMLLabelElement
• canvas(id) → HTMLCanvasElement
• template(id) → HTMLTemplateElement
• svg(id) → SVGSVGElement
• body(id) → HTMLBodyElement

Each getter also has .optional and .opt variants:

dom.canvas.optional('game')
dom.canvas.opt('game')

Common tag helpers:

• main(id) → validates <main>
• section(id) → validates <section>
• small(id) → validates <small>

Each also supports .optional and .opt.

Error handling

Throwing mode:

import dom from 'id-dom'

dom.button('missing') // throws

Null-returning mode:

import { createDom } from 'id-dom'

const d = createDom(document, { mode: 'null' })
d.button('missing') // null

Central reporting:

const d = createDom(document, {
  mode: 'null',
  onError: (err, ctx) => {
    // sendToSentry({ err, ctx })
  },
})

Enable console warnings too:

createDom(document, { mode: 'null', warn: true })

Notes

Why id-first?

Using getElementById is fast, unambiguous, and easy to reason about. With typed getters, you immediately know whether you got a HTMLButtonElement, HTMLInputElement, SVGSVGElement, and so on.

When scoped roots do not support getElementById, id-dom falls back to querySelector(#id) and safely escapes edge-case IDs.

Bundle-size note

The shared lookup machinery (validation, CSS-escape fallback, error policy, root resolution) is the bulk of the package, roughly 1.9 KB gzipped in a modern bundler. Importing 4 helpers vs 1 vs the full default object lands in the same ballpark. The named-import style is recommended for readability and explicit-surface clarity, not for size.

Scoped roots

Shadow DOM:

import { createDom } from 'id-dom'

const host = document.querySelector('#widget')
const shadow = host.attachShadow({ mode: 'open' })
shadow.innerHTML = `<button id="shadowBtn">Click</button>`

const d = createDom(shadow)
const btn = d.button('shadowBtn')

Element root:

const container = document.querySelector('#settings-panel')
const d = createDom(container)
const input = d.input('emailInput')

SVG in scoped roots:

const container = document.querySelector('#icons')
const d = createDom(container)
const icon = d.svg('logoMark')

Misc

• el(id) is specifically for HTMLElement, not every possible DOM Element.
• body(id) looks up a <body> by ID. This library stays ID-first on purpose.
• tag() can validate non-HTML tags too, such as svg, when used against supported scoped roots.

Browser support

Modern browsers supporting:

• getElementById
• querySelector

CSS.escape is used when available. A safe internal fallback is included for environments such as some jsdom builds where it may be missing.

License

Licensed under AGPL-3.0 with WATT3D Additional Terms. See LICENSE and ADDITIONAL_TERMS.md. Commercial AI/model-training use requires compliance with those terms or a separate WATT3D license. © WATT3D.