Reference

Every stable element’s attributes, properties, methods, events, and CSS custom properties, generated from the code. Each element’s guide (linked) explains how to use it.

<attribute-cycler>

A persisted attribute or class switch (e.g. a theme toggle) driven by buttons. Guide · module @johnhenry/domkit/cyclable/attribute-cycler

Attributes

Attribute	Property	Type	Description
values	values	string	Comma-separated values to cycle through. An empty entry means “none”: no class, or no attribute.
attribute	attribute	string	The attribute to set on the targets. Default class, where the value is one class among the target’s others; any other attribute gets the value as its whole value.
target		string	Selector for the element(s) whose attribute is set. Default html.
storage-key	storageKey	string	localStorage key to persist under. Without it, the value isn’t persisted.
value	value	string	The current value. Reflects; set it to choose the initial value when nothing is stored.
disabled	disabled	boolean	Its buttons are disabled, and invoker commands are ignored.

Properties

Property	Type	Description
values (read-only)	string[]	The values to cycle through, in order.
attribute	string	The attribute set on the targets. Mirrors the attribute attribute.
value	string	The current value. Setting it applies and persists it, without an event.
targets (read-only)	Element[]	The elements whose attribute is set.
disabled	boolean	Mirrors the disabled attribute.
storageKey	string	Mirrors the storage-key attribute.

Methods

Method	Description
next()	Move to the next value (wrapping), without an event.
previous()	Move to the previous value (wrapping), without an event.
reset()	Forget the stored value and go back to the default (the value attribute as first written, or the first value), without an event.

Events

Event	Description
change	The user changed the value with a button or command.

<attribute-provider>

Add classes, styles, and attributes to children by media query. Guide · module @johnhenry/domkit/matchable/attribute-provider

Attributes

Attribute	Property	Type	Description
classes		string	[media query] class class | … sections. Bracket-less sections always apply.
styles		string	[media query] property: value; … | … sections.
attributes		string	[media query] name=value; name; name=null | … sections. null removes the attribute while the query matches.
container		string	Container mode: evaluate the queries against an element’s size instead of the viewport. Empty = the parent element; otherwise a selector for the closest matching ancestor.

Properties

Property	Type	Description
activeQueries (read-only)	string[]	The media (or container) queries that currently match, across classes, styles, and attributes, without duplicates.

Events

Event	Description
change	A query started or stopped matching (the viewport or container changed), so activeQueries changed and the children were updated.

<code-color>

Syntax highlighting that never touches your markup. Guide · module @johnhenry/domkit/code-color

Attributes

Attribute	Property	Type	Description
language	language	string	js, css, or html (plus aliases like javascript, ts, json, xml). Default: a language-* class on a <code> inside, else html.

Properties

Property	Type	Description
resolvedLanguage (read-only)	string | null	The language in effect: js, css, html, or null if unrecognized.
language	string	Mirrors the language attribute.

Methods

Method	Description
tokens()	The current token ranges, by type (for tests and tooling).

<define-component>

Register a custom element in HTML, from a module or from inline markup. Guide · module @johnhenry/domkit/definable/define-component

Attributes

Attribute	Property	Type	Description
name		string	The tag name to register.
src		string	URL of a module exporting the element class, resolved against the document’s base URL. Not allowed with inline markup.
import		string	With src: the name of the export to register. Default default.
content		string	Inline markup, if there’s no <template> child. Not allowed with src.
mode		string	With inline markup: open (default) or closed shadow root, or none to append the markup as light DOM.

Properties

Property	Type	Description
ready (read-only)	Promise<CustomElementConstructor>	Resolves with the registered class once the element is defined; rejects if it couldn’t be.

Events

Event	Description
load	The element is registered (or the name already was).
error	No source or two sources, an invalid name or mode, or (with src) the module failed to load, lacked the export, or the export isn’t a class. An ErrorEvent.

<draw-svg>

Self-drawing SVG strokes, CSP-safe and reduced-motion aware. Guide · module @johnhenry/domkit/draw-svg

Attributes

