Command
A searchable list of commands: type to filter, arrows to highlight, Enter to run. The core of a ⌘K palette.
c2-command
A searchable list of commands: a search field above c2-command-item rows, optionally sorted into
c2-command-groups and split by c2-command-separators. Typing filters the rows (every word of the query must appear in
a row's label, value or keywords), hides the groups left without a match and shows the empty slot when nothing
matches. Put it in a c2-modal for a ⌘K palette, or inline in a page or a popover.
Focus never leaves the search field. Arrow Up/Down move the highlight between the enabled matching rows (wrapping
with loop), Enter activates the highlighted row and a click activates the clicked one. Activation fires
command-select; a row with href then navigates unless the event was cancelled. The field is a combobox whose
aria-activedescendant tracks the highlighted option.
Set manual-filter when the rows come from a server: the palette then shows every row, and the app filters on
input (read query) and replaces the rows.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
query | string | — | The search text. Setting it filters the rows as typing does. |
placeholder | string | Type a command or search… | Placeholder of the search field. |
label | string | Search commands | Accessible name of the search field and the list. |
manual-filter | boolean | false | Show every row whatever the query, for rows the app filters itself (a server search). |
loop | boolean | false | Arrow keys wrap from the last row to the first and back. |
Slots
| Name | Description |
|---|---|
default | The rows: c2-command-item, c2-command-group and c2-command-separator elements (separators are hidden while a query is typed). |
prefix-icon | Icon before the search field. Defaults to a magnifier. |
suffix | Content after the search field, such as an esc hint or a spinner. |
empty | Shown when no row matches. Defaults to "No results found." |
footer | A bar under the list, such as keyboard hints. |
Events
| Name | Type | Description |
|---|---|---|
command-select | CustomEvent<CommandSelectEventDetail> | Fired on the palette when a row is activated by Enter or a click. Cancelable: cancelling it stops an href row from navigating. Does not bubble. |
input | InputEvent | Re-dispatched from the search field whenever the query changes; read query. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
field | The row holding the icon, the search input and the suffix. |
input | The native search <input>. |
list | The scrolling listbox around the rows. |
empty | The container of the empty slot. |
footer | The container of the footer slot. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-command--background | color | #ffffff | |
--c2-command--color | color | #18181b | |
--c2-command--font-family | font-family | — | |
--c2-command--width | pixel | — | Defaults to the width of the container. |
--c2-command--max-height | pixel | none | Caps the height of the whole palette: the field and the footer stay in view and the list shrinks to the space left, scrolling on its own. Pair it with --c2-command__list--max-height: none to let the list grow past its own cap and fill that height. Keep the host's display: flex. |
--c2-command--border-top | border | 1px solid #e4e4e7 | |
--c2-command--border-right | border | 1px solid #e4e4e7 | |
--c2-command--border-bottom | border | 1px solid #e4e4e7 | |
--c2-command--border-left | border | 1px solid #e4e4e7 | |
--c2-command--border-top-left-radius | border-radius | 8px | |
--c2-command--border-top-right-radius | border-radius | 8px | |
--c2-command--border-bottom-left-radius | border-radius | 8px | |
--c2-command--border-bottom-right-radius | border-radius | 8px | |
--c2-command--box-shadow | box-shadow | — | |
--c2-command__field--min-height | pixel | 48px | |
--c2-command__field--gap | pixel | 8px | |
--c2-command__field--padding-right | padding | 12px | |
--c2-command__field--padding-left | padding | 12px | |
--c2-command__field--border-bottom | border | 1px solid #e4e4e7 | |
--c2-command__field--font-size | font-size | 14px | |
--c2-command__placeholder--color | color | #71717a | |
--c2-command__icon--size | pixel | 16px | |
--c2-command__icon--color | color | #71717a | |
--c2-command__list--max-height | pixel | 320px | The list scrolls past this height. Set none to let the list take whatever --c2-command--max-height leaves. |
--c2-command__list--padding-top | padding | 4px | |
--c2-command__list--padding-right | padding | 4px | |
--c2-command__list--padding-bottom | padding | 4px | |
--c2-command__list--padding-left | padding | 4px | |
--c2-command__list--gap | pixel | — | Space between the rows and groups. |
--c2-command__empty--color | color | #71717a | |
--c2-command__empty--font-size | font-size | 14px | |
--c2-command__empty--padding | padding | 24px 8px | |
--c2-command__footer--border-top | border | 1px solid #e4e4e7 | |
--c2-command__footer--padding | padding | 8px 12px | |
--c2-command__footer--color | color | #71717a | |
--c2-command__footer--font-size | font-size | 12px | |
c2-command-item
One command of a c2-command palette. The palette filters rows against the query, highlights one of them and
activates it on Enter or a click; the row itself never handles the keyboard and never takes focus, which stays in the
palette's search field. The default slot is the label, description a second muted line, prefix-icon /
suffix-icon take an inline SVG or an icon element, and shortcut holds a keyboard hint (plain text or a c2-kbd).
The row matches when every word of the query appears in its label, its value or its keywords. With href the
row is a link: activating it navigates unless the palette's command-select event is cancelled.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
value | string | — | The value reported in command-select, also matched against the query. Defaults to the label text. |
keywords | string | — | Extra words the query matches, separated by spaces or commas (synonyms, ids, tags). |
disabled | boolean | false | Dims the row; it can be matched but never highlighted or activated. |
href | string | undefined | — | Makes the row a link that activating it navigates to. |
target | string | undefined | — | Browsing context used when href is set, such as _blank. |
Slots
| Name | Description |
|---|---|
default | The row label, also the text the palette matches. Falls back to value when empty. |
description | Secondary line under the label (muted, smaller). Not matched. |
prefix-icon | Icon shown before the label. |
suffix-icon | Icon or badge shown after the label. |
shortcut | Keyboard hint, aligned to the end of the row. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
row | The row box: a <div>, or an <a> when href is set. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-command-item--min-height | pixel | 36px | |
--c2-command-item--gap | pixel | 8px | Space between the icons, label and shortcut. |
--c2-command-item--border-top-left-radius | border-radius | 6px | |
--c2-command-item--border-top-right-radius | border-radius | 6px | |
--c2-command-item--border-bottom-left-radius | border-radius | 6px | |
--c2-command-item--border-bottom-right-radius | border-radius | 6px | |
--c2-command-item--padding-top | padding | 8px | |
--c2-command-item--padding-right | padding | 8px | |
--c2-command-item--padding-bottom | padding | 8px | |
--c2-command-item--padding-left | padding | 8px | |
--c2-command-item--font-size | font-size | 14px | |
--c2-command-item--font-weight | font-weight | — | |
--c2-command-item--font-family | font-family | — | |
--c2-command-item--line-height | pixel | 20px | |
--c2-command-item--color | color | #18181b | |
--c2-command-item--background | color | transparent | |
--c2-command-item__active--background | color | #f4f4f5 | The highlighted row (keyboard or pointer). |
--c2-command-item__active--color | color | — | Defaults to the row colour. |
--c2-command-item__description--color | color | #71717a | |
--c2-command-item__description--font-size | font-size | 12px | |
--c2-command-item__description--line-height | pixel | 16px | |
--c2-command-item__shortcut--color | color | #71717a | |
--c2-command-item__shortcut--font-size | font-size | 12px | |
--c2-command-item__icon--size | pixel | 16px | |
--c2-command-item__icon--color | color | #71717a | |
--c2-command-item__disabled--opacity | opacity | 0.38 | |
c2-command-group
A labelled group of c2-command-item rows inside a c2-command. The palette hides the whole group, heading
included, while none of its rows matches the query.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
heading | string | — | Heading text shown above the rows; also the group's accessible name. |
Slots
| Name | Description |
|---|---|
default | The c2-command-item rows of the group. |
heading | Rich heading content; replaces the heading text. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
heading | Heading region wrapping the heading slot and the heading text fallback; assigned content keeps its own styles. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-command-group__heading--color | color | #71717a | |
--c2-command-group__heading--font-size | font-size | 12px | |
--c2-command-group__heading--font-weight | font-weight | 500 | |
--c2-command-group__heading--letter-spacing | letter-spacing | — | |
--c2-command-group__heading--text-transform | text-transform | — | |
--c2-command-group__heading--padding-top | padding | 8px | |
--c2-command-group__heading--padding-right | padding | 8px | |
--c2-command-group__heading--padding-bottom | padding | 4px | |
--c2-command-group__heading--padding-left | padding | 8px | |
c2-command-separator
A divider between rows or groups of a c2-command. It divides the full list only: the palette hides every separator
while a query is typed, so the groups that survive the filter stand on their own. Purely presentational (role="none");
a native <hr> is not allowed inside the palette's listbox.
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-command-separator--color | color | #e4e4e7 | |
--c2-command-separator--margin | margin | 4px -4px | |