Skip to content
WebJs
Menu

Command menu for search and quick actions.

import { html } from '@webjsdev/core';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

export default function CommandDemo() {
  return html`
    <ui-command label="Command menu" class="max-w-sm rounded-lg border">
      <ui-command-input placeholder="Type a command or search..."></ui-command-input>
      <ui-command-list>
        <ui-command-empty>No results found.</ui-command-empty>
        <ui-command-group heading="Suggestions">
          <ui-command-item>
            ${CalendarIcon()}
            <span>Calendar</span>
          </ui-command-item>
          <ui-command-item>
            ${SmileIcon()}
            <span>Search Emoji</span>
          </ui-command-item>
          <ui-command-item disabled>
            ${CalculatorIcon()}
            <span>Calculator</span>
          </ui-command-item>
        </ui-command-group>
        <ui-command-separator></ui-command-separator>
        <ui-command-group heading="Settings">
          <ui-command-item>
            ${UserIcon()}
            <span>Profile</span>
            <ui-command-shortcut>⌘P</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${CreditCardIcon()}
            <span>Billing</span>
            <ui-command-shortcut>⌘B</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${SettingsIcon()}
            <span>Settings</span>
            <ui-command-shortcut>⌘S</ui-command-shortcut>
          </ui-command-item>
        </ui-command-group>
      </ui-command-list>
    </ui-command>
  `;
}
View Code

About

The <ui-command> element follows the model of cmdk by Dip, built on the platform with no dependency: typing in the input filters and ranks the items, the arrow keys move the selection while focus stays in the input, and Enter runs the selected item.

Installation

pnpm dlx @webjsdev/ui add command

Usage

import '#components/ui/command.ts';
<ui-command label="Command menu" class="max-w-sm rounded-lg border">
  <ui-command-input placeholder="Type a command or search..."></ui-command-input>
  <ui-command-list>
    <ui-command-empty>No results found.</ui-command-empty>
    <ui-command-group heading="Suggestions">
      <ui-command-item>Calendar</ui-command-item>
      <ui-command-item>Search Emoji</ui-command-item>
      <ui-command-item>Calculator</ui-command-item>
    </ui-command-group>
    <ui-command-separator></ui-command-separator>
    <ui-command-group heading="Settings">
      <ui-command-item>Profile</ui-command-item>
      <ui-command-item>Billing</ui-command-item>
      <ui-command-item>Settings</ui-command-item>
    </ui-command-group>
  </ui-command-list>
</ui-command>

Composition

Use the following composition to build a command:

ui-command
├── ui-command-input
└── ui-command-list
    ├── ui-command-empty
    ├── ui-command-group
    │   ├── ui-command-item
    │   └── ui-command-item
    ├── ui-command-separator
    └── ui-command-group
        ├── ui-command-item
        └── ui-command-item

Basic

A simple command menu in a dialog. It is a Dialog whose content takes commandDialogClass() and holds the command, with its title and description for screen readers only.

Command Palette

Search for a command to run...

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';

// shadcn's CommandDialog is a Dialog around a Command, so the button opens a
// <ui-dialog> whose content holds the command, with the title and the
// description for screen readers only.
export default function CommandBasic() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Suggestions">
                <ui-command-item>Calendar</ui-command-item>
                <ui-command-item>Search Emoji</ui-command-item>
                <ui-command-item>Calculator</ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
View Code

Shortcuts

Command Palette

Search for a command to run...

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import { CreditCardIcon, SettingsIcon, UserIcon } from '#lib/ui/lucide.ts';

export default function CommandWithShortcuts() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Settings">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
View Code

Groups

A command menu with groups, icons and separators.

Command Palette

Search for a command to run...

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

export default function CommandWithGroups() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Suggestions">
                <ui-command-item>
                  ${CalendarIcon()}
                  <span>Calendar</span>
                </ui-command-item>
                <ui-command-item>
                  ${SmileIcon()}
                  <span>Search Emoji</span>
                </ui-command-item>
                <ui-command-item>
                  ${CalculatorIcon()}
                  <span>Calculator</span>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Settings">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
