Behaviors

Most components need no script: the element they style already has the behavior. A few patterns have no native element, such as a combobox, a calendar grid or a splitter. For those the stylesheet draws the states from ARIA and native attributes, and a behavior is the reference script that coordinates input, focus and selection. Use this guide to attach one, read its value and release its listeners when the element leaves the page.

#What a behavior is

A behavior is one file with one function, named after the pattern. It takes the root element and returns a cleanup function that stops its listeners, observers and timers. Cleanup does not restore the original markup; a calendar, for example, keeps the month it drew. It is a plain ES module with no dependency, no framework and no build step.

The stylesheet can work with another script that maintains the same contract: the attributes, values and keyboard behavior must still agree. The framework components attach these same behaviors rather than reimplementing their keys.

#The behaviors

Each is imported from @master/ui/behaviors/<name>.js. The last column is the script field of the contract: required means the pattern does not work without a script, optional means the script adds to markup that already works.

#Attach one

First load the stylesheet, then write the contract's markup. Run the module after the root element exists, and pass the element carrying the root class. The bare package import below assumes your application resolves npm modules; a raw browser module needs a resolvable URL or import map.

<div class="combobox">  <div class="input-group">    <input class="input-group-field" id="region" role="combobox" aria-expanded="false" aria-controls="region-list" aria-autocomplete="list" autocomplete="off" aria-label="Region">    <button type="button" class="combobox-toggle" tabindex="-1" aria-label="Show regions"></button>  </div>  <div id="region-list" popover="manual" class="listbox" role="listbox" aria-label="Regions">    <div class="listbox-option" role="option" id="region-hnd" data-value="hnd" aria-checked="false">Tokyo</div>    <div class="listbox-option" role="option" id="region-sin" data-value="sin" aria-checked="false">Singapore</div>    <div class="listbox-empty">No regions match.</div>  </div></div>

import { combobox } from '@master/ui/behaviors/combobox.js'const detach = combobox(document.querySelector('.combobox'))

Type “Tok”, press ArrowDown and Enter, and confirm that the field shows Tokyo and detach.value is hnd. Call detach() when the element leaves the page. Attaching the same behavior twice to one root detaches its previous instance; it does not clean up listeners your application added.

#Attach all of them

attach() finds every pattern by its root class and attaches its behavior. It looks in the whole document, or in the element it is given and under it, and returns one function that detaches everything it attached.

import { attach } from '@master/ui/behaviors'const detach = attach()

Three things to know before choosing it over single imports:

• It attaches the optional behaviors too. Every menu gets the arrow keys, every tree becomes one tab stop and every tabs that is a role="tablist" switches its panels. To leave one as the platform has it, import behaviors by name.
• It passes no options. A calendar that picks a range, or has a first and a last day, is attached by name.
• A context menu belongs to a target only the page knows, so attach() does not attach one. Call contextMenu(target, menu).

It does not watch the document. For markup added later, call attach(element) on what was added and keep that call's cleanup function too. Call each cleanup before removing the corresponding roots.

#In a framework

For React, Svelte and Vue, each of these patterns has a component to copy into the project: it renders the markup, attaches the behavior and passes the value in and out. React, Svelte and Vue lists them. The rest of this section is for attaching a behavior yourself, in a component of your own.

The following snippets show attachment and cleanup only; place the full combobox markup from Attach one inside each root. Reattach when configuration options change. For application values and changing options, prefer the copied framework component or its adapter helper.

In React, useEffect takes the detach function as its cleanup:

import { useEffect, useRef } from 'react'import { combobox } from '@master/ui/behaviors/combobox.js'export function Combobox({ children }) {  const root = useRef(null)  useEffect(() => combobox(root.current), [])  return <div className="combobox" ref={root}>{children}</div>}

In Svelte, a behavior has the signature of an attachment, so {@attach} takes it as it is:

<script>  import { combobox } from '@master/ui/behaviors/combobox.js'</script><div class="combobox" {@attach combobox}>  <!-- the field and the listbox --></div>

An action returns an object, so in a version of Svelte without attachments wrap the behavior: const action = (node) => ({ destroy: combobox(node) }), then use:action.

In Vue, attach when the component is mounted and detach when it is unmounted:

<script setup>import { onMounted, onUnmounted, ref } from 'vue'import { combobox } from '@master/ui/behaviors/combobox.js'const root = ref(null)let detachonMounted(() => { detach = combobox(root.value) })onUnmounted(() => detach?.())</script><template>  <div class="combobox" ref="root"><slot /></div></template>

#Options

The behaviors below accept an options object as their second argument, for example calendar(root, options).

#Calendar

• value: the chosen day as YYYY-MM-DD, or the two ends of a range.
• month: the month to show first, as YYYY-MM.
• min, max: the first and last day that can be chosen.
• range: choose two days and every day between them.
• weekStart: the day in the first column, from 0 for Sunday to 6 for Saturday.
• locale: a BCP 47 language tag for the displayed names.
• disabled: a function that returns whether a day cannot be chosen.
• draw: a function that renders the grid instead of the behavior.

#Combobox

filter defaults to true: the behavior hides options whose text does not contain what was typed. Set it to false when the application supplies the matching options.

#Command palette

shortcut is the key combined with Command or Control to open and close the palette. It defaults to 'k'; set it to false to disable the shortcut. filter works as it does for the combobox.

#OTP

pattern is a regular expression each character must match. When omitted, the behavior reads the first slot's pattern attribute and falls back to digits when there is none.

#Splitter

step sets how far an arrow key moves the handle, in percentage points. It defaults to 5.

#Events

A behavior reports a change the way a native control does: with a DOM event that bubbles. Listen with addEventListener, or with the framework's own binding for native events.

