Skip to content
Pelatform UI

Actions

Command

A searchable list of links and actions, inline or in a dialog, that filters as you type.

Class nameTypeDescription
commandplf:commandComponentThe searchable list of actions
command-dialogplf:command-dialogComponentA Modal dialog that holds a command palette
command-searchplf:command-searchPartThe search row
command-inputplf:command-inputPartThe search field
command-iconplf:command-iconPartAn action's SVG icon, or your own in place of the search row's drawn one; an icon class there doesn't need it
command-clearplf:command-clearPartThe button that clears the search, which draws an x while empty
command-listplf:command-listPartThe scrolling list of groups
command-groupplf:command-groupPartA group of actions
command-headingplf:command-headingPartA group's heading
command-itemsplf:command-itemsPartA group's list of rows
command-rowplf:command-rowPartThe list item around an action
command-itemplf:command-itemPartA link or button action
command-labelplf:command-labelPartAn action's label
command-descriptionplf:command-descriptionPartSecondary text after the label
command-shortcutplf:command-shortcutPartA key hint at the end of an action
command-separatorplf:command-separatorPartA divider between groups
command-emptyplf:command-emptyPartThe message when nothing matches
command-footerplf:command-footerPartA footer of key hints
command-keyplf:command-keyPartA key in the footer

Default

Pages

Actions

Links navigate as usual; the script runs button actions from plf:command:select by their key.

Descriptions

A description is not searched, so repeat its words in data-plf-keywords.

Pages

Sections

Dialog

In the Modal, give the field autofocus and keep a close button. An action closes the dialog, and aria-keyshortcuts on the open button opens it from the keyboard outside text fields.

Pages

Actions

JavaScript

Command needs JavaScript to search. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

Hooks

Attribute Purpose
data-plf-command Marks the container
data-plf-command-controls Optional: the search row, which is the parent of the Command’s one <input>; authored hidden
data-plf-command-clear Optional: the clear button, which is the search row’s one <button>
data-plf-command-list Optional: the list, which is the child that holds the actions
data-plf-command-group Optional: a group; groups are the list’s children other than <hr>, each named by its heading
data-plf-command-item The link or button; its value is a key, unique in the Command
data-plf-command-label The action’s label; exactly one per action
data-plf-keywords Optional: more words to search
data-plf-command-empty The command-empty message, authored hidden
data-plf-command-help Optional: a command-footer with command-key labels, authored hidden
data-plf-results-label, data-plf-available-label On the container, the status words; Results and Available by default

The script shows the search row and the footer, adds a polite live region that announces the counts, hides rows, groups and separators without a match, and marks the active action with data-plf-command-active.

Methods

Method Behavior
PLF.Command.getOrCreateInstance(element, options) Returns the instance, creating it for valid markup. The options resultsLabel and availableLabel set the status words
PLF.Command.getInstance(element) Returns the instance or null
instance.setQuery(value) Searches for value. Returns false when unchanged or canceled
instance.focusItem(key) Focuses that action. Returns false when it is unavailable or already focused
instance.activate(key) Runs that action as a click does. Returns false when it is unavailable or canceled
instance.getState() Returns { query, activeKey, totalCount, matchingCount, availableCount }
instance.destroy() Removes listeners and restores what the script changed

Events

Event When
plf:command:before-change Before the search changes; cancelable
plf:command:change After the search changes
plf:command:before-select Before an action runs; cancelable
plf:command:select As an action runs, before its click or navigation; in a Modal it then closes the dialog, unless a handler calls preventDefault()

Each event’s detail:

Property Events Value
instance All The Command instance
reason All api, trigger or keyboard
trigger All The field, the clear button or the chosen action, or null from setQuery()
previousState before-change, change The state before the change, shaped like getState()
state before-change, change The state after the change
item before-select, select The action’s link or button
key before-select, select The action’s key
query before-select, select The search text

Keyboard

Key Action
Down Arrow, Up Arrow From the field, focus the first or last action; on an action, move to the next or previous one
Home, End On an action, focus the first or last one
Enter Runs the active action
Space On a button action, runs it
Escape On an action, returns to the field; in the field, clears the search. In a Modal, closes the dialog
Tab, Shift+Tab Move between the field, the clear button and the active action

React

Command from @pelatform/react renders this search with its status: typing filters the items by their label and keywords, and the keys move between the field and the items, as the script’s do. Each part is a component of its own.

Prop Values Default
resultsLabel, availableLabel The status words before the numbers of matches and of items that can run Results, Available
open On CommandDialog, true while the palette is open Required
onOpenChange On CommandDialog, (open, reason), called when it asks to close: trigger (a chosen item or a ModalClose), keyboard (Escape) or backdrop; keep open to stay open None
closeOnBackdrop On CommandDialog, true closes on a click outside the palette false
heading On CommandGroup, the group’s heading, which names it None
level On CommandGroup, the heading’s level, 2 to 6 3
value On CommandItem, its key, unique in the Command Required
keywords On CommandItem, more words to search, such as its description’s None
onSelect On CommandItem, (event), called when the item is chosen by a click or Enter; in a CommandDialog, the dialog then asks to close with trigger unless it calls event.preventDefault() None
aria-label On CommandClear, the button’s name Clear search

The parts:

Part Element
CommandDialog A Modal with command-dialog around the Command, which takes Modal’s parts, such as ModalClose
CommandSearch A div with command-search
CommandInput An input with command-input, whose value the Command keeps; its onChange hears the search
CommandClear A button with command-clear, shown while there is a search
CommandList A div with command-list, a child of Command
CommandGroup A section with command-group, its heading and a command-items list, a child of CommandList
CommandItem A button with command-item in a command-row, or a link with href, a child of CommandGroup
CommandLabel A span with command-label, the item’s searched text
CommandDescription A span with command-description
CommandShortcut A kbd with command-shortcut, hidden from assistive technologies
CommandSeparator An hr with command-separator
CommandEmpty A p with command-empty, shown while nothing matches
CommandFooter A div with command-footer
CommandKey A kbd with command-key

The other props are the element’s own, className and ref included. CommandDialog doesn’t bind aria-keyshortcuts, so the Dialog example opens it on Control+K and Command+K itself.

CSS variables

Variable Default
--plf-command-bg, --plf-command-color Elevated surface and text
--plf-command-border --plf-color-border-subtle
--plf-command-divider-color --plf-color-border-subtle
--plf-command-radius Extra large radius (12px)
--plf-command-icon-color, --plf-command-heading-color Muted text
--plf-command-item-active-bg Muted surface
--plf-command-item-height 40px, a minimum
--plf-command-list-max-height 20rem
--plf-command-dialog-width 32rem

Built with Pelatform UIv0.1.0

Components

Getting started

Foundations

Components

Actions

Data display

Navigation

Feedback

Data input

Layout

Advanced

Integrations

Blocks

Application

Authentication

Icons