Skip to content
Nana UI

Navigation

Command

A command palette: a search field over grouped pages and actions, opened from anywhere with ⌘K or Control+K.

View .md Download

The command palette lets people jump to a page or run an action by typing its name. It opens in a dialog from anywhere on the page with ⌘K on Apple devices and Control+K elsewhere, filters as they type, and closes once they choose. The palette also works on its own, inside a page. For a short list of actions on one button, use a menu; to pick a value for a form, use a combobox.

Search

Choose a command

Dashboard
Claims
Policies
Payments
New claim
Export report
Settings

Choose a command

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add command --framework web-components
npx @nana-tec/ui add command --framework svelte

Lands in src/lib/components/ui/command/ as NanaCommand.svelte and NanaCommandDialog.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

The commands are data, in groups with an optional heading. Each command has an id and a label, and can carry keywords that also match, an icon, a shortcut to show beside it, and disabled. Choosing a command hands it back; what it does is up to you.

A command matches when every word typed appears in its label or keywords, ignoring case, so “new cl” finds “New claim”. Groups left empty are hidden.

<script lang="ts">
import { goto } from '$app/navigation';
import { documentTextIcon, plusIcon } from '@nana-tec/ui-core/heroicons';
import { NanaCommandDialog, type CommandGroup } from '$lib/components/ui/command';
const groups: CommandGroup[] = [
{
heading: 'Pages',
items: [{ id: '/claims', label: 'Claims', icon: documentTextIcon, keywords: ['motor'] }],
},
{
heading: 'Actions',
items: [{ id: 'new-claim', label: 'New claim', icon: plusIcon, shortcut: 'mod+n' }],
},
];
</script>
<NanaCommandDialog {groups} onSelect={(item) => goto(item.id)} />

Bind open to open it from a button as well. NanaCommand is the palette without the dialog, for a page of its own.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/command";

Copied in with npx @nana-tec/ui add command? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-command-dialog></nana-command-dialog>
<script type="module">
const palette = document.querySelector('nana-command-dialog');
palette.groups = [
{
heading: 'Pages',
items: [{ id: '/claims', label: 'Claims', icon: 'document-text', keywords: ['motor'] }],
},
{
heading: 'Actions',
items: [{ id: 'new-claim', label: 'New claim', icon: 'plus', shortcut: 'mod+n' }],
},
];
palette.addEventListener('nana-select', (event) => console.log(event.detail.item.id));
</script>

Call show() to open it from a button as well. <nana-command> is the palette without the dialog, for a page of its own. An icon is the name of a registered icon.

The dialog opens and closes on mod+k: ⌘K on Apple devices, Control+K elsewhere. Set shortcut to another combination in the kbd format, such as mod+shift+p, or turn it off with shortcut={false} in Svelte and shortcut="" on the web component. It opens with the search field focused and empty each time.

The previews on this page use mod+j, because this site’s own search already answers to ⌘K. Pick a combination nothing else on your page uses.

KeyDoes
⌘K or Control+KOpens or closes the palette
TypingFilters the commands
Up and Down arrowsMove through the commands, skipping disabled ones, and wrap around
EnterRuns the highlighted command
EscapeCloses the palette
  • The search field is a combobox over a listbox, named by label, “Commands” by default. Focus stays in the field; the highlighted command is announced as the active option.
  • Each group is named by its heading. A disabled command stays in the list, announced as unavailable, and cannot be run.
  • The message shown when nothing matches is a status, so it is announced as people type.
  • A shortcut shown beside a command is hidden from screen readers; put what it does in the label.

Properties

PropertyAttributeTypeDefaultDescription
emptyemptystring'No results found.'Message shown when nothing matches.
groups—CommandGroup[][]The commands, in groups with an optional heading.
labellabelstring'Commands'Names the dialog, the search field and the list for screen readers.
openopenbooleanfalseWhether the palette is open.
placeholderplaceholderstring'Type a command or search…'Hint shown in the empty search field.
shortcutshortcutstring'mod+k'The combination that opens and closes the palette. An empty value turns it off.

Methods

MethodDescription
close(): voidClose the palette.
show(): voidOpen the palette.

Events

EventDescription
nana-selectA command was chosen (detail.item); the dialog closes
nana-openFired after the dialog opens
nana-closeFired after the dialog closes

CSS parts

PartDescription
::part(dialog)The dialog around the palette
::part(command)The palette

Properties

PropertyAttributeTypeDefaultDescription
emptyemptystring'No results found.'Message shown when nothing matches.
groups—CommandGroup[][]The commands, in groups with an optional heading.
labellabelstring'Commands'Names the search field and the list for screen readers.
placeholderplaceholderstring'Type a command or search…'Hint shown in the empty search field.
queryquerystring''The text in the search field.

Events

EventDescription
nana-selectA command was chosen (detail.item)

CSS parts

PartDescription
::part(base)The palette
::part(search)The row holding the search field
::part(search-icon)The magnifying glass
::part(input)The search field
::part(list)The list of commands
::part(group)A group of commands
::part(heading)A group's heading
::part(item)A command, with the active and disabled states
::part(icon)A command's icon
::part(label)A command's name
::part(shortcut)A command's keyboard shortcut
::part(empty)The message shown when nothing matches

NanaCommand

PropTypeDefault
groupsrequiredreadonly CommandGroup[]
labelstring'Commands'
placeholderstring'Type a command or search…'
emptystring'No results found.'
querybind:string''
onSelect(item: CommandItem) => void

NanaCommandDialog

PropTypeDefault
groupsrequiredreadonly CommandGroup[]
openbind:booleanfalse
shortcutstring | false'mod+k'
labelstring'Commands'
placeholderstring'Type a command or search…'
emptystring'No results found.'
onSelect(item: CommandItem) => void
onOpenChange(open: boolean) => void

groups is required on both. Bind query on NanaCommand to read or set the search.