Navigation

Command Palette

A spotlight-style navigation overlay opened with Cmd+K or Ctrl+K from anywhere.

<script>
  import { CommandPalette } from "@codeatlasdev/ui";
  import { goto } from "$app/navigation";
  let open = $state(false);
</script>

<CommandPalette modules={NAV} onNavigate={(path) => goto(path)} bind:open />

The palette searches the same NavModule[] you pass to AppShellLayout, matching on item label and module label. It registers Cmd+K and Ctrl+K itself on window, so mount it once near the root. It opens as a modal dialog layer. Arrow keys move the selection, Enter navigates and Escape closes.

#156

Open the palette

Click the button or press Cmd+K / Ctrl+K while this page is focused. Picking an item shows its path instead of navigating.

⌘K

Reference #156 · Pick in the gallery

Code

<script lang="ts">
  import { CommandPalette, Button, Kbd, type NavModule } from '@codeatlasdev/ui';
  import { Keyboard, Home, Users, Settings, BarChart3, FileText, CreditCard } from '@lucide/svelte';

  let open = $state(false);
  let picked = $state('');

  const modules: NavModule[] = [
    {
      id: 'app',
      label: 'App',
      icon: Home,
      basePath: '/app',
      items: [
        { id: 'dashboard', label: 'Dashboard', icon: Home, path: '/app/dashboard' },
        { id: 'users', label: 'Users', icon: Users, path: '/app/users' },
        { id: 'reports', label: 'Reports', icon: BarChart3, path: '/app/reports' },
      ],
    },
    {
      id: 'account',
      label: 'Account',
      icon: Settings,
      basePath: '/account',
      items: [
        { id: 'settings', label: 'Settings', icon: Settings, path: '/account/settings' },
        { id: 'billing', label: 'Billing', icon: CreditCard, path: '/account/billing' },
        { id: 'docs', label: 'Documentation', icon: FileText, path: '/account/docs' },
      ],
    },
  ];
</script>

<CommandPalette {modules} onNavigate={(path) => (picked = path)} bind:open />

<Button variant="filled" onclick={() => (open = true)}>
  {#snippet leading()}<Keyboard size={16} />{/snippet}
  Open command palette
</Button>
<Kbd>⌘K</Kbd>
{#if picked}<span class="picked" aria-live="polite">Selected: <code>{picked}</code></span>{/if}

<style>
  .picked { font-size: var(--ca-font-size-body2); color: var(--ca-text-secondary); }
  .picked code { font-family: var(--ca-font-mono); color: var(--ca-brand-text); }
</style>

#155

Keyboard

Type to filter across every module. Queries shorter than minQueryLength keep the full grouped list.

TypeFilter by label or module name
↑ ↓Move through the results
↵Navigate to the selected item
ESCClose the palette

Reference #155 · Pick in the gallery

Code

<script lang="ts">
  import { Kbd } from '@codeatlasdev/ui';

  const keys = [
    { key: 'Type', desc: 'Filter by label or module name' },
    { key: '↑ ↓', desc: 'Move through the results' },
    { key: '↵', desc: 'Navigate to the selected item' },
    { key: 'ESC', desc: 'Close the palette' },
  ];
</script>

<ul class="list">
  {#each keys as k}
    <li><Kbd>{k.key}</Kbd><span>{k.desc}</span></li>
  {/each}
</ul>

<style>
  .list { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; width: 100%; max-width: 480px; }
  li { display: flex; align-items: center; gap: 16px; padding: 8px 4px; }
  span { font-size: var(--ca-font-size-body2); color: var(--ca-text-secondary); }
</style>

Async results

Pass search to add server-side results under the local matches. It runs once the user stops typing for searchDebounce ms, receives the trimmed query and an AbortSignal, and returns CommandResult[] ({ id, label, group?, path }). A newer query, closing the palette or unmounting aborts the pending call, so forward the signal to fetch and never apply a stale answer. While it runs the list is aria-busy and a “Searching…” row shows; a rejection shows “Search failed” without hiding local matches; the empty state appears only after the search settles. Progress, the result count and failures are announced through announce().

Results with a group are listed under that heading. Activating one calls onSelect(result) when provided, otherwise onNavigate(result.path).

#422

Async results

A simulated 600 ms server search, grouped, with loading and abort on every new query.

Reference #422 · Pick in the gallery

Code

<script lang="ts">
  import { CommandPalette, Button, type CommandResult, type NavModule } from '@codeatlasdev/ui';
  import { Search, Home, Settings } from '@lucide/svelte';

  let open = $state(false);
  let picked = $state('');

  const modules: NavModule[] = [
    {
      id: 'app',
      label: 'App',
      icon: Home,
      basePath: '/app',
      items: [
        { id: 'dashboard', label: 'Dashboard', icon: Home, path: '/app/dashboard' },
        { id: 'settings', label: 'Settings', icon: Settings, path: '/app/settings' },
      ],
    },
  ];

  const records: CommandResult[] = [
    { id: 'i1', label: 'Invoice 1042', group: 'Invoices', path: '/invoices/1042' },
    { id: 'i2', label: 'Invoice 1043', group: 'Invoices', path: '/invoices/1043' },
    { id: 'c1', label: 'Acme Corp', group: 'Customers', path: '/customers/acme' },
    { id: 'c2', label: 'Globex', group: 'Customers', path: '/customers/globex' },
  ];

  /** Stand-in for a server call: honours the AbortSignal like fetch(url, { signal }) does. */
  function search(query: string, signal: AbortSignal): Promise<CommandResult[]> {
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        resolve(records.filter((r) => r.label.toLowerCase().includes(query.toLowerCase())));
      }, 600);
      signal.addEventListener('abort', () => {
        clearTimeout(timer);
        reject(new DOMException('Aborted', 'AbortError'));
      });
    });
  }
</script>

<!-- The page's first palette owns Mod+K; this one opens from its button only. -->
<CommandPalette {modules} {search} shortcut={false} onNavigate={(path) => (picked = path)} bind:open />

<Button variant="filled" onclick={() => (open = true)}>
  {#snippet leading()}<Search size={16} />{/snippet}
  Search records
</Button>
{#if picked}<span class="picked">Selected: <code>{picked}</code></span>{/if}

<style>
  .picked { font-size: var(--ca-font-size-body2); color: var(--ca-text-secondary); }
  .picked code { font-family: var(--ca-font-mono); color: var(--ca-brand-text); }
</style>

Props

Prop	Type	Default	Description
`modules`	`NavModule[]`	–	Navigation tree to search. Same format as AppShellLayout.
`onNavigate`	`(path: string) => void`	–	Called with the selected item's path. Use goto() in SvelteKit or location in static sites.
`open`	`boolean`	`false`	Bindable. Controls visibility. Cmd+K and Ctrl+K also toggle it.
`minQueryLength`	`number`	`1`	Trimmed characters needed before the list is filtered. Shorter queries keep the full grouped list.
`search`	`(query: string, signal: AbortSignal) => Promise<CommandResult[]>`	–	Async/server-side search, debounced and aborted on every new query. Throw or reject to show the failed state.
`searchDebounce`	`number`	`200`	Milliseconds without typing before `search` is called.
`shortcut`	`boolean`	`true`	Opens and closes on Mod+K (Cmd+K / Ctrl+K) anywhere in the window. Turn it off for every palette but one when a page has several, or when the app binds its own shortcut.
`onSelect`	`(result: CommandResult) => void`	–	Called with the whole result when a server result is activated. Replaces `onNavigate` for those results.
`query`	`string`	`''`	Bindable current input text.