Skip to main content

CommandPalette

Search grouped commands and navigation targets from an inline surface.

Workspace Actions
Create New Issue⌘+N
Open Notifications⌘+I
Sync RoadmapPull the latest project updates
Navigation
Dashboard Overview
Projects Directory
Settings & Security
↑+↓Navigate
↵Select
EscClose
Props
Slots

Anatomy#

CommandPalette [component; slot=root]
├── inputWrapper [slot]
│   ├── inputLeading [slot]
│   ├── input [slot]
│   └── close [slot]
├── listbox [slot]
│   ├── group [slot]
│   │   ├── groupLabel [slot]
│   │   └── item [slot]
│   │       ├── itemLeading [slot]
│   │       ├── itemWrapper [slot]
│   │       │   ├── itemLabel [slot]
│   │       │   └── itemDescription [slot]
│   │       └── itemTrailing [slot]
│   └── empty [slot]
└── footer [slot]

Group labels and items flatten into sibling rows when virtualized. With descriptionPosition: 'trailing', the description renders inside itemLabel.

Usage#

Use CommandPalette for searchable commands or navigation targets on an inline surface. The application decides when to open it and registers any global shortcut. Wrap it in a Dialog or BaseDialog when the palette should occupy a focused overlay; the wrapper also owns Escape dismissal. Use NavigationMenu for persistent site destinations.

import { CommandPalette } from 'moraine'

export function Example() {
  return (
    <CommandPalette
      items={[{ type: 'group', label: 'Pages', items: [{ value: 'settings', label: 'Settings' }] }]}
    />
  )
}

Groups, filtering, and selection#

Pass items and groups from application state. The palette filters the supplied collection and calls the item’s onSelect, then the palette’s onSelect. Fetching commands, routing, and global shortcuts stay with the application. The default filterMethod is 'contains'; it matches the item’s label, value, description, and keywords ignoring case and accents. Pass 'startsWith', 'endsWith', or a predicate for custom matching, or false to skip filtering when you already filter the collection. Set alwaysShow on an item to keep it visible for any query.

<CommandPalette
  placeholder="Find a workspace section..."
  items={COMMAND_GROUPS}
  onSelect={(item) => setSection(item.value)}
/>

By default, selecting an enabled item also calls onClose. The palette never hides itself: use onClose to close the surrounding Dialog or BaseDialog. Set closable to show a close button that calls onClose. The search input takes focus on mount unless the palette sits inside an element with role="dialog"; set autofocus={false} to disable it. Control the query with searchValue and onSearchValueChange, or start from defaultSearchValue.

Custom item layout and states#

Use itemRender when a row needs extra fields such as owner or status; it replaces the default row content, so the items’ leadingRender and trailingRender no longer apply. Provide emptyRender when an empty query or a miss needs explanation, and footerRender for a footer such as keyboard hints. Set loading while results are still arriving: it swaps the leading icon for loadingIcon, and items stay selectable.

<CommandPalette
  items={groups}
  itemRender={(ctx) => <span>{ctx.item.label}</span>}
  emptyRender={() => <p>No commands found.</p>}
  loading={isLoading()}
/>

Sub-navigation is a short, deliberate branch of commands. Swap the items prop from application state rather than treating the palette as an application shell. Set closeOnSelect={false} while the branch stays open.

Keyboard interaction#

Key Description
↓ Highlights the next enabled command.
↑ Highlights the previous enabled command.
↵ Selects the highlighted command.

Focus stays in the search input while the highlight moves. Navigation wraps from the last command to the first. Escape and other dismissal keys belong to the enclosing Dialog or BaseDialog, not the palette.

Examples#

Jump to a workspace section#

Filter grouped destinations and store the selected section in page state.

import { CommandPalette, Icon } from 'moraine'
import type { CommandPaletteT } from 'moraine'
import { createSignal } from 'solid-js'

const COMMAND_GROUPS: CommandPaletteT.Group[] = [
  {
    type: 'group',
    label: 'Workspace sections',
    items: [
      {
        value: 'overview',
        label: 'Overview',
        description: 'Recent activity and open work',
        leadingRender: () => <Icon name="i-lucide:layout-dashboard" />,
      },
      {
        value: 'members',
        label: 'Members',
        description: 'People with workspace access',
        leadingRender: () => <Icon name="i-lucide:users" />,
      },
      {
        value: 'security',
        label: 'Security',
        description: 'Sign-in and access policies',
        leadingRender: () => <Icon name="i-lucide:shield-check" />,
      },
    ],
  },
]