Attribute	Property	Type	Description
duration		string	How long each shape takes to draw: 2s, 400ms, or milliseconds. Default 2s.
delay		string	Wait before the first shape starts. Default 0.
stagger		string	Extra delay for each next shape, so they draw one after another. Default 0 (together).
easing		string	A CSS easing function. Default ease-in-out.
iterations		string	How many times to draw: a number or infinite. Default 1.
direction		string	normal, reverse, alternate, or alternate-reverse, as in CSS animations.
erase		boolean	After drawing in, keep going until the stroke has wiped itself out from its start.
select		string	Which shapes to animate, as a selector. Default: every path, line, polyline, polygon, circle, ellipse, and rect.
paused	paused	boolean	Whether it’s paused. Reflects; write it in markup to start paused (strokes hidden).
start		string	visible: wait to play until the drawing scrolls into view. Default: play on connect.

Properties

Property	Type	Description
paused (read-only)	boolean	Whether it’s paused.
shapes (read-only)	SVGGeometryElement[]	The shapes being animated.

Methods

Method	Description
play()	Start or resume drawing.
pause()	Pause where it is.
restart()	Draw again from the start (and play, unless paused).

Events

Event	Description
play	It started or resumed.
pause	It paused.
ended	Every shape finished drawing (not for iterations="infinite"). Invoker commands: --play, --pause, --toggle, and --restart (<button commandfor="logo" command="--restart">).

<drill-menu>

A list that drills into sub-screens and back. Guide · module @johnhenry/domkit/drill-menu

Attributes

Attribute	Property	Type	Description
screen	screen	string	Key of the screen currently shown (absent = the list). Reflects; set it to navigate.
disabled	disabled	boolean	Items can’t be activated, leave the tab order, and are marked aria-disabled. push()/pop() still work from script.
sync-hash	syncHash	boolean	Mirror the current screen in location.hash, so links and the browser’s Back button work.

Properties

Property	Type	Description
items (read-only)	Element[]	The items: element children other than templates and the screen.
screen	string | null	Key of the open screen, or null. Setting it navigates.
disabled	boolean	Mirrors the disabled attribute.
syncHash	boolean	Mirrors the sync-hash attribute.

Methods

Method	Description
push(key, options)	Show the screen of the item with this key (its data-key, or its position). Items without a template are leaves and can’t be pushed.
pop(options)	Return to the list, restoring focus to the item that opened the screen.

Events

Event	Description
push	A screen was shown. event.detail is { key, item }.
pop	The menu returned to the list. event.detail is { key, item } for the screen that closed.

<frame-timer>

A frame-paced ticking clock with play/pause. Guide · module @johnhenry/domkit/frame-timer

Attributes

Attribute	Property	Type	Description
paused	paused	boolean	Whether the timer is paused. Reflects; write it in markup to start paused.
fps	fps	number	Ticks per second. Default 60. Any positive number up to the display’s refresh rate.

Properties

Property	Type	Description
fps	number	Ticks per second.
paused (read-only)	boolean	Whether the timer is paused.
ticks	number	Ticks fired since the element was created (pausing keeps the count).

Methods

Method	Description
play()	Start or resume ticking.
pause()	Stop ticking (the count is kept).

Events

Event	Description
play	The timer started (or resumed).
pause	The timer paused. Invoker commands: --play, --pause, and --toggle (<button commandfor="clock" command="--toggle">).
tick	Once per period while playing. Read ticks for the count.

<gamepad-input>

Game controller buttons that send invoker commands. Guide · module @johnhenry/domkit/gamepad-input

Attributes

Attribute	Property	Type	Description
commandfor		string	The id of the element to send commands to. Without it, --custom commands bubble up from this element as command events, for an ancestor to handle.
index		number	Which controller (0 is the first connected). Default: any.
up		string	The command for the d-pad (or left stick) up. Likewise down, left, and right.
a		string	The command for the bottom face button. Likewise b (right), x (left), y (top), lb, rb, lt, rt, select, start, ls, rs, and home.
disabled	disabled	boolean	Button presses do nothing.

Properties

