Commands

A command is a plain object. Its primary action comes from whichever of href, url, run, view or actions you provide:

createQikbar({
  commands: [
    { title: 'Settings', icon: 'settings', href: '/settings' },          // navigate in-app
    { title: 'Status page', icon: 'globe', url: 'https://status.acme.co' }, // open a new tab
    { title: 'Toggle sidebar', icon: 'layout-dashboard', run: () => toggleSidebar() }, // run code
    { title: 'Browse projects', icon: 'folder', view: list({ items: projects }) },     // push a view
  ],
})

Fields

Field	Type	Description
title	string	Required. What the user searches and sees.
subtitle	string	Muted text after the title. Searchable.
icon	Icon	A built-in icon name, image URL, emoji, SVG string or DOM node.
section	string	Groups commands under a heading. Defaults to "Commands".
keywords	string[]	Extra search terms (“invoice” for Billing).
description	string	Longer text. Searchable as a last resort and given to AI models.
accessories	Accessory[]	Right-aligned text, tags, dates or keys.
href	string	Navigate with your router. Adds Open in New Tab and Copy Link actions.
url	string	Open an external URL. Adds Copy URL.
run	(ctx) => void | View | false	Run code. Return a view to push it, or false to keep the bar open.
view	View | (ctx) => View	Push a view.
actions	Action[]	Extra actions, shown in the action panel.
shortcut	string	A global hotkey that works even while the bar is closed, like "mod+shift+d" or "g s".
arguments	Argument[]	Inline inputs asked for before running. See Arguments.
when	() => boolean	Show the command only when this returns true. Checked on each open.
searchOnly	boolean	Hide the command until the user types. Useful for rare or dangerous commands.
priority	number	A ranking boost from 0 to 1.
noHistory	boolean	Don’t track it in Recent.
id	string	A stable id for frecency and AI. Generated from the section and title if omitted.

After a command runs, the bar closes unless the command pushed a view, returned false, or called ctx.push, ctx.render or ctx.navigate itself.

Sections and order

With an empty query, commands appear in the order you register them, grouped by section. A Recent section at the top shows frequently and recently used commands. Configure it with recents: false or recents: 6.

When the user types, matches are ranked by relevance and frecency. Sections are ordered by their best match.

Accessories

{
  title: 'Inbox',
  accessories: [
    { tag: { value: '3 new', color: 'blue' } },
    { text: 'Updated', date: new Date(lastUpdate) }, // "5 min. ago"
    { kbd: 'g i' },
    { icon: 'star', tooltip: 'Favorite' },
  ],
}

Tag colors: gray, blue, green, yellow, orange, red, purple, pink, or any CSS color.

Icons

Strings are interpreted in this order:

1. Built-in names: search, home, settings, user, users, folder, file, file-text, book, bookmark, star, heart, clock, history, calendar, calculator, sun, moon, monitor, palette, sparkles, bot, message, send, mail, bell, credit-card, key, lock, log-out, trash, pencil, eye, download, upload, refresh, filter, globe, code, terminal, hash, zap, layers, grid, list, image, git-branch, package, puzzle, info, alert, check, x, plus, minus, copy, link, external, arrow-right, arrow-left, chevron-right, layout-dashboard, bar-chart, inbox, tag, languages, wand, keyboard, github and more
2. Image URLs: https://…, /…, ./…, data:image/…
3. Inline SVG: a string starting with <svg (treated as trusted HTML)
4. Anything else: rendered as text, for example an emoji '🚀'

You can also pass { url, alt }, a tinted icon { icon: 'folder', color: '#8b5cf6' }, a DOM Node, or a function that returns one.

Contextual commands

Register commands from anywhere, for example while a page is mounted:

const unregister = bar.register([
  { title: `Archive ${project.name}`, icon: 'trash', run: () => archive(project.id) },
])
// later
unregister()

In React, use the useCommands hook.

Fallbacks

Fallbacks appear at the bottom whenever the user has typed something. {query} is replaced with the search text:

createQikbar({
  fallbacks: [
    { title: 'Search the docs for “{query}”', icon: 'book', run: (ctx) => ctx.openUrl(`/docs?q=${ctx.query}`) },
    { title: 'Create issue “{query}”', icon: 'plus', run: (ctx) => createIssue(ctx.query) },
  ],
})

If AI is configured, an Ask AI fallback is added automatically. Tab also triggers it.

Global shortcuts

Commands with a shortcut run even when the bar is closed:

• Combos such as "mod+shift+p" work everywhere, even in text fields.
• Single keys and sequences such as "?" or "g s" are ignored while the user is typing in an input.

mod means ⌘ on macOS and Ctrl elsewhere. Disable all item shortcuts with shortcuts: false.