Command Bar
Searchable command palette with categories, icons, shortcuts, recent commands, and optional subgroups (nested lists or custom snippet panels).
import { CommandBar, getCommandBarState } from "phoundry-ui";Basic Usage
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { getCommandBarState } from "phoundry-ui";
const barState = getCommandBarState();
let lastExecuted = $state("");</script>
<div class="flex items-center gap-3"> <Button onclick={() => barState.open()}>Open Command Bar</Button> {#if lastExecuted} <span class="text-xs text-txt-secondary">Executed: {lastExecuted}</span> {/if}</div>Recent commands
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { getCommandBarState } from "phoundry-ui";
const barState = getCommandBarState();
let recentIds = $state<string[]>(["save", "search"]);</script>
<p class="mb-2 text-xs text-txt-secondary"> Open the palette and run a command - executed ids bubble to the Recent group via <code>onTrackRecent</code>.</p><div class="flex items-center gap-2"> <Button onclick={() => barState.open()}>Open palette</Button> <span class="text-[11px] text-txt-tertiary" >recent: {recentIds.join(", ")}</span ></div>Subgroups
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { getCommandBarState } from "phoundry-ui";
const barState = getCommandBarState();</script>
<p class="mb-2 text-xs text-txt-secondary"> Subgroups appear in the root list with a chevron. Choose one to drill in; <strong >Esc</strong > or the back control returns to the root. Use a <code>content</code> snippet for a fully custom panel instead of command rows.</p><div class="flex items-center gap-2"> <Button onclick={() => barState.open()}>Open palette (with subgroups)</Button></div>CommandBar Props
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
commandsrequired | CommandBarCommand[] | — | Commands shown, filtered, and grouped by category. |
configrequired | CommandBarConfig | — | onExecute runs after a command is chosen; optional onTrackRecent persists usage for recentCommandIds. |
subgroups | CommandBarSubgroup[] | [] | Subgroup rows in the root list; each opens a nested list (items) or a custom snippet (content). |
recentCommandIds | string[] | [] | Ordered ids surfaced under the Recent heading when the query is empty (commands only). |
placeholder | string | 'Search commands...' | Placeholder on the filter input. |
CommandBarConfig
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
onExecuterequired | (command: CommandBarCommand) => void | Promise<void> | — | Runs after the user confirms a command. |
onTrackRecent | ((commandId: string) => void | Promise<void>) | undefined | — | Optional hook to persist recency - wire into storage, then feed ids back via recentCommandIds. |
CommandBarCommand
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | — | Unique identifier. |
labelrequired | string | — | Display label. |
description | string | undefined | — | Optional description shown below the label. |
icon | string | undefined | — | Iconify icon string. |
category | string | undefined | — | Category for grouping. |
shortcut | string | undefined | — | Keyboard shortcut hint. |
CommandBarSubgroup
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | — | Stable key for the subgroup row. |
labelrequired | string | — | Root list label. |
description | string | undefined | — | Optional muted line in the root list. |
icon | string | undefined | — | Iconify icon string. |
category | string | undefined | — | Category for grouping in the root list. |
items | CommandBarCommand[] | undefined | — | Commands shown inside the subgroup (exclusive with content). |
content | Snippet<[CommandBarSubgroupContentContext]> | undefined | — | Custom panel inside the subgroup (exclusive with items); use {@render content(ctx)} pattern from a snippet prop. |
CommandBarSubgroupContentContext
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
queryrequired | string | — | Current search string (same as the palette input). |
subgroupIdrequired | string | — | Opened subgroup id. |
backrequired | () => void | — | Return to the root list without closing. |
closerequired | () => void | — | Close the command bar. |
Usage tips
- Call
getCommandBarState()to get the singleton - it works from any component. - The mounted
CommandBarregistersconfigon the shared state - avoid mounting multiple instances with different configs at once. - Pass
recentCommandIdsplusconfig.onTrackRecentto populate the Recent section (top-level commands only). - Root list: ↑↓ navigate, ↵ runs a command or opens a subgroup.
- Inside a subgroup with commands: same navigation; ↵ executes the selected command.
- Custom subgroup: arrow navigation is disabled; esc or the back button returns to the root list.
- Esc from the root list closes the palette; from a subgroup it goes back first.
CSS styling
.ph-command-bar is the stable identification hook for CommandBar. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Panel, search, results, and decorative edge styles are local to the overlay. Search and command execution behavior are unchanged.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.