Property	Type	Description
disabled	boolean	Mirrors the disabled attribute.
commandForElement (read-only)	Element | null	The element commandfor names.

Events

Event	Description
gamepadpress	A button went down, before its command is sent. detail is { button, gamepad }; cancel it to skip the command. Fired even when that button has no command.

<hot-key>

Toggle a native dialog or popover, or run an invoker command, with a keyboard shortcut. Guide · module @johnhenry/domkit/hot-key

Attributes

Attribute	Property	Type	Description
hotkey	hotkey	string	One or more space-separated shortcuts, e.g. mod+k /. mod is ⌘ on Apple platforms and Ctrl elsewhere.
commandfor		string	The id of an element to send command to, as on a <button>. Without it, a --custom command bubbles up from this element as a command event (for an ancestor to handle), and with no command the shortcut toggles the <dialog> or popover inside.
command	command	string	With commandfor: the command to run, a built-in one (show-modal, close, request-close, show-popover, hide-popover, toggle-popover) or a custom --name (dispatched as a command event).
non-modal	nonModal	boolean	Open a dialog with show() instead of showModal().
disabled	disabled	boolean	The shortcut does nothing. The dialog or popover itself is unaffected.

Properties

Property	Type	Description
target (read-only)	HTMLElement | null	The <dialog> or popover this element opens and closes: its first <dialog> or [popover] descendant.
dialog (read-only)	HTMLDialogElement | null	The <dialog> this element controls, if its target is one.
command	string	Mirrors the command attribute.
commandForElement	Element | null	The element commandfor names, like a button’s commandForElement.
hotkey	string	Mirrors the hotkey attribute.
disabled	boolean	Mirrors the disabled attribute.
nonModal	boolean	Mirrors the non-modal attribute.
open (read-only)	boolean	Whether the dialog or popover is open.

Methods

Method	Description
show()	Open the dialog (modally, unless non-modal) or popover.
close(returnValue)	Close the dialog or popover.
toggle()	Open the dialog or popover if it’s closed, close it if it’s open.
runCommand()	Run command on the commandfor element, as a button would; without commandfor, a --custom command bubbles up from this element as a command event. Returns false if there’s no such element or command.

<infinite-combo-box>

An accessible autocomplete with paged (“infinite”) results. Guide · module @johnhenry/domkit/infinite-combo-box

Attributes

Attribute	Property	Type	Description
placeholder		string	Placeholder for the input.
disabled	disabled	boolean	Blocks interaction and form submission. Also inherited from a disabled fieldset.
required	required	boolean	The form is invalid until there’s a value.
open	open	boolean	Whether the option list is showing. Reflects.
value	value	string	Initial value (the value of an option, or text with allow-custom).
src	src	string	URL template for remote options: {query} and {cursor} are replaced (missing ones are added as ?q=/?cursor=). JSON (an array, or { options, next, total }) or HTML (with an optional data-next element).
inline		boolean	Render the list in normal flow under the input, instead of as a floating popup in the top layer.
name	name	string	Name submitted with the form.
debounce		number	Milliseconds to wait after typing before searching. Default 0 for local options, 200 for src/searchFunction.
page-size		number	Show the element’s own matching options this many at a time, loading more as the list scrolls.
min-length		number	Characters needed before searching. Default 0.
allow-custom	allowCustom	boolean	Typed text is a valid value even if it matches no option.

Properties