View Code

Scrollable

Scrollable command menu with multiple items.

Command Palette

Search for a command to run...

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import {
  BellIcon, CalculatorIcon, CalendarIcon, ClipboardPasteIcon, CodeIcon, CopyIcon,
  CreditCardIcon, FileTextIcon, FolderIcon, FolderPlusIcon, HelpCircleIcon, HomeIcon,
  ImageIcon, InboxIcon, LayoutGridIcon, ListIcon, PlusIcon, ScissorsIcon, SettingsIcon,
  TrashIcon, UserIcon, ZoomInIcon, ZoomOutIcon,
} from '#lib/ui/lucide.ts';

export default function CommandManyItems() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Navigation">
                <ui-command-item>
                  ${HomeIcon()}
                  <span>Home</span>
                  <ui-command-shortcut>⌘H</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${InboxIcon()}
                  <span>Inbox</span>
                  <ui-command-shortcut>⌘I</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FileTextIcon()}
                  <span>Documents</span>
                  <ui-command-shortcut>⌘D</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FolderIcon()}
                  <span>Folders</span>
                  <ui-command-shortcut>⌘F</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Actions">
                <ui-command-item>
                  ${PlusIcon()}
                  <span>New File</span>
                  <ui-command-shortcut>⌘N</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FolderPlusIcon()}
                  <span>New Folder</span>
                  <ui-command-shortcut>⇧⌘N</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CopyIcon()}
                  <span>Copy</span>
                  <ui-command-shortcut>⌘C</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ScissorsIcon()}
                  <span>Cut</span>
                  <ui-command-shortcut>⌘X</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ClipboardPasteIcon()}
                  <span>Paste</span>
                  <ui-command-shortcut>⌘V</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${TrashIcon()}
                  <span>Delete</span>
                  <ui-command-shortcut>⌫</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="View">
                <ui-command-item>
                  ${LayoutGridIcon()}
                  <span>Grid View</span>
                </ui-command-item>
                <ui-command-item>
                  ${ListIcon()}
                  <span>List View</span>
                </ui-command-item>
                <ui-command-item>
                  ${ZoomInIcon()}
                  <span>Zoom In</span>
                  <ui-command-shortcut>⌘+</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ZoomOutIcon()}
                  <span>Zoom Out</span>
                  <ui-command-shortcut>⌘-</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Account">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${BellIcon()}
                  <span>Notifications</span>
                </ui-command-item>
                <ui-command-item>
                  ${HelpCircleIcon()}
                  <span>Help &amp; Support</span>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Tools">
                <ui-command-item>
                  ${CalculatorIcon()}
                  <span>Calculator</span>
                </ui-command-item>
                <ui-command-item>
                  ${CalendarIcon()}
                  <span>Calendar</span>
                </ui-command-item>
                <ui-command-item>
                  ${ImageIcon()}
                  <span>Image Editor</span>
                </ui-command-item>
                <ui-command-item>
                  ${CodeIcon()}
                  <span>Code Editor</span>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      placeholder: 'Type a command or search...',
      empty: 'No results found.',
      suggestions: 'Suggestions',
      calendar: 'Calendar',
      searchEmoji: 'Search Emoji',
      calculator: 'Calculator',
      settings: 'Settings',
      profile: 'Profile',
      billing: 'Billing',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      placeholder: 'اكتب أمرًا أو ابحث...',
      empty: 'لم يتم العثور على نتائج.',
      suggestions: 'اقتراحات',
      calendar: 'التقويم',
      searchEmoji: 'البحث عن الرموز التعبيرية',
      calculator: 'الآلة الحاسبة',
      settings: 'الإعدادات',
      profile: 'الملف الشخصي',
      billing: 'الفوترة',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      placeholder: 'הקלד פקודה או חפש...',
      empty: 'לא נמצאו תוצאות.',
      suggestions: 'הצעות',
      calendar: 'לוח שנה',
      searchEmoji: "חפש אמוג'י",
      calculator: 'מחשבון',
      settings: 'הגדרות',
      profile: 'פרופיל',
      billing: 'חיוב',
    },
  },
};

