Command primitive

Headless Command: the behavior, keyboard support and ARIA of the WAI-ARIA Combobox pattern, with no styles.

@ndop/primitives/command
WAI-ARIA: Combobox

Import

Primitives ship in the @ndop/primitives package and have no styles. Their state is on data attributes for you to style. The styled Command is built on this one.

import {
  NdCommand,
  NdCommandGroup,
  NdCommandEmpty,
  NdCommandGroupHeading,
  NdCommandInput,
  NdCommandItem,
  NdCommandList,
  NdCommandSeparator,
} from '@ndop/primitives/command';

Accessibility

Implements the Combobox pattern of the WAI-ARIA Authoring Practices.

Keyboard

Keys the component handles.

Key	Action
`ArrowDown`or`ArrowUp`	Highlights the next or previous shown, enabled item.
`Home`or`End`	Moves the caret in the field, as in any text field.
`Enter`	Runs the highlighted item.
`a`	Types into the field, filtering the list.

Focus

Focus stays in the field; aria-activedescendant points at the highlighted item, which scrolls into view.
Clicking an item runs it.

Right-to-left

Nothing mirrors: the list is vertical, and the field follows the text direction.

API reference

NdCommand

[ndCommand]from @ndop/primitives/command

A command menu: a search field over a list of commands that it filters as the user types, such as a ⌘K palette (WAI-ARIA combobox pattern with an always-visible listbox). Focus stays in the field and aria-activedescendant points at the highlighted command, on the CDK's ActiveDescendantKeyManager. Put it in a Dialog for a palette.

NdCommand binding	Type	Default
`[label]` Names the field and the list for assistive technology.	`string \| null`	`null`
`[filter]` Tests whether an item matches what was typed.	`NdFilter`	`ndContainsFilter`
`[shouldFilter]` Hides the items that don't match; `false` for lists filtered elsewhere.	`boolean`	`true`
`[loop]` Makes the arrow keys wrap at the ends.	`boolean`	`false`
`[(search)]` The field's text. Two-way bindable with `[(search)]`.	`string`	`''`

NdCommandGroup

[ndCommandGroup]role groupfrom @ndop/primitives/command

Groups commands (role="group"), named by its NdCommandGroupHeading. It's hidden while none of its commands is shown.

Manages aria-labelledby, hidden.

NdCommandEmpty

[ndCommandEmpty]from @ndop/primitives/command

What shows while no command matches the search. It has the hidden attribute otherwise.

Manages hidden.

NdCommandGroupHeading

[ndCommandGroupHeading]from @ndop/primitives/command

The heading of a NdCommandGroup, which names the group. It's hidden from assistive technology itself, which reads it as the group's name.

Manages id, aria-hidden.

NdCommandInput

input[ndCommandInput]role comboboxfrom @ndop/primitives/command

The search field (role="combobox"), on a native input. Typing filters the list; ArrowDown and ArrowUp move the highlight and Enter runs the highlighted command, while focus stays here.

Manages aria-expanded, aria-controls, aria-activedescendant, aria-autocomplete, aria-label.

NdCommandItem

[ndCommandItem]role optionfrom @ndop/primitives/command

One command (role="option"). Clicking it, or Enter while it's highlighted, emits triggered. It's hidden while the search doesn't match its text or keywords.

Manages aria-selected, aria-disabled, id, hidden.

NdCommandItem binding	Type	Default
`[value]` Identifies it; defaults to its text.	`string \| null`	`null`
`[keywords]` Other words the search matches it by, separated by spaces.	`string`	`''`
`[disabled]` Makes it inert; the arrow keys skip it.	`boolean`	`false`
`(triggered)` Emits when it's run.	`void`	`—`

Data attribute	Values
`data-selected`	—
`data-disabled`	—
`data-value`	—

NdCommandList

[ndCommandList]role listboxfrom @ndop/primitives/command

The list of commands (role="listbox"), named by the command menu's label.

Manages aria-label, id.

NdCommandSeparator

[ndCommandSeparator]from @ndop/primitives/command

A decorative line between groups, hidden while searching.

Manages aria-hidden, hidden.