Property	Type	Description
value	string	The current value: the chosen option’s value, or the typed text with allow-custom. Setting it chooses the matching option (by value, then by label). Script changes don’t fire events.
text	string	The text in the input.
options (read-only)	Element[]	The options currently in the list.
hasMore (read-only)	boolean	Whether the source has more results for the current query.
selectedOption (read-only)	Element | null	The chosen option element, if it’s in the list.
selectedOptions (read-only)	Element[]	The chosen option as a list (0 or 1 items), like a select’s.
selectedIndex	number	Index of the chosen option among the options now in the list, or -1. Setting it chooses that option (-1 clears the value). Script changes don’t fire events.
length (read-only)	number	Number of options now in the list.
input (read-only)	HTMLInputElement | null	The inner <input> (generated, or the one you wrote as a child).
searchFunction	((query: string, init: { signal: AbortSignal, cursor: string }) => unknown) | null	A function that produces options for a query, instead of filtering the child <option>s or fetching src: async (query, { signal }) => an HTML string, an array of strings / { value, label } / Nodes, or a Node. signal aborts when a newer search starts. To page results, return { options, next, total? }: next is the cursor passed back as cursor for the following page (null when there are no more).
open	boolean	Mirrors the open attribute.
name	string	Mirrors the name attribute.
src	string	Mirrors the src attribute.
allowCustom	boolean	Mirrors the allow-custom attribute.
disabled	boolean	Mirrors the disabled attribute.
required	boolean	Mirrors the required attribute.
form (read-only)	HTMLFormElement | null
labels (read-only)	NodeList
validity (read-only)	ValidityState
validationMessage (read-only)	string
willValidate (read-only)	boolean
strings	Record<string, string | Record<string, string>>	The strings this element shows and announces (see DEFAULT_STRINGS). Setting it merges your values over the defaults, so you only pass the ones you change.

Methods

Method	Description
loadMore()	Load the next page of results for the current query (what scrolling to the end of the list does). Resolves when it’s appended.
item(index)	The option at index in the list.
checkValidity()
reportValidity()
setCustomValidity(message)
focus(options)	Focus the input.

Events

Event	Description
error
input	The user changed the value (chose an option, or typed with allow-custom).
change	The user committed a new value (chose an option, or left the field after typing with allow-custom).
toggle	The list opened or closed (a ToggleEvent with oldState/newState, like a popover).

CSS custom properties

Property	Description
--domkit-highlight	Background of the active option (shared token; see theme.css).
--domkit-surface	Background of the popup list (shared token).

<polyfill-window>

Load a module’s export onto window, in HTML. Guide · module @johnhenry/domkit/definable/polyfill-window

Attributes

Attribute	Property	Type	Description
name		string	The global to assign (window[name]).
src		string	URL of the module, resolved against the document’s base URL.
import		string	Name of the export to assign. Default default.

Properties

Property	Type	Description
ready (read-only)	Promise<unknown>	Resolves with the global’s value once it’s in place.

Events

Event	Description
error	The module failed to load or lacked the export. An ErrorEvent.
load	The global is in place (assigned now, or already there).

<query-container>

Swap the element wrapping some content by media query. Guide · module @johnhenry/domkit/matchable/query-container

Attributes