// The provider is the dir attribute: every part styles itself with logical
// properties, so dir="rtl" on the command flips the whole menu.
export default function CommandRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <ui-command label=${t.suggestions} dir=${dir} lang=${lang} class="max-w-sm rounded-lg border">
      <ui-command-input placeholder=${t.placeholder}></ui-command-input>
      <ui-command-list>
        <ui-command-empty>${t.empty}</ui-command-empty>
        <ui-command-group heading=${t.suggestions}>
          <ui-command-item>
            ${CalendarIcon()}
            <span>${t.calendar}</span>
          </ui-command-item>
          <ui-command-item>
            ${SmileIcon()}
            <span>${t.searchEmoji}</span>
          </ui-command-item>
          <ui-command-item disabled>
            ${CalculatorIcon()}
            <span>${t.calculator}</span>
          </ui-command-item>
        </ui-command-group>
        <ui-command-separator></ui-command-separator>
        <ui-command-group heading=${t.settings}>
          <ui-command-item>
            ${UserIcon()}
            <span>${t.profile}</span>
            <ui-command-shortcut>⌘P</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${CreditCardIcon()}
            <span>${t.billing}</span>
            <ui-command-shortcut>⌘B</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${SettingsIcon()}
            <span>${t.settings}</span>
            <ui-command-shortcut>⌘S</ui-command-shortcut>
          </ui-command-item>
        </ui-command-group>
      </ui-command-list>
    </ui-command>
  `;
}
View Code

API Reference

The command follows cmdk's model, built on the platform: typing in the input filters and ranks the items, the arrow keys move a selection while focus stays in the input, and Enter runs the selected item.

Elements

ElementDescription
<ui-command>The root. Holds the search and the selection.
<ui-command-input>The search field, a role="combobox" input that keeps focus and points at the selected item through aria-activedescendant.
<ui-command-list>The role="listbox" holding the groups and items.
<ui-command-empty>Shown when nothing matches the search.
<ui-command-group>A group of items under a heading, hidden when none of its items match.
<ui-command-item>One action, a role="option" carrying data-selected="true" while selected.
<ui-command-shortcut>A keyboard shortcut hint at the end of an item.
<ui-command-separator>A divider between groups, hidden while a search runs.
<ui-command-dialog>A <ui-command> in a native modal dialog, with a screen-reader title and description. Open it with show(), or compose a Dialog as the demos above do.

ui-command

AttributeTypeDefault
labelstring, the name a screen reader reads-
should-filter"true" | "false""true"
loopbooleanfalse
valuestring, the selected item's value, reflected-

should-filter="false" leaves filtering to you, for a list a server action returns.

ui-command-input

AttributeTypeDefault
placeholderstring-

ui-command-group

AttributeTypeDefault
headingstring-

ui-command-item

AttributeTypeDefault
valuestringThe item's text
keywordsstring, space separated, matched by the search-
disabledbooleanfalse

An item that holds a link follows it when it runs.

ui-command-dialog

AttributeTypeDefault
openboolean, reflectedfalse
titlestring"Command Palette"
descriptionstring"Search for a command to run..."
show-close-button"true" | "false""false"

Events

EventDetailFires
ui-select{ value: string }On the item, when it runs (Enter or a click). Cancelable: cancel it to stop a link inside the item from being followed.
ui-value-change{ value: string }On <ui-command>, as the selection moves.
ui-search-change{ search: string }On <ui-command>, as the search text changes.

Keyboard

ArrowDown and ArrowUp (and Ctrl+N / Ctrl+P, Ctrl+J / Ctrl+K) move the selection, loop wraps it, Home and End jump to the ends, and Enter runs the selected item. Pointing at an item selects it.