Liking cljdoc? Tell your friends :D

x-command-palette

A searchable command list overlay (⌘K pattern). Opens as a modal with a text input that filters a list of commands supplied via the items JS property. Supports keyboard navigation, groups, disabled items, and a scrim backdrop.


Tag

<x-command-palette></x-command-palette>

Attributes

AttributeTypeDefaultDescription
openbooleanfalseWhether the palette is visible
modalboolean†trueAdds focus trap and blocks background interaction
dismissibleboolean†trueAllow closing via Escape or backdrop click
no-scrimbooleanfalseHides the backdrop scrim even in modal mode
close-on-scrimboolean(see below)Close when backdrop is clicked (default: same as scrim visibility)
close-on-escapeboolean†trueClose on Escape key
disabledbooleanfalseDisables the palette and all interactions
placeholderstring"Search…"Input placeholder text
empty-textstring"No results"Text shown when no items match the query
filterstring"default"default shows the items that match the query. none shows every item, in the order given
labelstring—aria-label on the dialog element

†Default-true boolean: absent = true; attribute="false" = false.


Properties

PropertyTypeDescription
itemsarrayCommand items. Each item: { id, label, keywords?, group?, value?, icon?, disabled? }
openbooleanReflects open attribute
disabledbooleanReflects disabled attribute
modalbooleanReflects modal. true when the attribute is absent
dismissiblebooleanReflects dismissible. true when the attribute is absent
closeOnEscapebooleanReflects close-on-escape. true when the attribute is absent
noScrimbooleanReflects no-scrim
closeOnScrimbooleanReflects close-on-scrim. Reads the effective value, which follows the scrim when the attribute is absent. Writes "true" or "false", and null removes the attribute
labelstringReflects label
placeholderstringReflects placeholder, default "Search…"
emptyTextstringReflects empty-text, default "No results"
filterstringReflects filter, default "default"

Item shape

{
  id:        string           // required, unique identifier
  label:     string           // required, displayed text
  keywords?: string | string[] // extra search terms
  group?:    string           // group heading
  value?:    any              // arbitrary payload in select event detail
  icon?:     string           // icon glyph or URL
  shortcut?: string           // text shown in an x-kbd at the end of the row
  disabled?: boolean          // greys out item, skips in keyboard nav
}

shortcut is documentation only. The palette shows it with x-kbd, so "Mod+S" reads ⌘S on a Mac and Ctrl+S elsewhere, and any other text shows as it is. The palette does not bind the shortcut and does not search its text. A page that wants the key to run the command binds it itself.


Events

EventCancelableDetailDescription
x-command-palette-open-requestyes{}Fired before opening
x-command-palette-openno{}Fired after opening
x-command-palette-close-requestyes{}Fired before closing
x-command-palette-closeno{}Fired after closing
x-command-palette-select-requestyes{ item }Fired before item selection
x-command-palette-selectno{ item }Fired after item selected
x-command-palette-query-changeno{ query: string }Fired as the user types

Keyboard

KeyAction
ArrowDownMove to next enabled item (wraps)
ArrowUpMove to previous enabled item (wraps)
EnterSelect highlighted item
EscapeClose palette (if close-on-escape is true)

Accessibility

  • Renders a <div> with role="dialog" and aria-modal="true".
  • The input takes the focus when the palette opens, including a palette created open.
  • Input has role="combobox" with aria-expanded, aria-controls (linked to the listbox), and aria-activedescendant (tracks the highlighted item).
  • The list has role="listbox"; each item has role="option".
  • Disabled items have aria-disabled="true".
  • The name of an item is its label. Its shortcut describes it through aria-describedby.
  • Group headers are hidden from the accessibility tree via aria-hidden="true".

Parts

PartDescription
overlayThe scrim behind the panel.
panelThe dialog.
search-wrapThe row that holds the search icon, input and clear button.
search-iconThe search glyph.
inputThe search input.
clear-btnThe button that clears the query.
list-wrapThe scrolling area of the list.
listThe listbox.
group-headerThe heading of a group.
itemAn option.
item-labelThe label of an item.
item-shortcutThe x-kbd that shows the shortcut of an item.
emptyThe text shown when nothing matches.

Responsive

The panel max-width is capped at calc(100vw - 2rem) to prevent horizontal overflow on narrow viewports.


Examples

Basic usage

<x-command-palette id="palette"></x-command-palette>
<button onclick="document.getElementById('palette').setAttribute('open','')">
  Open (⌘K)
</button>
<script>
  const palette = document.getElementById('palette');
  palette.items = [
    { id: 'new',      label: 'New file',     group: 'File' },
    { id: 'open',     label: 'Open file…',   group: 'File' },
    { id: 'settings', label: 'Preferences',  group: 'App'  },
  ];
  palette.addEventListener('x-command-palette-select', e => {
    console.log('selected', e.detail.item);
    palette.removeAttribute('open');
  });
  palette.addEventListener('x-command-palette-close', () => {
    palette.removeAttribute('open');
  });
</script>

ClojureScript (hiccup renderer)

[:x-command-palette
 {:open (when (:palette-open state) "")
  :on-x-command-palette-close
  (fn [_] (swap! app dissoc :palette-open))
  :on-x-command-palette-select
  (fn [e]
    (handle-command (.. e -detail -item))
    (swap! app dissoc :palette-open))}]

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close