export function GroupsFiltering() {
  const [section, setSection] = createSignal('overview')

  return (
    <div class="max-w-md w-full space-y-3">
      <CommandPalette
        autofocus={false}
        placeholder="Find a workspace section..."
        items={COMMAND_GROUPS}
        onSelect={(item) => setSection(item.value)}
      />
      <p class="text-sm">Current section: {section()}</p>
    </div>
  )
}

Scan projects by owner and status#

Render each command row with extra fields. Keep matching against the item model.

import { Badge, CommandPalette, Icon } from 'moraine'
import type { CommandPaletteT } from 'moraine'

interface TeamCommand extends CommandPaletteT.Item {
  owner: string
  status: 'ready' | 'blocked'
}

const GROUPS: CommandPaletteT.Group<TeamCommand>[] = [
  {
    type: 'group',
    label: 'Projects',
    items: [
      {
        value: 'moraine-docs',
        label: 'Moraine Docs',
        description: 'Update examples for the next release',
        owner: 'Design Systems',
        status: 'ready',
      },
      {
        value: 'billing-api',
        label: 'Billing API',
        description: 'Waiting on staging credentials',
        owner: 'Platform',
        status: 'blocked',
      },
    ],
  },
]

export function CustomItemRender() {
  return (
    <div class="max-w-full w-lg">
      <CommandPalette<TeamCommand>
        items={GROUPS}
        autofocus={false}
        itemRender={(ctx) => (
          <div class="flex flex-1 gap-3 min-w-0 items-center">
            <Icon name="i-lucide-folder-kanban text-muted-foreground group-data-[highlighted]:text-accent-foreground shrink-0" />
            <span class="flex flex-1 flex-col min-w-0">
              <span class="text-sm font-medium truncate">{ctx.item.label}</span>
              <span class="text-xs text-muted-foreground truncate group-data-[highlighted]:text-accent-foreground">
                {ctx.item.owner} · {ctx.item.description}
              </span>
            </span>
            <Badge variant={ctx.item.status === 'ready' ? 'soft' : 'outline'}>
              {ctx.item.status}
            </Badge>
          </div>
        )}
      />
    </div>
  )
}

Replace the default empty copy when the query matches nothing.

import { CommandPalette, Icon } from 'moraine'

export function CustomEmptyState() {
  return (
    <div class="max-w-full w-lg">
      <CommandPalette
        items={[]}
        autofocus={false}
        emptyRender={() => (
          <span class="flex flex-col gap-2 items-center">
            <Icon name="i-lucide-search-x" class="text-xl text-muted-foreground" />
            <span class="text-foreground font-medium">No commands found</span>
            <span class="text-xs">Try a different keyword or clear the search.</span>
          </span>
        )}
      />
    </div>
  )
}

Empty palette copy#

Show an empty collection with an explicit no-results message.

import { CommandPalette } from 'moraine'

export function CustomStates() {
  return (
    <div class="b-1 b-border rounded-xl max-w-md w-full shadow-lg overflow-hidden">
      <CommandPalette
        autofocus={false}
        placeholder="Search empty query..."
        items={[]}
        emptyRender={() => (
          <p class="text-xs text-muted-foreground p-6 text-center">
            No commands found matching your query.
          </p>
        )}
      />
    </div>
  )
}

Wait for command results#

Keep the palette visible while loading is true.

import { CommandPalette, Icon, KbdGroup } from 'moraine'
import type { CommandPaletteT } from 'moraine'

export function Loading() {
  const BASIC_GROUPS: CommandPaletteT.Group[] = [
    {
      type: 'group',
      label: 'Workspace',
      items: [
        {
          value: 'new-issue',
          label: 'New Issue',
          leadingRender: () => <Icon name="i-lucide-circle-plus" />,
          trailingRender: () => <KbdGroup items={['⌘', 'N']} />,
        },
        {
          value: 'open-inbox',
          label: 'Open Inbox',
          leadingRender: () => <Icon name="i-lucide-inbox" />,
          trailingRender: () => <KbdGroup items={['⌘', 'I']} />,
        },
        {
          value: 'sync-roadmap',
          label: 'Sync Roadmap',
          leadingRender: () => <Icon name="i-lucide-refresh-cw" />,
          description: 'Pull the latest planning updates',
        },
      ],
    },
  ]

  return (
    <div class="max-w-full w-lg">
      <CommandPalette items={BASIC_GROUPS} autofocus={false} loading />
    </div>
  )
}

Search ten thousand commands#

Pass a virtualizer from createListVirtualizer to render only the rows near the viewport. Its entries are CommandPaletteT.VirtualEntry rows: group labels and commands flattened into one list. The listbox keeps its default bounded height, so the virtual range stays stable while scrolling.

