Skip to content

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
basic-usage.svelte
<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
recent-commands.svelte
<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
subgroups.svelte
<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

NameTypeDefaultDescription
commandsrequiredCommandBarCommand[]—Commands shown, filtered, and grouped by category.
configrequiredCommandBarConfig—onExecute runs after a command is chosen; optional onTrackRecent persists usage for recentCommandIds.
subgroupsCommandBarSubgroup[][]Subgroup rows in the root list; each opens a nested list (items) or a custom snippet (content).
recentCommandIdsstring[][]Ordered ids surfaced under the Recent heading when the query is empty (commands only).
placeholderstring'Search commands...'Placeholder on the filter input.

CommandBarConfig

From phoundry-ui@0.4.21

NameTypeDefaultDescription
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

NameTypeDefaultDescription
idrequiredstring—Unique identifier.
labelrequiredstring—Display label.
descriptionstring | undefined—Optional description shown below the label.
iconstring | undefined—Iconify icon string.
categorystring | undefined—Category for grouping.
shortcutstring | undefined—Keyboard shortcut hint.

CommandBarSubgroup

From phoundry-ui@0.4.21

NameTypeDefaultDescription
idrequiredstring—Stable key for the subgroup row.
labelrequiredstring—Root list label.
descriptionstring | undefined—Optional muted line in the root list.
iconstring | undefined—Iconify icon string.
categorystring | undefined—Category for grouping in the root list.
itemsCommandBarCommand[] | undefined—Commands shown inside the subgroup (exclusive with content).
contentSnippet<[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

NameTypeDefaultDescription
queryrequiredstring—Current search string (same as the palette input).
subgroupIdrequiredstring—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 CommandBar registers config on the shared state - avoid mounting multiple instances with different configs at once.
  • Pass recentCommandIds plus config.onTrackRecent to 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.