The change of an OTP field, a calendar, a wheel, a tree and a tablist is a CustomEvent, because the value is not on one native control. A slot of an OTP field is a native input, so its own change bubbles through the root as well, without a detail. The command palette, the menu and the compare dispatch nothing of their own. A command runs from the click of its option, which Enter sends too, and the items of a menu are native buttons, links and inputs.

import { calendar } from '@master/ui/behaviors/calendar.js'const root = document.querySelector('.calendar')const detach = calendar(root, { value: '2026-11-13', min: '2026-11-01' })root.addEventListener('change', (event) => {  console.log(event.detail.value)})

#The value

Where a pattern has a value that no single native control holds, the function its behavior returns has a value. Read it for what is chosen now. Set it to choose from outside: that marks the pattern and dispatches nothing, as setting the value of a native input does.

An option, a tab and a row stand for their data-value, or for their text when they have none. Give data-value when the text is not what the application stores: data-value="hnd" on an option that says Tokyo.

import { combobox } from '@master/ui/behaviors/combobox.js'const region = combobox(document.querySelector('.combobox'))region.value = 'hnd'        // checks the option, writes "Tokyo" into the fieldconsole.log(region.value)   // "hnd"

A value the script writes into a field goes through the setter of the element's prototype. React shadows value on an input to notice its own writes and ignores an input event for a value it has already seen; written this way, a choice reaches onChange like typing does.

#Options from a server

By default the combobox and the command palette filter the options that are in the markup. When the page decides what matches, by asking a server or searching an index, pass filter: false: the script hides nothing, and the page writes the options as the reader types. Options that arrive while the list is open get an active option again, so Enter still chooses the first match.

import { combobox } from '@master/ui/behaviors/combobox.js'const root = document.querySelector('.combobox')const list = root.querySelector('[role="listbox"]')const selection = combobox(root, { filter: false })let request = 0root.querySelector('[role="combobox"]').addEventListener('input', async (event) => {  const current = ++request  if (selection.value !== null) return // Choosing an option also dispatches input.  const regions = await search(event.target.value)  if (current !== request || !root.isConnected) return  list.replaceChildren(...regions.map(option))})

Here search(text) is the application's async search function and option(region) builds one element with listbox-option, role="option", a unique id, data-value and aria-checked="false". Keep labels as text rather than injecting server strings as HTML. The request counter prevents an older response replacing newer results; provide loading, empty and error feedback in the application.

#A grid of your own

The calendar is the one behavior that writes elements: the weeks of the month it shows. A renderer that should write them itself, a template or a framework that renders on a server, passes draw. The script then writes no element. It calls draw with the month to show, as YYYY-MM, whenever that is not the month in the grid, and marks the days once they are there: today, the chosen ones, the ones that cannot be chosen and the one in the tab order.

calendarMonth() gives a month as data, the same data the script draws from: its title, the seven weekday names and its weeks. Each day is a calendar-day button whose value is its date; that is how the script knows the days it did not write. Given a value, and range for two ends, the data also says how each day is drawn: selected, tab for the one day in the tab order, and range for the classes of a day in a range. A renderer that writes them has the chosen day in its first HTML, before any script runs.

import { calendarMonth } from '@master/ui/behaviors/calendar.js'const month = calendarMonth('2026-11', {  value: '2026-11-13',  locale: 'en-GB'})const chosen = month.weeks.flat().find(day => day.selected)console.log(chosen.date) // "2026-11-13"console.log(chosen.tab)  // true

The renderer uses that data to produce the contract's markup:

After the grid exists, attach calendar(root, { value, locale, draw }), using the same initial value and locale. Your draw(month) callback renders another month's rows; the behavior marks the current selection and focus once those rows are present. Keep the title, weekday headers and grid labeling when replacing rows.

The calendar components for React, Svelte and Vue are written this way, so the month is in the first HTML.

#The keys

The keyboard list of a contract specifies the behavior shipped with that pattern. Read it with npx master-ui contract combobox:

A key the behavior handles calls preventDefault(). A key it does not handle is left alone, so Enter in a combobox with no active option still submits the form. Hidden items and those with disabled or aria-disabled="true" are skipped, and the horizontal arrow keys follow the direction of the text.

#Own a behavior

Keep importing the packaged behavior while it meets the application's needs; package upgrades then bring its fixes. When the project needs different keyboard or selection behavior, take the source and maintain that implementation:

npx master-ui own combobox

own copies the component's stylesheet, its contract and its behavior into the project, by default ui/combobox.css, ui/combobox.json and ui/combobox.js. From then on the script is the project's. Import it from there instead of from the package. Customization covers the rest of owning a component.

The combobox, command, listbox and menu behaviors import shared helpers from ./internal.js; own copies it beside them.

Keep the contract true while editing: the attributes the script moves are the ones the stylesheet reads, and the keyboard list should say what the keys now do.

#Without any script

The table lists packaged behaviors, not every application action that may need JavaScript. Native controls supply their own interaction where the browser supports it; consult the browser support guide for enhancement fallbacks. Several patterns in the table also have a form without a behavior:

• Tabs can be links or radio controls. The optional behavior is for a tablist that selects and shows associated panels.
• A tree is nested <details> elements whose <summary> is the row. Branches open and close by themselves and every row is a tab stop.
• A menu is a popover of buttons and links. The browser opens and closes it, Tab moves through the items and Escape returns focus to the button. Add role="menu" only together with the behavior, because the role promises arrow keys.

A few other contracts mark a script optional and name no behavior. The script there is a line or two for something HTML has no attribute for, such as the indeterminate state of a checkbox, and the component works without it.