import { CommandPalette } from 'moraine'
import type { CommandPaletteT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'

const GROUPS: CommandPaletteT.Group[] = ['Files', 'Symbols'].map((label) => ({
  type: 'group',
  label,
  items: Array.from({ length: 5_000 }, (_, index) => ({
    value: `${label.toLowerCase()}-${index}`,
    label: `${label.slice(0, -1)} ${index + 1}`,
  })),
}))

export function Virtualization() {
  const virtualizer = createListVirtualizer<CommandPaletteT.VirtualEntry>({
    estimateSize: (entry) => (entry.type === 'label' ? 24 : 32),
    getItemKey: (entry) => entry.key,
    overscan: 8,
  })

  return (
    <div class="max-w-md w-full">
      <CommandPalette
        autofocus={false}
        placeholder="Search 10,000 commands..."
        items={GROUPS}
        virtualizer={virtualizer}
        classes={{ listbox: 'h-72' }}
      />
    </div>
  )
}

Drill into Create or Share#

Swap items to open a short command branch. Keep selection from closing the palette until the user finishes or goes back.

import { Button, CommandPalette, Icon } from 'moraine'
import type { CommandPaletteT } from 'moraine'
import { createMemo, createSignal } from 'solid-js'

export function SubNavigation() {
  const ROOT_GROUPS: CommandPaletteT.Group[] = [
    {
      type: 'group',
      label: 'Commands',
      items: [
        {
          value: 'create',
          label: 'Create',
          leadingRender: () => <Icon name="i-lucide-plus-circle" />,
          description: 'Create new resources',
        },
        {
          value: 'share',
          label: 'Share',
          leadingRender: () => <Icon name="i-lucide-share-2" />,
          description: 'Share with others',
        },
        {
          value: 'delete',
          label: 'Delete',
          leadingRender: () => <Icon name="i-lucide-trash-2" />,
        },
      ],
    },
  ]
  const CREATE_GROUPS: CommandPaletteT.Group[] = [
    {
      type: 'group',
      label: 'Create',
      items: [
        {
          value: 'create-new-file',
          label: 'New File',
          leadingRender: () => <Icon name="i-lucide-file-plus" />,
        },
        {
          value: 'create-new-folder',
          label: 'New Folder',
          leadingRender: () => <Icon name="i-lucide-folder-plus" />,
        },
        {
          value: 'create-new-project',
          label: 'New Project',
          leadingRender: () => <Icon name="i-lucide-git-branch" />,
        },
      ],
    },
  ]
  const SHARE_GROUPS: CommandPaletteT.Group[] = [
    {
      type: 'group',
      label: 'Share',
      items: [
        {
          value: 'share-copy-link',
          label: 'Copy Link',
          leadingRender: () => <Icon name="i-lucide-link" />,
          trailingRender: () => <span class="text-xs text-muted-foreground">⌘L</span>,
        },
        {
          value: 'share-send-email',
          label: 'Send via Email',
          leadingRender: () => <Icon name="i-lucide-mail" />,
        },
      ],
    },
  ]
  const [view, setView] = createSignal<'root' | 'create' | 'share'>('root')

  const groups = createMemo(() => {
    switch (view()) {
      case 'create':
        return CREATE_GROUPS
      case 'share':
        return SHARE_GROUPS
      case 'root':
      default:
        return ROOT_GROUPS
    }
  })

  const onSelect = (item: CommandPaletteT.Item) => {
    if (item.value === 'create') {
      setView('create')
    } else if (item.value === 'share') {
      setView('share')
    }
  }

  return (
    <div class="flex flex-col gap-3 max-w-full w-lg">
      <div class="flex gap-3 items-center justify-between">
        <p class="text-sm text-muted-foreground">
          Drive multi-step navigation outside the component by swapping the `items` prop.
        </p>
        <Button
          size="sm"
          variant="outline"
          disabled={view() === 'root'}
          onClick={() => setView('root')}
        >
          Back
        </Button>
      </div>
      <CommandPalette
        items={groups()}
        autofocus={false}
        closeOnSelect={false}
        onSelect={onSelect}
      />
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-disabled
Slot: command-palette-item
Description: Present when the component, slot, or item is disabled.
data-highlighted
Slot: command-palette-itemcommand-palette-item-leadingcommand-palette-item-descriptioncommand-palette-item-trailing
Description: Present when the item is highlighted by pointer or keyboard navigation.
data-loading
Slot: command-palette-input-leading
Description: Present when the component or async operation is loading.

Props#

Renders a <div> element by default.

Prop