Navigation
Command
A command palette: a search field over grouped pages and actions, opened from anywhere with ⌘K or Control+K.
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.
Preview
Section titled “Preview”Choose a command
<div
style="
display: flex;
flex-direction: column;
align-items: center;
gap: 1rem;
width: 100%;
"
>
<nana-button variant="secondary" id="command-open">
Search
<nana-kbd keys="mod+j" size="sm"></nana-kbd>
</nana-button>
<nana-command-dialog
id="command-dialog"
shortcut="mod+j"
></nana-command-dialog>
<nana-command
id="command-inline"
label="Example commands"
style="
width: 100%;
max-width: 28rem;
border: 1px solid var(--nana-surface-border);
border-radius: 0.5rem;
overflow: hidden;
"
></nana-command>
<p
id="command-chosen"
aria-live="polite"
style="
margin: 0;
font-size: 0.875rem;
color: var(--nana-surface-text-subtle);
"
>
Choose a command
</p>
</div>
<script type="module">
const groups = [
{
heading: "Pages",
items: [
{ id: "home", label: "Dashboard", icon: "home" },
{
id: "claims",
label: "Claims",
icon: "document-text",
keywords: ["motor", "medical"],
},
{ id: "policies", label: "Policies", icon: "shield-check" },
{
id: "payments",
label: "Payments",
icon: "credit-card",
keywords: ["mpesa"],
},
],
},
{
heading: "Actions",
items: [
{
id: "new-claim",
label: "New claim",
icon: "plus",
shortcut: "mod+n",
},
{
id: "export",
label: "Export report",
icon: "arrow-down-tray",
disabled: true,
},
{
id: "settings",
label: "Settings",
icon: "cog-6-tooth",
shortcut: "mod+,",
},
],
},
];
const dialog = document.getElementById("command-dialog");
const inline = document.getElementById("command-inline");
const chosen = document.getElementById("command-chosen");
dialog.groups = groups;
inline.groups = groups;
document
.getElementById("command-open")
.addEventListener("click", () => dialog.show());
for (const palette of [dialog, inline]) {
palette.addEventListener("nana-select", (event) => {
chosen.textContent = "Ran " + event.detail.item.label;
});
}
</script> Choose a command
<script lang="ts">
import {
arrowDownTrayIcon,
cog6ToothIcon,
creditCardIcon,
documentTextIcon,
homeIcon,
plusIcon,
shieldCheckIcon,
} from '@nana-tec/ui-core/heroicons';
import { NanaButton, NanaCommand, NanaCommandDialog, NanaKbd, type CommandGroup } from '$lib';
const groups: CommandGroup[] = [
{
heading: 'Pages',
items: [
{ id: 'home', label: 'Dashboard', icon: homeIcon },
{ id: 'claims', label: 'Claims', icon: documentTextIcon, keywords: ['motor', 'medical'] },
{ id: 'policies', label: 'Policies', icon: shieldCheckIcon },
{ id: 'payments', label: 'Payments', icon: creditCardIcon, keywords: ['mpesa'] },
],
},
{
heading: 'Actions',
items: [
{ id: 'new-claim', label: 'New claim', icon: plusIcon, shortcut: 'mod+n' },
{ id: 'export', label: 'Export report', icon: arrowDownTrayIcon, disabled: true },
{ id: 'settings', label: 'Settings', icon: cog6ToothIcon, shortcut: 'mod+,' },
],
},
];
let open = $state(false);
let chosen = $state('');
</script>
<div class="flex w-full flex-col items-center gap-4">
<NanaButton variant="secondary" onclick={() => (open = true)}>
Search
<NanaKbd keys="mod+j" size="sm" />
</NanaButton>
<NanaCommandDialog
{groups}
shortcut="mod+j"
bind:open
onSelect={(item) => (chosen = item.label)}
/>
<div class="w-full max-w-md overflow-hidden rounded-lg border border-line shadow-sm">
<NanaCommand {groups} label="Example commands" onSelect={(item) => (chosen = item.label)} />
</div>
<p class="text-sm text-foreground-muted" aria-live="polite">
{chosen ? `Ran ${chosen}` : 'Choose a command'}
</p>
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add command --framework web-componentsnpx @nana-tec/ui add command --framework svelteLands 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.
Shortcut
Section titled “Shortcut”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.
Keyboard
Section titled “Keyboard”| Key | Does |
|---|---|
| ⌘K or Control+K | Opens or closes the palette |
| Typing | Filters the commands |
| Up and Down arrows | Move through the commands, skipping disabled ones, and wrap around |
| Enter | Runs the highlighted command |
| Escape | Closes the palette |
Accessibility
Section titled “Accessibility”- 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
empty | empty | string | 'No results found.' | Message shown when nothing matches. |
groups | — | CommandGroup[] | [] | The commands, in groups with an optional heading. |
label | label | string | 'Commands' | Names the dialog, the search field and the list for screen readers. |
open | open | boolean | false | Whether the palette is open. |
placeholder | placeholder | string | 'Type a command or search…' | Hint shown in the empty search field. |
shortcut | shortcut | string | 'mod+k' | The combination that opens and closes the palette. An empty value turns it off. |
Methods
| Method | Description |
|---|---|
close(): void | Close the palette. |
show(): void | Open the palette. |
Events
| Event | Description |
|---|---|
nana-select | A command was chosen (detail.item); the dialog closes |
nana-open | Fired after the dialog opens |
nana-close | Fired after the dialog closes |
CSS parts
| Part | Description |
|---|---|
::part(dialog) | The dialog around the palette |
::part(command) | The palette |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
empty | empty | string | 'No results found.' | Message shown when nothing matches. |
groups | — | CommandGroup[] | [] | The commands, in groups with an optional heading. |
label | label | string | 'Commands' | Names the search field and the list for screen readers. |
placeholder | placeholder | string | 'Type a command or search…' | Hint shown in the empty search field. |
query | query | string | '' | The text in the search field. |
Events
| Event | Description |
|---|---|
nana-select | A command was chosen (detail.item) |
CSS parts
| Part | Description |
|---|---|
::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
| Prop | Type | Default |
|---|---|---|
groupsrequired | readonly CommandGroup[] | |
label | string | 'Commands' |
placeholder | string | 'Type a command or search…' |
empty | string | 'No results found.' |
querybind: | string | '' |
onSelect | (item: CommandItem) => void |
NanaCommandDialog
| Prop | Type | Default |
|---|---|---|
groupsrequired | readonly CommandGroup[] | |
openbind: | boolean | false |
shortcut | string | false | 'mod+k' |
label | string | 'Commands' |
placeholder | string | 'Type a command or search…' |
empty | string | '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.