Attribute	Property	Type	Description
default	default	string	Wrapper when no query matches, as a simple selector (ul, ol.steps, div#x[data-y=z]). Defaults to the first section’s.
query	query	string	[media query] selector sections separated by |. The last matching section wins.
container		string	Container mode: evaluate the queries against an element’s size instead of the viewport. Empty = the parent element; otherwise a selector for the closest matching ancestor.

Properties

Property	Type	Description
default	string	Mirrors the default attribute.
query	string	Mirrors the query attribute.
activeQueries (read-only)	string[]	The media (or container) queries that currently match, in the order they’re written.
wrapper (read-only)	Element | null	The element currently wrapping the children.

Events

Event	Description
change	A query started or stopped matching (the viewport or container changed), so activeQueries changed. The wrapper may have been swapped.

<stylable-select>

A fully stylable listbox that works like a native select. Guide · module @johnhenry/domkit/stylable-select

Attributes

Attribute	Property	Type	Description
disabled	disabled	boolean	Blocks interaction and form submission. Also inherited from a disabled fieldset.
required	required	boolean	The form is invalid until an option is selected.
multiple	multiple	boolean	Allow selecting more than one option.
size	size	number	Number of visible rows (sets --domkit-select-size, used by index.css).
name	name	string	Name submitted with the form.

Properties

Property	Type	Description
options (read-only)	Element[]	Every option, in document order (including those in groups).
selectedOptions (read-only)	Element[]	The selected options.
selectedOption (read-only)	Element | null	The first selected option, or null (like infinite-combo-box’s).
selectedIndex	number	Index of the first selected option, or -1. Setting it selects only that option. Script changes don’t fire events.
value	string	Value of the first selected option, or “”. Setting it selects the first option with that value (or nothing, if none matches).
length (read-only)	number	Number of options.
type (read-only)	string	“select-one” or “select-multiple”, like a native select.
name	string	Mirrors the name attribute.
multiple	boolean	Mirrors the multiple attribute.
disabled	boolean	Mirrors the disabled attribute.
required	boolean	Mirrors the required attribute.
size	number	Mirrors the size attribute.
form (read-only)	HTMLFormElement | null	The form this element belongs to.
labels (read-only)	NodeList	Labels associated with this element.
validity (read-only)	ValidityState
validationMessage (read-only)	string
willValidate (read-only)	boolean

Methods

Method	Description
item(index)	The option at index.
namedItem(name)	The first option whose id or name is name, like a select’s.
add(element, before)	Add an option or optgroup, like a select’s add(): before before (an option element or an index), or at the end. Throws a NotFoundError if before is an element that isn’t in this list.
remove(index)	With an index, remove that option, like a select’s remove(index). With no argument, remove this element itself, as on any element.
checkValidity()
reportValidity()
setCustomValidity(message)

Events

Event	Description
input	The user changed the selection.
change	The user changed the selection (fired right after input, like a native select).

CSS custom properties

Property	Description
--domkit-select-size	Visible rows, from the size attribute.
--domkit-highlight	Background of selected options (shared token; see theme.css).
--domkit-focus-ring	Focus outline (shared token).

<swipe-input>

Swipe gestures that send invoker commands. Guide · module @johnhenry/domkit/swipe-input

Attributes

Attribute	Property	Type	Description
commandfor		string	The id of the element to send commands to. Without it, --custom commands bubble up from this element as command events, for an ancestor to handle.
up		string	The command for a swipe up (for example --up, or a built-in like show-popover).
down		string	The command for a swipe down.
left		string	The command for a swipe left.
right		string	The command for a swipe right.
threshold		number	How far, in CSS pixels, a pointer must travel to count as a swipe. Default 30.
pointers		string	Which pointers swipe: touch, pen, mouse, or a space-separated mix. Default: all of them.
disabled	disabled	boolean	Swipes do nothing.

Properties

Property	Type	Description
disabled	boolean	Mirrors the disabled attribute.
commandForElement (read-only)	Element | null	The element commandfor names.

Events

Event	Description
swipe	A swipe was recognized, before its command is sent. detail is { direction, distance }; cancel it to skip the command. Fired even when that direction has no command.

<tabbed-ui>

Accessible tabs and panels from plain children. Guide · module @johnhenry/domkit/tabbed-ui

Attributes

Attribute	Property	Type	Description
selected-index	selectedIndex	number	Index of the selected tab. Reflects the current selection.
manual	manual	boolean	Arrow keys move focus only; Enter/Space selects (manual activation).
disabled	disabled	boolean	No tab can be selected by the user (or by commands), and the tabs leave the tab order. Panels stay as they are.

Properties

Property	Type	Description
disabled	boolean	Mirrors the disabled attribute.
tabList (read-only)	Element | null	The tab list: the child with role=“tablist”, else the first element child.
tabs (read-only)	Element[]	The tabs, in order.
panels (read-only)	Element[]	The panels, in order (every element child except the tab list).
selectedIndex	number	Index of the selected tab. Setting it does not fire change.
manual	boolean	With manual, arrow keys move focus and Enter/Space selects.

Methods

Method	Description
next()	Select the next enabled tab (wrapping), without an event.
previous()	Select the previous enabled tab (wrapping), without an event.

Events

Event	Description
change	The user selected a different tab (click, keyboard, or an invoker command). Not fired for script changes.

CSS custom properties

Property	Description
--domkit-tab-gap	Space between tabs (index.css).
--domkit-tab-padding	Padding inside each tab (index.css).
--domkit-accent	Selected-tab indicator (shared token; see theme.css).
--domkit-border	Line under the tab list (shared token).
--domkit-focus-ring	Focus outline of tabs and panels (shared token).