# Qikbar documentation (full)

---



---

> The complete Qikbar documentation in one file, for AI assistants and coding agents.

---



---

# Introduction

> Qikbar is a free, open-source command bar for any web app. It brings search, routing, actions, extensions and AI together in one tiny package.

Source: https://qikbar.com/docs

Qikbar adds a **⌘K command bar** to your web app, like Raycast, Linear or Vercel have. Users press <kbd>⌘</kbd><kbd>K</kbd> (<kbd>Ctrl</kbd><kbd>K</kbd> on Windows and Linux) to:

- **Search** everything: pages, commands, and live records from your API
- **Navigate** anywhere using your existing router
- **Act** with keyboard-driven actions, forms and nested views
- **Ask AI** to do things: “open the Acme project”, “invite Sam to the team”

```ts
import { createQikbar } from '@qikbar/qikbar'

createQikbar({
  routes: [
    { path: '/', title: 'Home', icon: 'home' },
    { path: '/settings', title: 'Settings', icon: 'settings' },
  ],
  commands: [{ title: 'Toggle dark mode', icon: 'moon', run: () => toggleTheme() }],
})
```

That's a complete integration. Press <kbd>⌘</kbd><kbd>K</kbd>.

## Why Qikbar

**Batteries included.** A command palette needs fuzzy ranking, keyboard handling, accessibility, async data, nested views, theming and, increasingly, AI. Qikbar ships all of it so you don't have to build it.

**Framework-agnostic.** The core is plain TypeScript with zero dependencies. Use the vanilla API anywhere, the React bindings in React and Next.js, or a single `<script>` tag.

**Fast.** About 3.5 KB boots the shell. The UI loads when the browser is idle. Ranking 10,000 commands takes about 3 ms, and lists with 100,000 rows are virtualized.

**AI-native.** Connect Claude, GPT, Gemini, a local model, or a proxy to your own server. Every command, route and data source becomes a tool the model can call. Users type what they want and Qikbar does it.

**Extensible.** The [extensions API](/docs/extensions) is inspired by Raycast. It bundles commands, live sources, AI tools and user preferences into a portable package.

**Yours.** MIT licensed. No accounts, no tracking, no SaaS.

## Core ideas

| Concept | What it is |
| --- | --- |
| [Commands](/docs/commands) | Items at the root of the bar: a title, an icon, and something to do |
| [Routes](/docs/routing) | Pages in your app, opened with your router |
| [Sources](/docs/sources) | Async search providers, for example records from your API |
| [Views](/docs/views) | Screens a command can push: list, grid, detail, form, chat |
| [Actions](/docs/actions) | What you can do with the selected item (<kbd>↵</kbd>, <kbd>⌘</kbd><kbd>↵</kbd>, <kbd>⌘</kbd><kbd>.</kbd>) |
| [Extensions](/docs/extensions) | Reusable bundles of commands, sources, tools and preferences |
| [AI](/docs/ai) | Chat and natural-language actions with any model |

Everything is **plain data**. A command is an object, a view is an object, and an action is an object with a `run` function. You can generate them, serialize most of them, and an AI model can reason about them.

## Where to go next

<div class="doc-cards">
  <a href="/docs/quick-start"><strong>Quick start</strong><span>Routes, commands, search and a form in five minutes.</span></a>
  <a href="/docs/ai-setup"><strong>Set up with AI</strong><span>One prompt for Claude Code, Cursor or Copilot.</span></a>
  <a href="/docs/views"><strong>Views</strong><span>Lists, grids, Markdown, forms and chats.</span></a>
  <a href="/docs/ai"><strong>AI</strong><span>Let users ask, and let the model act.</span></a>
  <a href="/docs/extensions"><strong>Extensions</strong><span>Package and share functionality.</span></a>
  <a href="/docs/theming"><strong>Theming</strong><span>Presets, variables and your design tokens.</span></a>
  <a href="/docs/react"><strong>React</strong><span>The component, hooks and a trigger button.</span></a>
  <a href="/docs/recipes-backend-search"><strong>Recipes</strong><span>Backend search, switchers, copilots and more.</span></a>
</div>


---

# Installation

> Install Qikbar from npm or load it from a CDN with a script tag.

Source: https://qikbar.com/docs/installation

## Package manager

```bash
npm install @qikbar/qikbar
# or
pnpm add @qikbar/qikbar
yarn add @qikbar/qikbar
bun add @qikbar/qikbar
```

Qikbar has **no dependencies**. React is an optional peer dependency, needed only if you import `@qikbar/qikbar/react`.

## Entry points

| Import | Use it for |
| --- | --- |
| `@qikbar/qikbar` | `createQikbar`, view helpers (`list`, `form`, …), AI providers, types |
| `@qikbar/qikbar/react` | `<Qikbar>`, `useQikbar`, `useCommands`, `useSource`, `useExtension`, `<QikbarTrigger>` |
| `@qikbar/qikbar/extensions` | Built-in extensions: `calculator`, `themeSwitcher`, `page`, `aiActions`, `shortcuts` |
| `@qikbar/qikbar/server` | `createHandler` for an AI proxy endpoint, plus server-side providers |
| `@qikbar/qikbar/theme` | Theme presets, `themeToCss`, the default stylesheet as a string |
| `@qikbar/qikbar/utils` | The fuzzy matcher, Markdown renderer, icons, hotkey helpers |
| `@qikbar/qikbar/styles.css` | The default stylesheet as a file (optional; styles are injected automatically) |

## CDN / script tag

You don't need a build step:

```html
<script src="https://unpkg.com/@qikbar/qikbar/dist/qikbar.global.js"></script>
<script>
  const bar = Qikbar.createQikbar({ autoIndex: true })
</script>
```

Everything is available on the `Qikbar` global, including the built-in extensions under `Qikbar.extensions`.

Or use native ES modules:

```html
<script type="module">
  import { createQikbar } from 'https://esm.sh/@qikbar/qikbar'
  createQikbar({ autoIndex: true })
</script>
```

## Requirements

- Any evergreen browser (Chrome, Edge, Firefox, Safari 16.4+)
- TypeScript 5+ for types (optional)
- Server helpers run on any runtime with Web `Request` / `Response`: Node 18+, Bun, Deno, Cloudflare Workers, Vercel and Netlify

## Styles

By default Qikbar injects one `<style id="qikbar-styles">` tag the first time the bar opens. If your [Content Security Policy](/docs/styling#content-security-policy) blocks inline styles, pass a `nonce`, or set `unstyled: true` and import `@qikbar/qikbar/styles.css` yourself.


---

# Quick start

> Add a fully featured command bar to your app in five minutes.

Source: https://qikbar.com/docs/quick-start

This guide builds a command bar with routes, commands, live search and a form. It takes about five minutes.

## 1. Create the bar

Call `createQikbar` once, on the client:

```ts
import { createQikbar } from '@qikbar/qikbar'

export const bar = createQikbar({
  placeholder: 'Search or jump to…',
})
```

Press <kbd>⌘</kbd><kbd>K</kbd>. The bar is empty, so let's fill it.

> [!TIP]
> Using React? Render `<Qikbar />` from `@qikbar/qikbar/react` instead. It takes the same options as props. See [React](/docs/react).

## 2. Add routes

Routes are pages in your app. Pass your router's navigate function so navigation stays client-side:

```ts
createQikbar({
  navigate: (href) => router.push(href),
  routes: [
    { path: '/', title: 'Dashboard', icon: 'home' },
    { path: '/projects', title: 'Projects', icon: 'folder' },
    { path: '/settings/billing', title: 'Billing', icon: 'credit-card', keywords: ['invoice', 'plan'] },
  ],
})
```

If you don't pass `navigate`, Qikbar clicks a matching link on the page, which works with most routers. Otherwise it does a normal navigation. See [Routing](/docs/routing).

## 3. Add commands

Commands run code. Group them with `section` and give them global shortcuts:

```ts
commands: [
  { title: 'New project', icon: 'plus', section: 'Projects', shortcut: 'c p', run: () => openNewProjectDialog() },
  { title: 'Toggle sidebar', icon: 'layout-dashboard', shortcut: 'mod+b', run: () => toggleSidebar() },
  { title: 'Sign out', icon: 'log-out', run: () => signOut() },
]
```

`shortcut: 'c p'` means press <kbd>C</kbd> then <kbd>P</kbd>, anywhere in your app.

## 4. Search your data

A **source** searches your API as the user types. Qikbar debounces the calls, cancels stale requests, and merges the results into their own section:

```ts
sources: [
  {
    id: 'projects',
    title: 'Projects',
    async search({ query, signal }) {
      const res = await fetch(`/api/projects?q=${encodeURIComponent(query)}`, { signal })
      const projects = await res.json()
      return projects.map((p) => ({
        title: p.name,
        subtitle: p.owner,
        icon: 'folder',
        href: `/projects/${p.id}`,
      }))
    },
  },
]
```

## 5. Push a view

Commands can open **views**: lists, grids, Markdown details, forms and AI chats. Here's a form:

```ts
import { form } from '@qikbar/qikbar'

commands: [
  {
    title: 'Invite teammate',
    icon: 'users',
    view: form({
      title: 'Invite teammate',
      fields: [
        { name: 'email', label: 'Email', type: 'email', required: true },
        { name: 'role', label: 'Role', type: 'select', options: [{ title: 'Member', value: 'member' }, { title: 'Admin', value: 'admin' }] },
      ],
      async onSubmit(values, ctx) {
        await api.invite(values)
        ctx.toast({ title: `Invited ${values.email}`, style: 'success' })
      },
    }),
  },
]
```

## 6. Add extensions

```ts
import { calculator, themeSwitcher, shortcuts } from '@qikbar/qikbar/extensions'

createQikbar({
  // …
  extensions: [calculator(), themeSwitcher(), shortcuts()],
})
```

Now typing `12 * 7` or `5 km in mi` shows the answer instantly.

## 7. Make it yours

Pick a [theme preset](/docs/theming) or match your design tokens:

```ts
createQikbar({
  theme: { preset: 'linear', vars: { accent: 'var(--brand)', radius: '10px', font: 'inherit' } },
})
```

## 8. Optional: AI

```ts
import { proxy } from '@qikbar/qikbar'

createQikbar({ ai: proxy('/api/qikbar') })
```

Users can now press <kbd>Tab</kbd> to ask AI, and the model can run your commands. See [AI](/docs/ai) to set up the server route.

## Add a trigger button

Any element with `data-qikbar-open` opens the bar:

```html
<button data-qikbar-open>Search… <kbd>⌘K</kbd></button>
```

Or call `bar.open()`.


---

# Set up with AI

> A copy-paste prompt that lets Claude Code, Cursor, Copilot or Codex add Qikbar to your app.

Source: https://qikbar.com/docs/ai-setup

Qikbar is designed so that a coding agent can integrate it in one pass. The agent reads your router, pages and API, then writes the config. Copy this prompt into Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, or any other agent:

```text
Add a Qikbar command bar (⌘K) to this app.

Qikbar is an open-source, zero-dependency command bar library (npm package `@qikbar/qikbar`). The full documentation for AI agents is at https://qikbar.com/llms-full.txt. Read it before you start.

Do the following:

1. Install it with this project's package manager (`npm install @qikbar/qikbar`, `pnpm add @qikbar/qikbar`, `yarn add @qikbar/qikbar` or `bun add @qikbar/qikbar`).

2. Find how this app does routing (Next.js, React Router, TanStack Router, Vue Router, SvelteKit, Remix, Astro, or plain links). Mount Qikbar once, near the root:
   - React and Next.js: render `<Qikbar … />` from `@qikbar/qikbar/react` in the root layout or a top-level client component.
   - Anything else: call `createQikbar({ … })` from `@qikbar/qikbar` once on the client.
   - Pass the router's navigate function as `navigate`, for example `navigate: (href) => router.push(href)`.

3. Add a `routes` entry for every main page you find (path, title, an `icon` from the built-in icon names, and `keywords`). Group them with `section`.

4. Add `commands` for the main actions a user takes (create, invite, toggle, sign out, open settings…). Wire them to the app's existing functions. Use `view: form({...})` for actions that need input. Use `arguments` for one or two quick text inputs.

5. For each main kind of record (projects, users, documents, orders…), add a `sources` entry. It calls the app's existing API or data layer with the query and returns items (`title`, `subtitle`, `href`, `icon`). Respect the `signal` for cancellation.

6. Make it match the app's design. Set `theme: { vars: { … } }` from the app's colors, font, and radius (accent, bg, fg, border, radius, font). Set `appearance: 'auto'` if the app has a dark mode.

7. Add a visible trigger, for example a "Search… ⌘K" button in the header, with the `data-qikbar-open` attribute or `useQikbar().open()`.

8. If the app already uses an AI provider, or the user wants AI: add a server route with `createHandler` from `@qikbar/qikbar/server`, and set `ai: proxy('/api/qikbar')` on the client. Keep API keys on the server. Otherwise skip AI.

9. Add the built-in extensions that fit: `calculator()`, `themeSwitcher()` (only if the app has dark mode), and `shortcuts()` from `@qikbar/qikbar/extensions`.

10. Run the type checker and the build. Fix any errors. Then summarize what you added, with file paths.

Keep the changes small and idiomatic for this codebase. Don't add new dependencies besides `@qikbar/qikbar`.
```

You can also fetch it directly: [`/prompt.txt`](/prompt.txt).

## Documentation for AI

Every page in these docs is available as plain Markdown:

- **[/llms.txt](/llms.txt)**: an index of every page, following the [llms.txt](https://llmstxt.org) convention
- **[/llms-full.txt](/llms-full.txt)**: the entire documentation in one file
- **Any page + `.md`**: for example [`/docs/sources.md`](/docs/sources.md)

Each docs page also has **Copy as Markdown**, **Open in Claude** and **Open in ChatGPT** buttons at the top.

## Tips for agents

- Mount Qikbar **once**. In React, render `<Qikbar>` near the root. Elsewhere, call `createQikbar` in your client entry.
- Use the app's router for `navigate`. Never hard-code `window.location` if a router exists.
- Use `sources` for data that lives on the server, with the app's existing fetch layer.
- Theme with the app's existing CSS variables, for example `vars: { accent: 'var(--primary)' }`.
- Keep AI keys on the server with `createHandler` from `@qikbar/qikbar/server`.

## Add Qikbar to your project instructions

If your repo has an `AGENTS.md`, `CLAUDE.md` or `.cursor/rules`, add this line so future changes keep the bar up to date:

```md
When adding a page, route, or user-facing action, also register it with Qikbar (see src/command-bar.ts). Qikbar docs: https://qikbar.com/llms.txt
```


---

# Commands

> Commands are the items at the root of the bar. Each has a title, an icon, and something to do.

Source: https://qikbar.com/docs/commands

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

```ts
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](#icons) 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](/docs/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](/docs/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

```ts
{
  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:

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

In React, use the [`useCommands`](/docs/react#usecommands) hook.

## Fallbacks

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

```ts
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](/docs/ai) is configured, an **Ask AI** fallback is added automatically. <kbd>Tab</kbd> 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 <kbd>⌘</kbd> on macOS and <kbd>Ctrl</kbd> elsewhere. Disable all item shortcuts with `shortcuts: false`.


---

# Routing

> Turn your app's pages into searchable destinations and navigate with your existing router.

Source: https://qikbar.com/docs/routing

## Routes

```ts
createQikbar({
  routes: [
    { path: '/', title: 'Home', icon: 'home' },
    { path: '/projects', title: 'Projects', icon: 'folder', keywords: ['work'] },
    { path: '/settings/billing', title: 'Billing', icon: 'credit-card', section: 'Settings', shortcut: 'g b' },
  ],
})
```

Each route becomes a command with `href: path`, in the **Navigation** section unless you set `section`. Routes get *Open*, *Open in New Tab* (<kbd>⌘</kbd><kbd>↵</kbd>) and *Copy Link* actions.

Any command or list item can navigate with `href`, and code can navigate with `ctx.navigate(href)`.

## Connect your router

Pass `navigate` so navigation is client-side:

```ts
createQikbar({ navigate: (href, { newTab }) => (newTab ? window.open(href) : router.push(href)) })
```

| Router | `navigate` |
| --- | --- |
| Next.js (App Router) | `const router = useRouter()` → `(href) => router.push(href)` |
| React Router | `const navigate = useNavigate()` → `(href) => navigate(href)` |
| TanStack Router | `(href) => router.navigate({ to: href })` |
| Vue Router | `(href) => router.push(href)` |
| SvelteKit | `import { goto } from '$app/navigation'` → `(href) => goto(href)` |
| Nuxt | `(href) => navigateTo(href)` |
| Angular | `(href) => this.router.navigateByUrl(href)` |
| Remix / React Router 7 | `(href) => navigate(href)` |
| Astro (View Transitions) | `import { navigate } from 'astro:transitions/client'` → `(href) => navigate(href)` |

### The default navigator

If you don't pass `navigate`, Qikbar:

1. Clicks an existing `<a href>` on the page with the same `href`. This runs framework link handlers, such as Next.js `<Link>`.
2. Otherwise clicks a temporary anchor. Routers that intercept anchor clicks pick this up: SvelteKit, Astro, Nuxt, Turbo, htmx-boost and others.
3. Otherwise the browser does a normal navigation.

This works for most apps without configuration.

## Index your page automatically

`autoIndex` turns links and elements already on your page into commands. You don't need to configure anything:

```ts
createQikbar({ autoIndex: true })
```

It indexes:

- **Links** in `nav`, `header`, `aside` and `[data-qikbar-index]`. A link's section comes from `data-qikbar-section` or the nav's `aria-label`.
- **Elements with `data-qikbar`**, which become commands that click the element:

```html
<button data-qikbar="Sign out" data-qikbar-icon="log-out" data-qikbar-keywords="logout,exit">Sign out</button>
<button data-qikbar="Export CSV" data-qikbar-section="Reports" data-qikbar-shortcut="mod+e">Export</button>
```

Add `data-qikbar-ignore` to skip a region. Indexing runs each time the bar opens, so it always reflects the current page.

```ts
createQikbar({
  autoIndex: { links: 'nav a, .sidebar a', elements: true, section: 'Pages' },
})
```

## Dynamic routes

For routes with parameters, like `/projects/:id`, use a [source](/docs/sources) that returns items with `href`:

```ts
sources: [{
  id: 'projects',
  title: 'Projects',
  search: async ({ query }) => (await api.projects.search(query)).map((p) => ({
    title: p.name, icon: 'folder', href: `/projects/${p.id}`,
  })),
}]
```


---

# Sources

> Search your API, database or any async data as the user types.

Source: https://qikbar.com/docs/sources

A **source** provides results for the root search. Qikbar debounces the calls, cancels stale requests with an `AbortSignal`, and shows each source's results in its own section:

```ts
createQikbar({
  sources: [
    {
      id: 'customers',
      title: 'Customers',
      minQueryLength: 2,
      debounce: 200,
      limit: 6,
      async search({ query, signal }) {
        const res = await fetch(`/api/customers?q=${encodeURIComponent(query)}`, { signal })
        const rows = await res.json()
        return rows.map((c) => ({
          id: `customer:${c.id}`,
          title: c.name,
          subtitle: c.email,
          icon: c.avatarUrl,
          href: `/customers/${c.id}`,
          accessories: [{ tag: { value: c.plan, color: 'purple' } }],
        }))
      },
    },
  ],
})
```

## Options

| Option | Default | Description |
| --- | --- | --- |
| `id` | — | **Required.** A unique id. |
| `title` | `"Results"` | The section heading. |
| `search({ query, signal, ctx })` | — | **Required.** Returns items, or a promise of items. |
| `minQueryLength` | `1` | Don't search below this length. |
| `debounce` | `150` | Milliseconds to wait after typing stops. |
| `limit` | `8` | The most results to show. |
| `filter` | `false` | Re-rank results with the local fuzzy matcher. Useful when `search` returns everything. |
| `position` | `"bottom"` | `"top"` puts results above matching commands (the calculator does this). |

## Behavior

- While a source loads, a thin progress bar animates under the input.
- Results from the previous query that still match stay visible, so the list doesn't flash empty.
- The top result stays selected as results arrive, unless the user has moved the selection.
- An error in one source is logged and doesn't affect other sources.
- AI models can query your sources through the built-in `search` tool. See [AI tools](/docs/ai-tools).

## Static data with local filtering

If your dataset is small, return everything and let Qikbar rank it:

```ts
{
  id: 'docs',
  title: 'Documentation',
  filter: true,
  debounce: 0,
  search: async () => (await getDocsIndex()).map((d) => ({ title: d.title, href: d.url })),
}
```

## Adding sources at runtime

```ts
const remove = bar.addSource(mySource)
```

In React, use [`useSource`](/docs/react#usesource).


---

# Views

> Push lists, grids, Markdown documents, forms and AI chats onto the navigation stack.

Source: https://qikbar.com/docs/views

Commands can open **views**. Views stack like pages: <kbd>Esc</kbd> or <kbd>⌫</kbd> on an empty input goes back, and the header shows a breadcrumb. There are five types:

| Helper | Shows |
| --- | --- |
| `list()` | A searchable list, optionally with a Markdown side panel |
| `grid()` | A grid of images or icons |
| `detail()` | A Markdown document with optional metadata. It can stream. |
| `form()` | Fields with validation |
| `chat()` | An AI conversation |

The helpers only add a `type` field. `list({...})` is the same as `{ type: 'list', ... }`.

```ts
import { list, grid, detail, form, chat } from '@qikbar/qikbar'
```

## Opening a view

```ts
// As a command's primary action
{ title: 'Projects', view: list({ items: projects }) }

// Lazily: build the view when it opens
{ title: 'Projects', view: async (ctx) => list({ items: await api.projects() }) }

// Return it from run or an action
{ title: 'Projects', run: () => list({ items: projects }) }

// Imperatively
ctx.push(view)
bar.push(view)
bar.open({ view })
```

## List

```ts
list({
  title: 'Issues',                     // breadcrumb
  placeholder: 'Search issues…',
  items: [ { title: 'Fix login', subtitle: '#142', accessories: [{ tag: 'bug' }] } ],
  detail: true,                        // show item.detail Markdown in a side panel
  emptyView: { title: 'No issues', description: 'You are all caught up', icon: 'check-circle' },
  actions: [ /* actions available on every item */ ],
})
```

### Async items

Pass a function to load items. It receives the current query and an `AbortSignal`, and is debounced (`debounce`, 120 ms by default). With a loader, local filtering is off by default because your loader handles the query. Set `filter: true` to rank results locally.

```ts
list({
  items: async ({ query, signal }) => {
    const res = await fetch(`/api/issues?q=${query}`, { signal })
    return (await res.json()).map(toItem)
  },
})
```

### Streaming items

Return an async iterable to show results progressively, for example from pagination or a slow backend:

```ts
list({
  async *items({ query }) {
    let page = 1
    let all = []
    while (page <= 3) {
      all = [...all, ...(await api.search(query, page++))]
      yield all
    }
  },
})
```

### Sections

Items with a `section` field are grouped under headings, in the order the sections first appear.

### Detail panel

With `detail: true`, the selected item's `detail` field is rendered as Markdown next to the list. `detail` can be a string or an async function, and results are cached per item.

```ts
{ title: 'README.md', detail: async () => await fetchReadme() }
```

## Grid

```ts
grid({
  title: 'Team',
  columns: 5,           // default 5
  aspectRatio: '1',     // or '16/9'
  fit: 'cover',         // or 'contain'
  items: people.map((p) => ({ title: p.name, subtitle: p.role, image: p.avatar })),
})
```

Arrow keys move in two dimensions. `items` can be a loader, like in lists.

## Detail

```ts
detail({
  title: 'Release notes',
  markdown: '# v2.0\n\n- New things',
  metadata: [
    { label: 'Version', value: '2.0.0' },
    { label: 'Status', tag: { value: 'Stable', color: 'green' } },
    { label: 'Docs', value: 'Read more', href: '/docs' },
  ],
  actions: [action.copy(text, { title: 'Copy release notes' })],
})
```

`markdown` can be a string, an async function, or an **async iterable of chunks**, so you can stream AI output straight into it:

```ts
{
  title: 'Summarize this page',
  run: (ctx) => detail({ title: 'Summary', markdown: ctx.ai!.stream(`Summarize: ${document.body.innerText}`) }),
}
```

Markdown is rendered safely. HTML is escaped and `javascript:` links are removed. It supports headings, lists, task lists, tables, code blocks with a copy button, quotes, links and images.

## Form

```ts
form({
  title: 'New issue',
  submitLabel: 'Create issue',
  fields: [
    { name: 'title', label: 'Title', required: true, placeholder: 'Short summary' },
    { name: 'body', label: 'Description', type: 'textarea' },
    { name: 'priority', label: 'Priority', type: 'select', options: [{ title: 'High', value: 'high' }, { title: 'Low', value: 'low' }] },
    { name: 'due', label: 'Due', type: 'date' },
    { name: 'notify', label: 'Notify the team', type: 'checkbox', defaultValue: true },
    { name: 'estimate', label: 'Estimate', type: 'number', validate: (v) => (v > 40 ? 'Too big, split it up' : undefined) },
  ],
  async onSubmit(values, ctx) {
    await api.createIssue(values)
    ctx.toast({ title: 'Issue created', style: 'success' })
  },
})
```

Field types: `text`, `textarea`, `password`, `number`, `email`, `url`, `checkbox`, `select` and `date`.

Submit with <kbd>⌘</kbd><kbd>↵</kbd>, or <kbd>↵</kbd> in a single-line field. Like actions, `onSubmit` closes the bar when it finishes. Return `false` to stay, or return a view to push it.

## Chat

```ts
chat({ title: 'Support', prompt: 'How do I export my data?', system: 'You are Acme support.', tools: false })
```

It opens an AI conversation and sends `prompt` immediately if you set one. Requires [AI](/docs/ai). `bar.ask(prompt)` is a shortcut.

## Re-rendering

Call `ctx.render(view)` to replace the current view, for example after changing data. The search text and selection are kept:

```ts
const todos = () =>
  list({
    title: 'Todos',
    items: store.todos.map((t) => ({
      title: t.text,
      icon: t.done ? 'check-circle' : 'circle',
      run: (ctx) => {
        store.toggle(t.id)
        ctx.render(todos())
        return false
      },
    })),
  })
```

## Lifecycle

- Every view's `ctx.signal` is aborted when the view is popped or the bar closes. Pass it to `fetch`.
- `onClose()` runs when the view is removed.
- The navigation stack resets each time the bar opens.


---

# Actions

> Primary and secondary actions, the action panel, shortcuts, and built-in action helpers.

Source: https://qikbar.com/docs/actions

Every item can have several **actions**. The first is the **primary** action (<kbd>↵</kbd>), the second is the **secondary** action (<kbd>⌘</kbd><kbd>↵</kbd>), and all of them are listed in the **action panel** (<kbd>⌘</kbd><kbd>.</kbd>). The panel works like Raycast's.

```ts
{
  title: 'Q3 report',
  href: '/reports/q3',             // primary: Open. Secondary: Open in New Tab.
  actions: [
    action.copy('https://acme.co/r/q3', { title: 'Copy share link' }),
    { title: 'Export as PDF', icon: 'download', shortcut: 'mod+e', run: () => exportPdf('q3') },
    { title: 'Delete report', icon: 'trash', style: 'destructive', section: 'Danger', shortcut: 'mod+backspace', run: deleteReport },
  ],
}
```

## Action fields

| Field | Description |
| --- | --- |
| `title` | **Required.** |
| `run(ctx)` | **Required.** Return a view to push it, or `false` to keep the bar open. |
| `icon` | Any [icon](/docs/commands#icons). |
| `shortcut` | Runs the action while the bar is open, for example `"mod+c"`. |
| `section` | Groups actions in the panel. |
| `style` | `"destructive"` shows the action in red. When AI runs it, the user is asked to confirm first. |
| `keepOpen` | Keep the bar open after running. |

## How actions are built

The action list for an item is assembled in this order:

1. Shorthands: `run` (*Run*), `view` (*Open*), `href` (*Open*, *Open in New Tab*, *Copy Link*), `url` (*Open in Browser*, *Copy URL*)
2. The item's own `actions`
3. The view's `actions`, which apply to every item in that view
4. For extension commands: *Configure Extension*, if the extension has preferences

## Built-in helpers

```ts
import { action } from '@qikbar/qikbar'

action.copy(text | () => text, options?)   // Copy to Clipboard (⌘C)
action.open(url, options?)                 // Open in Browser
action.navigate(href, options?)            // Open with your router
action.navigateNewTab(href, options?)      // Open in New Tab (⌘↵)
action.push(title, view, options?)         // Push a view
action.ask(prompt, options?)               // Ask AI (⌘J)
```

`options` overrides any field, for example `action.copy(id, { title: 'Copy ID', shortcut: 'mod+i' })`.

## The action panel

Press <kbd>⌘</kbd><kbd>.</kbd> (or <kbd>Ctrl</kbd><kbd>.</kbd>), or click **Actions** in the footer. You can type to filter, use the arrow keys and <kbd>↵</kbd> to run, and <kbd>Esc</kbd> to close. Change the key with `actionsHotkey`.

## Confirmation

```ts
{
  title: 'Delete workspace',
  style: 'destructive',
  async run(ctx) {
    const ok = await ctx.confirm({ title: 'Delete workspace?', message: 'This cannot be undone.', destructive: true, confirmLabel: 'Delete' })
    if (!ok) return false
    await api.deleteWorkspace()
    ctx.toast({ title: 'Workspace deleted', style: 'success' })
  },
}
```

## Toasts

```ts
const t = ctx.toast({ title: 'Deploying…', style: 'loading' })
await deploy()
t.update({ title: 'Deployed', style: 'success' })
```

Styles: `success`, `failure`, `loading` and `info`. While the bar is open, toasts appear in the footer. When it's closed, they appear as a small floating HUD. Loading toasts stay until you update or hide them. Others hide after 2.6 seconds unless you set `duration`.

## Errors

If `run` throws, Qikbar shows a failure toast with the error message and logs the error. The bar stays open.


---

# Arguments

> Ask for a value or two inline, right in the search bar, before a command runs.

Source: https://qikbar.com/docs/arguments

Some commands need a quick input: a language, a name, an amount. Instead of opening a form, declare `arguments`. Qikbar then shows inline fields in the search bar, like Raycast:

```ts
{
  title: 'Translate',
  icon: 'languages',
  arguments: [
    { name: 'text', placeholder: 'Text', required: true },
    { name: 'to', placeholder: 'Language', type: 'dropdown', options: [
      { title: 'French', value: 'fr' },
      { title: 'Spanish', value: 'es' },
    ] },
  ],
  run: (ctx) => translate(ctx.arguments.text, ctx.arguments.to),
}
```

Select the command and press <kbd>↵</kbd> or <kbd>Tab</kbd>. The fields appear and the first one is focused. <kbd>Tab</kbd> moves between fields, <kbd>↵</kbd> runs the command, and <kbd>Esc</kbd> cancels.

| Field | Description |
| --- | --- |
| `name` | **Required.** The key in `ctx.arguments`. |
| `placeholder` | The label shown in the field. |
| `type` | `text` (default), `password` or `dropdown`. |
| `required` | Blocks running until the field is filled. |
| `options` | `{ title, value }[]` for dropdowns. |

When the AI runs a command, it fills in the arguments itself.

> [!TIP]
> Need more than two or three inputs, or validation? Use a [form view](/docs/views#form).


---

# Context

> The ctx object passed to every run function, action, loader and form handler.

Source: https://qikbar.com/docs/context

Every `run`, action, loader, source, form `onSubmit` and AI tool receives a **context** object. It's how your code talks to the bar.

```ts
{
  title: 'Deploy',
  async run(ctx) {
    if (!(await ctx.confirm('Deploy to production?'))) return false
    const t = ctx.toast({ title: 'Deploying…', style: 'loading' })
    await deploy({ signal: ctx.signal })
    t.update({ title: 'Deployed', style: 'success' })
  },
}
```

## Reference

| Member | Description |
| --- | --- |
| `ctx.query` | The current search text. |
| `ctx.signal` | An `AbortSignal` that fires when the view is popped, the query changes (for loaders), or the bar closes. |
| `ctx.arguments` | Values for the command's [arguments](/docs/arguments). |
| `ctx.preferences` | Values for the extension's [preferences](/docs/extensions#preferences). Empty for app commands. |
| `ctx.storage` | Persistent key-value storage, namespaced per extension: `get(key)`, `set(key, value)`, `remove(key)`. |
| `ctx.ai` | The AI client: `ask(prompt)` returns a promise of the answer, `stream(prompt)` returns an async iterable of text. `undefined` without AI. |
| `ctx.push(view)` | Push a view. |
| `ctx.pop()` | Go back. |
| `ctx.render(view)` | Replace the current view, keeping the query and selection. |
| `ctx.close()` | Close the bar. |
| `ctx.navigate(href, { newTab? })` | Navigate with your router, then close the bar. |
| `ctx.openUrl(url)` | Open a URL in a new tab and close the bar. |
| `ctx.copy(text)` | Copy to the clipboard. Resolves to `true` on success. |
| `ctx.toast(options)` | Show a toast. Returns `{ update, hide }`. |
| `ctx.confirm(options)` | Ask the user to confirm. Resolves to a boolean. |
| `ctx.setQuery(text)` | Change the search text. |
| `ctx.bar` | The [Qikbar instance](/docs/api#instance). |

## Storage

`ctx.storage` uses `localStorage` by default, and falls back to memory during SSR or in private mode. Values are JSON-serialized. Each extension gets its own namespace, so keys don't collide.

```ts
const recent = ctx.storage.get<string[]>('recent') ?? []
ctx.storage.set('recent', [item.id, ...recent].slice(0, 10))
```

Replace the backend with the `storage` config option. It takes any object with `getItem`, `setItem` and `removeItem`.

## AI

```ts
const answer = await ctx.ai?.ask('Write a commit message for: ' + diff)
for await (const chunk of ctx.ai!.stream('Explain this error: ' + error)) output += chunk
```


---

# Keyboard

> Every keyboard shortcut in Qikbar, and how to define your own.

Source: https://qikbar.com/docs/keyboard

## Built-in keys

| Key | Action |
| --- | --- |
| <kbd>⌘</kbd><kbd>K</kbd> / <kbd>Ctrl</kbd><kbd>K</kbd> | Open or close the bar (`hotkey`) |
| <kbd>↑</kbd> <kbd>↓</kbd>, <kbd>Ctrl</kbd><kbd>N</kbd> / <kbd>Ctrl</kbd><kbd>P</kbd> | Move the selection (wraps around) |
| <kbd>⌘</kbd><kbd>↑</kbd> / <kbd>⌘</kbd><kbd>↓</kbd> | Jump to the first or last item |
| <kbd>PgUp</kbd> / <kbd>PgDn</kbd> | Move by 8 |
| <kbd>↵</kbd> | Run the primary action |
| <kbd>⌘</kbd><kbd>↵</kbd> | Run the secondary action |
| <kbd>⌘</kbd><kbd>.</kbd> | Open the action panel (`actionsHotkey`) |
| <kbd>Tab</kbd> | Ask AI, or fill in a command's arguments |
| <kbd>Esc</kbd> | Close the panel, stop the AI, go back, clear the search, then close the bar |
| <kbd>⌫</kbd> on an empty input | Go back |
| <kbd>←</kbd> <kbd>→</kbd> | Move within a grid |

## Shortcut syntax

```
mod+k            ⌘K on Mac, Ctrl+K elsewhere
shift+mod+p      modifiers in any order: mod, cmd/meta, ctrl, alt/option, shift
alt+enter        named keys: enter, escape/esc, tab, space, backspace, delete, up, down, left, right
g s              a sequence: press G, then S (within 900 ms)
?                a single character
```

Letter shortcuts use the **physical key** (`KeyboardEvent.code`), so <kbd>⌥</kbd> combinations work on macOS and on non-QWERTY layouts.

## Where shortcuts apply

| Defined on | Works |
| --- | --- |
| `hotkey` (config) | Everywhere, always |
| Command `shortcut` | Globally while the bar is closed. Combos with modifiers also work inside text fields. Single keys and sequences don't. |
| Action `shortcut` | While the bar is open and the item is selected |
| Accessory `kbd` | Display only |

## Changing defaults

```ts
createQikbar({
  hotkey: ['mod+k', '/'],     // several hotkeys, or false to disable
  actionsHotkey: 'mod+j',
  shortcuts: false,           // turn off global command shortcuts
})
```

## Display helpers

```ts
import { formatHotkey } from '@qikbar/qikbar'
formatHotkey('mod+shift+p') // [['⌘', '⇧', 'P']] on Mac, [['Ctrl', 'Shift', 'P']] elsewhere
```

The `shortcuts()` extension adds a searchable **Keyboard Shortcuts** cheat sheet that lists every command with a shortcut.


---

# AI

> Chat, answers and natural-language actions with any model. The AI can run your app's commands as tools.

Source: https://qikbar.com/docs/ai

Add one option and your command bar becomes an assistant that can act on the user's behalf:

```ts
import { createQikbar, proxy } from '@qikbar/qikbar'

createQikbar({
  routes,
  commands,
  sources,
  ai: proxy('/api/qikbar'), // or anthropic(), openai(), gemini(), byok()…
})
```

## What users get

- **Ask AI from anywhere.** Type a question and press <kbd>Tab</kbd>, or pick the **Ask AI** fallback at the bottom of the results.
- **Natural-language actions.** “Take me to billing”, “open the Apollo project”, “invite sam@acme.co as an admin”. The model calls your commands and sources as tools.
- **Page awareness.** “Summarize this page” or “what does this error mean?” The model can read the current page if you allow it.
- **Follow-ups.** The chat keeps context. <kbd>Esc</kbd> stops a response, and pressing it again goes back.

## How it works

When a chat starts, Qikbar builds a system prompt with the page title, the current path, and a compact list of your commands (id, title, section). It also gives the model these tools:

| Tool | What it does |
| --- | --- |
| `search` | Searches commands, routes and every [source](/docs/sources), and returns items with ids |
| `run` | Runs an item's primary action by id: navigates, runs code, or opens a view |
| `read_page` | Returns the visible text of the current page (turn off with `pageContext: false`) |
| Your tools | Anything in `tools` or in an [extension's `tools`](/docs/ai-tools) |

The model runs in a loop. It streams text, calls tools, reads the results and continues, for up to `maxSteps` steps. Each tool call shows up as a small chip in the chat ("Opening Billing", "Searching 'acme'"). Destructive actions and tools marked `confirm` ask the user before running.

## Options

```ts
createQikbar({
  ai: {
    provider: anthropic({ apiKey }),   // required
    name: 'Acme AI',                   // label in the UI, default "AI"
    system: 'Our product is called Acme. Be friendly.', // added to the system prompt
    fallback: true,                    // show "Ask AI" in results, default true
    tools: true,                       // let the model run commands, default true
    pageContext: true,                 // allow read_page, default true
    maxSteps: 6,                       // tool-calling steps per message
    suggestions: ['What can I do here?', 'Open my latest invoice'],
  },
})
```

Passing a provider directly (`ai: anthropic()`) uses the defaults.

## Choosing where the key lives

| Setup | Use when | Key exposure |
| --- | --- | --- |
| [`proxy()`](/docs/ai-server) + `createHandler` | Production apps paying for AI | Server only ✅ |
| [`byok()`](/docs/ai-providers#bring-your-own-key) | Users bring their own key | Each user's own browser |
| `anthropic({ apiKey })` in the browser | Prototypes, internal tools, local dev | Visible to anyone who opens devtools ⚠️ |
| [`browserAI()`](/docs/ai-providers#chrome-built-in-ai) | Free, private, on-device | None |

> [!WARNING]
> An API key in browser code is public. Anyone can copy it from devtools. Use a [server proxy](/docs/ai-server) for anything real.

## Using AI in your own commands

`ctx.ai` is available everywhere:

```ts
{
  title: 'Write release notes',
  icon: 'wand',
  run: (ctx) => detail({
    title: 'Release notes',
    markdown: ctx.ai!.stream(`Write release notes for these commits:\n${commits}`),
  }),
}
```

`ctx.ai.ask(prompt)` returns the whole answer as a promise. `ctx.ai.stream(prompt)` returns an async iterable you can pass straight to a detail view.

The [`aiActions()`](/docs/built-in-extensions#ai-actions) extension adds *Summarize This Page*, *Explain Selected Text* and *Translate*.

## Opening a chat from code

```ts
bar.ask('How do I invite my team?')                     // opens and sends
bar.open({ view: chat({ system: 'You are a SQL expert.' }) }) // empty chat with a custom prompt
```

## Privacy

Qikbar sends nothing anywhere unless you configure a provider. When a chat runs, the provider receives the conversation, the page title and path, and your command titles. It receives page text only if the model calls `read_page`, and search results only if it calls `search`. Turn tools off with `tools: false` for a plain chat.


---

# AI providers

> Claude, GPT, Gemini, local models, Chrome's on-device model, bring-your-own-key, or your own provider.

Source: https://qikbar.com/docs/ai-providers

Providers are tiny, dependency-free adapters that stream over `fetch`. They all implement the same interface, so you can switch models by changing one line.

```ts
import { anthropic, openai, gemini, openaiCompatible, ollama, browserAI, proxy, byok } from '@qikbar/qikbar'
```

## Anthropic (Claude)

```ts
anthropic({
  apiKey: '…',
  model: 'claude-opus-5-5',  // default
  effort: 'low',             // default: keeps the bar snappy. 'medium' | 'high' | 'xhigh' | 'max'
  maxTokens: 16000,
})
```

- Uses the Messages API with streaming and tool use.
- For the lowest latency and cost, use `model: 'claude-haiku-5-5'`.
- Server-side refusal fallbacks are on by default for models that support them. Turn them off with `fallbacks: false`.
- Thinking blocks are kept and replayed between tool calls automatically.
- In the browser, it sends the `anthropic-dangerous-direct-browser-access` header. Prefer a [proxy](/docs/ai-server) in production.

## OpenAI

```ts
openai({ apiKey: '…', model: 'gpt-6-luna' }) // default model
```

Uses Chat Completions with streaming tool calls.

## Any OpenAI-compatible API

Groq, OpenRouter, Together, Fireworks, Mistral, DeepSeek, xAI, Perplexity, vLLM, LM Studio and others work this way:

```ts
openaiCompatible({ baseURL: 'https://openrouter.ai/api/v1', apiKey: '…', model: 'anthropic/claude-sonnet-5-5' })
openaiCompatible({ baseURL: 'https://api.groq.com/openai/v1', apiKey: '…', model: '…' })
```

Set `tools: false` for models without function calling.

## Ollama (local)

```ts
ollama({ model: 'llama3.2' })                  // http://localhost:11434/v1
ollama({ model: 'qwen3', baseURL: 'http://gpu-box:11434/v1' })
```

## Google Gemini

```ts
gemini({ apiKey: '…', model: 'gemini-flash-latest' }) // default model
```

Uses `streamGenerateContent` with function calling. Thought signatures are preserved across tool calls.

## Chrome built-in AI

Chrome's on-device model, through the Prompt API. It's free and private, and needs no key. It doesn't support tools, so it's chat only.

```ts
if (await browserAI.isAvailable()) createQikbar({ ai: browserAI() })
```

## Proxy

Your own server endpoint, created with [`createHandler`](/docs/ai-server). This is the recommended setup for production.

```ts
proxy('/api/qikbar')
proxy({ url: '/api/qikbar', headers: async () => ({ authorization: `Bearer ${await getToken()}` }) })
```

## Bring your own key

Let each user paste their own key. It's stored only in their browser:

```ts
import { byok } from '@qikbar/qikbar'

createQikbar({
  ai: byok(),
  extensions: [byok.settings()], // adds "AI Settings" and "Remove AI API Key" commands
})
```

Users choose Anthropic, OpenAI, Gemini or any OpenAI-compatible endpoint, and optionally a model. Until a key is set, the chat explains how to add one. Limit the choices with `byok({ vendors: ['anthropic', 'openai'] })`, and pass the same options to `byok.settings()`.

## Write your own provider

A provider is an object with a `stream` method that yields events:

```ts
import type { AIProvider } from '@qikbar/qikbar'

const myProvider: AIProvider = {
  id: 'my-llm',
  tools: true, // set false if the model can't call tools
  async *stream({ messages, system, tools, signal }) {
    // messages: { role: 'user' | 'assistant' | 'tool', content, toolCalls?, toolCallId? }[]
    const res = await fetch('/my-llm', { method: 'POST', body: JSON.stringify({ messages, system, tools }), signal })
    let text = ''
    for await (const chunk of readChunks(res)) {
      text += chunk
      yield { type: 'text', text: chunk }
    }
    // If the model wants to call a tool:
    // yield { type: 'tool_call', call: { id, name, args } }
    yield { type: 'done', message: { role: 'assistant', content: text } }
  },
}
```

| Event | Meaning |
| --- | --- |
| `{ type: 'text', text }` | A chunk of the answer |
| `{ type: 'tool_call', call: { id, name, args } }` | The model wants to run a tool |
| `{ type: 'done', message }` | The final assistant message. Set `message.raw` to replay provider-specific data on the next turn. |
| `{ type: 'error', error }` | A message for the user (for example, refused or filtered) |

Throwing an error also works. It's shown in the chat.


---

# Server proxy

> Keep API keys on your server with one function. Works with Next.js, Hono, Express, Bun, Deno and Cloudflare Workers.

Source: https://qikbar.com/docs/ai-server

`createHandler` turns any provider into an endpoint that streams to the `proxy()` provider in the browser. Tools still run in the browser, where your commands live. The server only talks to the model.

```ts
// Browser
createQikbar({ ai: proxy('/api/qikbar') })
```

## Next.js (App Router)

```ts title="app/api/qikbar/route.ts"
import { createHandler, anthropic } from '@qikbar/qikbar/server'

export const POST = createHandler({
  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
})
```

## Hono

```ts
import { Hono } from 'hono'
import { createHandler, openai } from '@qikbar/qikbar/server'

const qikbar = createHandler({ provider: openai({ apiKey: process.env.OPENAI_API_KEY }) })
const app = new Hono()
app.post('/api/qikbar', (c) => qikbar(c.req.raw))
```

## Express / Node

```ts
import express from 'express'
import { createHandler, toNodeHandler, anthropic } from '@qikbar/qikbar/server'

const app = express()
app.post('/api/qikbar', express.json(), toNodeHandler(createHandler({ provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) })))
```

## Bun, Deno, Cloudflare Workers

```ts
const handler = createHandler({ provider: gemini({ apiKey: env.GEMINI_API_KEY }) })

Bun.serve({ fetch: (req) => (new URL(req.url).pathname === '/api/qikbar' ? handler(req) : new Response('Not found', { status: 404 })) })
export default { fetch: handler } // Workers
```

SvelteKit (`+server.ts`), Remix and React Router actions, Astro endpoints and Nuxt (`toWebRequest`) all use the same pattern: pass the Web `Request` to the handler.

## Options

| Option | Default | Description |
| --- | --- | --- |
| `provider` | — | **Required.** Any provider: `anthropic()`, `openai()`, `gemini()`, `ollama()`… |
| `system` | — | A server-side system prompt, prepended to the bar's prompt. |
| `allowClientSystem` | `true` | Accept the bar's system prompt (page title, command list). |
| `allowTools` | `true` | Forward tool definitions from the bar. |
| `authorize(request)` | — | Return `false` (401) or a `Response` to reject a request. |
| `maxMessages` | `50` | Reject longer conversations. |
| `maxChars` | `200000` | Reject larger payloads. |
| `maxTokens` | — | Cap output tokens. |
| `headers` | — | Extra response headers, for example for CORS. |

## Authentication and rate limiting

> [!CAUTION]
> Anyone who can reach the endpoint can spend your tokens. Always add `authorize` in production.

Check the session and rate-limit per user:

```ts
export const POST = createHandler({
  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  async authorize(request) {
    const session = await getSession(request)
    if (!session) return false
    const { success } = await ratelimit.limit(session.userId)
    return success || new Response('Slow down', { status: 429 })
  },
})
```

## Protocol

The endpoint receives `POST { messages, system?, tools?, maxTokens? }` and responds with newline-delimited JSON (`application/x-ndjson`). Each line is an AI event (`text`, `tool_call`, `done`, `error`). You can implement it in any language.


---

# AI tools

> Give the model functions it can call, with JSON-schema parameters and optional user confirmation.

Source: https://qikbar.com/docs/ai-tools

Out of the box, the model can `search` and `run` everything in your bar, and `read_page`. Add your own **tools** for operations that don't fit a command, or that need structured arguments.

```ts
import { createQikbar, defineTool } from '@qikbar/qikbar'

const inviteTeammate = defineTool<{ email: string; role: 'member' | 'admin' }>({
  name: 'invite_teammate',
  description: 'Invite someone to the current workspace by email.',
  parameters: {
    type: 'object',
    properties: {
      email: { type: 'string', description: 'Their email address' },
      role: { type: 'string', enum: ['member', 'admin'] },
    },
    required: ['email'],
  },
  confirm: (args) => `Invite ${args.email} as ${args.role ?? 'member'}?`,
  async run({ email, role = 'member' }, ctx) {
    await api.invite(email, role)
    return `Invited ${email} as ${role}.`
  },
})

createQikbar({ ai: proxy('/api/qikbar'), tools: [inviteTeammate] })
```

Now “invite sam@acme.co as an admin” works.

## Tool fields

| Field | Description |
| --- | --- |
| `name` | `snake_case`, unique. Extension tools are prefixed with `extension__`. |
| `description` | What the tool does and when to use it. The model reads this, so be specific. |
| `parameters` | A JSON Schema object for the arguments. |
| `confirm` | `true`, or a function that returns a question. The user must approve before the tool runs. |
| `run(args, ctx)` | Do the work. The return value (string or JSON) is sent back to the model. Throwing reports an error to the model, which can recover. |

## Tips

- **Return useful results.** Return ids, counts and what changed, not just “ok”. The model uses the result to answer.
- **Confirm anything destructive or external**: deleting, sending, paying.
- **Keep the list short.** A few precise tools work better than dozens of vague ones. Commands are already available through `run`.
- Results longer than 12,000 characters are truncated.

## Commands vs tools

| Use a command when… | Use a tool when… |
| --- | --- |
| Users would also run it from the bar | Only the AI needs it |
| It takes no input, or one or two [arguments](/docs/arguments) | It needs structured, typed parameters |
| It navigates or opens a view | It returns data for the model to reason about |

## Tools in extensions

Extensions can ship tools too. They get the extension's preferences and storage in `ctx`. See [Extensions](/docs/extensions#ai-tools).


---

# Building extensions

> Package commands, live sources, AI tools and user preferences into a reusable extension, inspired by Raycast.

Source: https://qikbar.com/docs/extensions

An **extension** is a portable bundle of functionality. If you've built a Raycast extension, this will feel familiar. The difference is that it's framework-agnostic and runs in any web app that uses Qikbar.

```ts
import { defineExtension, list, action } from '@qikbar/qikbar'

export default defineExtension({
  name: 'hacker-news',
  title: 'Hacker News',
  icon: 'https://news.ycombinator.com/favicon.ico',
  description: 'Browse top stories',
  commands: [
    {
      name: 'top',
      title: 'Top Stories',
      view: list({
        title: 'Top Stories',
        items: async ({ signal }) => {
          const ids: number[] = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json', { signal }).then((r) => r.json())
          const stories = await Promise.all(
            ids.slice(0, 30).map((id) => fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`, { signal }).then((r) => r.json())),
          )
          return stories.map((s) => ({
            title: s.title,
            subtitle: new URL(s.url ?? 'https://news.ycombinator.com').hostname,
            url: s.url ?? `https://news.ycombinator.com/item?id=${s.id}`,
            accessories: [{ text: `▲ ${s.score}` }, { text: `${s.descendants ?? 0} comments` }],
            actions: [action.open(`https://news.ycombinator.com/item?id=${s.id}`, { title: 'Open Comments', shortcut: 'mod+o' })],
          }))
        },
        filter: true,
      }),
    },
  ],
})
```

Install it:

```ts
import hackerNews from './hacker-news'

createQikbar({ extensions: [hackerNews] })
// or at runtime
const uninstall = bar.use(hackerNews)
```

## Anatomy

| Field | Description |
| --- | --- |
| `name` | **Required.** A unique id (kebab-case). Namespaces storage, ids and tool names. |
| `title` | **Required.** The display name. It's the default section and subtitle for its commands. |
| `icon`, `description`, `author`, `version` | Metadata. |
| `commands` | `ExtensionCommand[]`: same fields as [commands](/docs/commands) plus a required `name`. |
| `sources` | [Sources](/docs/sources) that contribute to the root search. |
| `tools` | [AI tools](/docs/ai-tools). Exposed to the model as `name__tool`. |
| `preferences` | Settings the extension needs (see below). |
| `setup(ctx)` | Called once when installed. Return a cleanup function. |

Command ids are `${extension.name}.${command.name}`, which keeps them stable for frecency and AI.

## Preferences

Declare what you need. Qikbar resolves values in this order: values passed at install time, then values the user entered, then defaults.

```ts
defineExtension({
  name: 'github',
  title: 'GitHub',
  preferences: [
    { name: 'token', title: 'Personal access token', type: 'password', required: true, description: 'Needs repo scope' },
    { name: 'org', title: 'Default organization', type: 'text', placeholder: 'acme' },
    { name: 'drafts', title: 'Include draft PRs', type: 'checkbox', default: false },
    { name: 'sort', title: 'Sort by', type: 'select', default: 'updated', options: [
      { title: 'Recently updated', value: 'updated' },
      { title: 'Most stars', value: 'stars' },
    ] },
  ],
  commands: [{ name: 'prs', title: 'My Pull Requests', view: (ctx) => prList(ctx.preferences.token) }],
})
```

> [!NOTE]
> **If a required preference is missing**, the first time the user runs a command, Qikbar shows a *Configure GitHub* form. It saves the values (namespaced in storage) and then runs the command. Users can change them later with the *Configure GitHub* action in the action panel (<kbd>⌘</kbd><kbd>.</kbd>).

Apps can also provide values when installing, so users never see the form:

```ts
createQikbar({ extensions: [[github, { token: session.githubToken, org: 'acme' }]] })
// or
bar.use(github, { token: session.githubToken })
```

Preference types: `text`, `password`, `number`, `checkbox` and `select`.

## Storage

`ctx.storage` is namespaced to the extension: `qikbar:ext:<name>:<key>`.

```ts
const favorites = ctx.storage.get<string[]>('favorites') ?? []
```

## AI tools

```ts
tools: [
  {
    name: 'create_issue',
    description: 'Create a GitHub issue in a repository',
    parameters: {
      type: 'object',
      properties: { repo: { type: 'string', description: 'owner/name' }, title: { type: 'string' }, body: { type: 'string' } },
      required: ['repo', 'title'],
    },
    confirm: (a) => `Create issue “${a.title}” in ${a.repo}?`,
    run: async (args, ctx) => {
      const issue = await gh(ctx.preferences.token).createIssue(args)
      return { url: issue.html_url, number: issue.number }
    },
  },
]
```

The model sees this tool as `github__create_issue`.

## Lifecycle with `setup`

```ts
setup({ bar, preferences, storage }) {
  const off = bar.on('open', () => prefetch())
  const timer = setInterval(sync, 60_000)
  return () => {
    off()
    clearInterval(timer)
  }
}
```

## Patterns

**Factory functions** make extensions configurable:

```ts
export function jira(options: { site: string }) {
  return defineExtension({ name: 'jira', title: 'Jira', commands: [/* uses options.site */] })
}
```

**Commands that run in place** return `false`:

```ts
{ name: 'refresh', title: 'Refresh Cache', run: async (ctx) => { await refresh(); ctx.toast('Refreshed'); return false } }
```

**Views that update** use `ctx.render`. See [Re-rendering](/docs/views#re-rendering).

## Compared with Raycast

| Raycast | Qikbar |
| --- | --- |
| `package.json` manifest | An `Extension` object |
| `mode: "view"` | `view: …` or `run` returning a view |
| `mode: "no-view"` | `run: …` |
| `<List>`, `<Grid>`, `<Detail>`, `<Form>` | `list()`, `grid()`, `detail()`, `form()` |
| `<ActionPanel>` / `<Action>` | `actions: Action[]` / `action.*` helpers |
| `useNavigation().push` | `ctx.push(view)` |
| `showToast`, `confirmAlert` | `ctx.toast`, `ctx.confirm` |
| `LocalStorage` | `ctx.storage` |
| `getPreferenceValues()` | `ctx.preferences` |
| `arguments` | `arguments` (inline in the search bar) |
| `AI.ask` | `ctx.ai.ask`, `ctx.ai.stream` |
| AI Extensions (`tools`) | `tools` |


---

# Built-in extensions

> Calculator, theme switcher, page tools, AI actions, keyboard shortcuts and bring-your-own-key settings.

Source: https://qikbar.com/docs/built-in-extensions

```ts
import { calculator, themeSwitcher, page, aiActions, shortcuts } from '@qikbar/qikbar/extensions'
import { byok } from '@qikbar/qikbar'

createQikbar({ extensions: [calculator(), themeSwitcher(), page(), aiActions(), shortcuts(), byok.settings()] })
```

Each one is a short, readable file. They're a good place to learn the API before you [build your own](/docs/extensions).

## Calculator

Type math straight into the bar and press <kbd>↵</kbd> to copy the result.

| Input | Result |
| --- | --- |
| `12 * (3 + 4)` | 84 |
| `2^10` | 1,024 |
| `15% of 80` | 12 |
| `200 + 10%` | 220 |
| `sqrt(2) * pi` | 4.4428829382 |
| `5 km in mi` | 3.1068559612 mi |
| `100 f to c` | 37.7777777778 °C |
| `1.5 gb in mb` | 1,536 MB |

It supports `+ - * / ^ %`, parentheses, implicit multiplication (`2pi`), `sqrt cbrt abs round floor ceil sin cos tan log ln exp min max`, and units for length, mass, data, time, volume and temperature. It uses a safe parser, never `eval`.

## Theme switcher

`themeSwitcher(options?)` adds *Toggle Dark Mode* (<kbd>⌘</kbd><kbd>⇧</kbd><kbd>L</kbd>), plus *Use Light/Dark/System Theme*. By default it toggles the `dark` class and `color-scheme` on `<html>` and saves the choice in `localStorage.theme`. Pass `set(mode)` to use your own theme logic:

```ts
themeSwitcher({ set: (mode) => setTheme(mode), shortcut: false })
```

## Page

`page({ headings? })` adds browser actions (*Go Back*, *Go Forward*, *Reload*, *Copy Page URL*, *Scroll to Top/Bottom*, *Print*, *Share*) and an **On This Page** source that searches headings with an `id`. That makes it handy for docs and long pages.

```ts
page({ headings: 'article h2[id], article h3[id]' })
```

## AI actions

Requires [`ai`](/docs/ai). `aiActions()` adds:

- **Summarize This Page**: streams a summary into a detail view
- **Explain Selected Text**: appears only when text is selected
- **Translate**: asks for a language with an [argument](/docs/arguments), then translates the selection or the page

## Shortcuts

`shortcuts()` adds a searchable **Keyboard Shortcuts** list of every command that has a `shortcut`, plus the bar's built-in keys.

## AI settings (bring your own key)

`byok.settings()` adds *AI Settings*, a form where users choose a provider and paste their key, and *Remove AI API Key*. Use it with `ai: byok()`. See [providers](/docs/ai-providers#bring-your-own-key).


---

# Example extensions

> Eleven complete, copy-pasteable extensions that show every part of the API.

Source: https://qikbar.com/docs/example-extensions

Each example is a single file you can copy into your app. All of them are live on the [extensions page](/extensions), where you can install them into this site's bar with one click.

| Extension | Shows | Data |
| --- | --- | --- |
| [Weather](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/weather.ts) | Sources that react to phrases (“weather in tokyo”), detail views with metadata, arguments, select preferences | Open-Meteo |
| [Currency](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/currency.ts) | Inline answers at the top of results (`position: 'top'`), async lists, arguments with defaults | Frankfurter |
| [npm](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/npm.ts) | Async lists with a detail panel, sectioned actions, preferences that change behavior | npm registry |
| [Wikipedia](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/wikipedia.ts) | Lazily loaded detail panels, `action.ask` to hand off to AI | Wikipedia |
| [Bookmarks](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/bookmarks.ts) | `ctx.storage`, forms, `ctx.render` after changes, destructive actions with confirmation, a source over local data | Browser storage |
| [GitHub](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/github.ts) | Optional password preferences, error states, empty views | GitHub API |
| [Hacker News](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/hacker-news.ts) | Several commands from one function, parallel fetching, extra actions | HN API |
| [Colors](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/colors.ts) | A pure source that parses the query, tinted icons | — |
| [Generators](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/generators.ts) | `run` commands with toasts, optional arguments | `crypto` |
| [Emoji](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/emoji.ts) | Grid views, `keepOpen` actions, `ctx.setQuery` | — |
| [World Clock](https://github.com/nearbycoder/qikbar-next/blob/main/apps/web/src/extensions/world-clock.ts) | Lists built at open time, phrase-triggered sources | `Intl` |

## Patterns worth copying

### Phrase-triggered sources

Weather, currency, colors and the world clock all use the same trick: a source that ignores every query except the ones it understands, and shows its answer at the top.

```ts
{
  id: 'currency-convert',
  position: 'top',
  async search({ query }) {
    const m = query.match(/^([\d.,]+)\s*([a-z]{3})\s+(?:to|in)\s+([a-z]{3})$/i)
    if (!m) return []
    // …fetch and return one item
  },
}
```

### Persist, then re-render

Bookmarks saves to `ctx.storage` and calls `ctx.render(browse(ctx))`, so the list updates without leaving the view.

### Lazy detail

Wikipedia sets `detail: () => summary(title)`. The summary is only fetched when the user selects that row, and then it's cached.


---

# Publishing extensions

> Share your extension on npm so any Qikbar app can install it.

Source: https://qikbar.com/docs/publishing-extensions

Extensions are plain ES modules, so publishing one is the same as publishing any small package.

## Package layout

```
qikbar-extension-linear/
├─ src/index.ts       # export default defineExtension({...}) or a factory
├─ package.json
└─ README.md          # screenshots, preferences, commands
```

```json
{
  "name": "qikbar-extension-linear",
  "version": "1.0.0",
  "type": "module",
  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
  "keywords": ["qikbar-extension", "qikbar", "linear"],
  "peerDependencies": { "@qikbar/qikbar": "^0.1.0" }
}
```

## Conventions

- **Name** it `qikbar-extension-<thing>` or `@scope/qikbar-<thing>`, and add the `qikbar-extension` keyword so the [extensions page](/extensions) can find it.
- List `@qikbar/qikbar` as a **peer dependency**. Only import types and helpers (`defineExtension`, `list`, `action`) from it.
- **Export a factory** when the extension takes options: `export function linear(options) { … }`.
- **Declare preferences** instead of reading environment variables. The app can pass values at install time.
- **Respect `ctx.signal`** in every `fetch`.
- **Never ship secrets.** API calls that need a private key belong behind the app's own endpoint.
- **Keep it small.** Avoid heavy dependencies. Qikbar's users care about bundle size.

## Testing

Extensions are data, so you can unit test commands directly:

```ts
import { expect, it, vi } from 'vitest'
import { linear } from '../src'

it('searches issues', async () => {
  const ext = linear({ team: 'ENG' })
  const source = ext.sources![0]!
  const items = await source.search({ query: 'login', signal: new AbortController().signal, ctx: fakeCtx({ preferences: { token: 'x' } }) })
  expect(items[0]!.title).toContain('login')
})
```

## Get listed

Open a pull request that adds your extension to `apps/web/src/data/extensions.ts` in the [Qikbar repo](https://github.com/nearbycoder/qikbar-next).


---

# Theming

> Presets, CSS variables, light and dark appearance, and matching your design system.

Source: https://qikbar.com/docs/theming

Qikbar's look is driven entirely by `--qb-*` CSS custom properties. You can choose a preset, override a few variables, or both. To try them live, open the [theme builder](/themes).

```ts
createQikbar({
  theme: {
    preset: 'linear',
    vars: { accent: '#e11d48', radius: '16px', font: 'inherit' },
    dark: { bg: 'rgba(12, 12, 14, .9)' },
  },
  appearance: 'auto',
})
```

## Presets

`light`, `dark`, `raycast`, `linear`, `vercel`, `github`, `nord`, `dracula`, `catppuccin`, `tokyo-night`, `rose-pine`, `solarized`, `midnight` and `paper`.

```ts
createQikbar({ theme: 'catppuccin' })
```

Most presets have a light and a dark variant. `dracula`, `tokyo-night` and `midnight` are always dark, and `paper` is always light.

## Appearance

| `appearance` | Behavior |
| --- | --- |
| `'auto'` (default) | Follows your app. It checks for a `dark` or `light` class on `<html>`/`<body>`, `data-theme`, `data-mode`, `data-color-scheme`, `data-bs-theme`, and `color-scheme`, then falls back to the OS setting. Changes are tracked live. |
| `'light'` / `'dark'` | Fixed |
| `() => 'light' \| 'dark'` | Your own logic, checked on each open |

## Variables

Pass these as camelCase keys in `vars`, `light` or `dark`. In CSS they're `--qb-kebab-case`.

| Key | CSS variable | Purpose |
| --- | --- | --- |
| `font` | `--qb-font` | Font family |
| `fontMono` | `--qb-font-mono` | Code font |
| `fontSize` | `--qb-font-size` | Base size (14px) |
| `bg` | `--qb-bg` | Dialog background (translucent by default) |
| `bgElevated` | `--qb-bg-elevated` | Action panel, toasts, confirm dialog |
| `fg` | `--qb-fg` | Primary text |
| `fgMuted` | `--qb-fg-muted` | Secondary text, icons |
| `fgSubtle` | `--qb-fg-subtle` | Section headings, placeholders, accessories |
| `border` | `--qb-border` | Hairlines |
| `selection` | `--qb-selection` | Selected row background |
| `selectionFg` | `--qb-selection-fg` | Selected row text |
| `hover` | `--qb-hover` | Hover background |
| `accent` | `--qb-accent` | Caret, focus rings, primary buttons, progress bar |
| `accentFg` | `--qb-accent-fg` | Text on the accent color |
| `highlight` | `--qb-highlight` | Matched characters |
| `overlay` | `--qb-overlay` | Backdrop color |
| `backdropBlur` | `--qb-backdrop-blur` | Dialog blur (20px) |
| `shadow` | `--qb-shadow` | Dialog shadow |
| `radius` | `--qb-radius` | Dialog radius |
| `radiusItem` | `--qb-radius-item` | Row radius |
| `width` | `--qb-width` | Dialog width (680px) |
| `listHeight` | `--qb-list-height` | Results height (380px) |
| `rowHeight` | `--qb-row-height` | Row height (42px) |
| `sectionHeight` | `--qb-section-height` | Section heading height |
| `inputHeight` | `--qb-input-height` | Search bar height |
| `inputFontSize` | `--qb-input-font-size` | Search text size |
| `top` | `--qb-top` | Distance from the top of the viewport (14vh) |
| `kbdBg` / `kbdFg` | `--qb-kbd-bg` / `--qb-kbd-fg` | Keyboard key chips |
| `danger` / `success` / `warning` | `--qb-danger` … | Status colors |

There's one more variable you can set in CSS: `--qb-z` (z-index, default `2147483000`).

## Use your design tokens

Variables accept any CSS value, including your own variables. Your theme and Qikbar's then stay in sync, with no JavaScript:

```ts
createQikbar({
  theme: {
    vars: {
      font: 'inherit',
      accent: 'var(--color-primary)',
      bg: 'var(--color-popover)',
      fg: 'var(--color-popover-foreground)',
      border: 'var(--color-border)',
      radius: 'var(--radius-lg)',
    },
  },
})
```

> [!TIP]
> This example maps Qikbar onto **shadcn/ui** tokens. Any design system with CSS variables works the same way.

## Pure CSS

You can also theme without any config:

```css
.qb-root {
  --qb-accent: hotpink;
  --qb-radius: 20px;
}
.qb-root[data-qb-appearance='dark'] {
  --qb-bg: #0b0b10;
}
```

## Change at runtime

```ts
bar.configure({ theme: 'nord' })
bar.configure({ theme: { vars: { accent: userColor } } })
```

## Export a theme

```ts
import { resolveThemeVars, themeToCss } from '@qikbar/qikbar/theme'

const { vars } = resolveThemeVars('dracula', 'dark')
console.log(themeToCss(vars))
```


---

# Styling

> Class names per slot, Tailwind, fully custom CSS, and Content Security Policy.

Source: https://qikbar.com/docs/styling

## Class names

Add classes to any part of the UI with `classNames`. This works well with Tailwind:

```ts
createQikbar({
  classNames: {
    dialog: 'ring-1 ring-black/5',
    input: 'font-medium',
    item: 'aria-selected:bg-indigo-50',
    footer: 'hidden sm:flex',
  },
})
```

Slots: `root`, `overlay`, `dialog`, `header`, `input`, `list`, `section`, `item`, `footer`, `actions`, `detail`, `form`, `grid`, `chat` and `toast`.

## Stable selectors

Every element has a `qb-` class you can target from your own CSS:

| Selector | Element |
| --- | --- |
| `.qb-root` | Wrapper. Has `data-qb-appearance`, `data-qb-theme`, `data-qb-state` and `data-qb-inline`. |
| `.qb-overlay` | Backdrop |
| `.qb-dialog` | The panel |
| `.qb-header`, `.qb-input`, `.qb-back`, `.qb-crumb`, `.qb-hint` | Search bar |
| `.qb-list`, `.qb-section`, `.qb-item[aria-selected=true]` | Results |
| `.qb-item-icon`, `.qb-item-title`, `.qb-item-subtitle`, `.qb-item-accessories`, `.qb-match` | Row parts |
| `.qb-footer`, `.qb-footer-btn`, `.qb-toast` | Footer |
| `.qb-actions`, `.qb-action` | Action panel |
| `.qb-detail`, `.qb-md`, `.qb-meta` | Detail views |
| `.qb-form`, `.qb-field-input` | Forms |
| `.qb-grid`, `.qb-cell` | Grids |
| `.qb-chat`, `.qb-msg-user`, `.qb-msg-ai`, `.qb-tool` | Chat |
| `.qb-hud` | Floating toast while closed |

Qikbar's base reset uses `:where()`, so it has zero specificity. A single class in your CSS overrides it.

```css
/* Show a left accent bar on the selected row */
.qb-root { --qb-indicator: 1; }

/* Bigger, bolder search */
.qb-root .qb-input { font-size: 20px; font-weight: 500; }
```

## Unstyled

Skip the default styles completely and write your own:

```ts
createQikbar({ unstyled: true })
```

You can start from the default stylesheet with `import '@qikbar/qikbar/styles.css'` (or copy it), then edit it.

## Content Security Policy

Qikbar injects a single `<style id="qikbar-styles">` tag. If your CSP blocks inline styles:

```ts
createQikbar({ nonce: window.__CSP_NONCE__ })
```

Or link the stylesheet yourself:

```ts
import '@qikbar/qikbar/styles.css'
createQikbar({ unstyled: true })
```

Qikbar also sets a few inline `style` properties for theme variables and virtualization. If you use `style-src-attr 'none'`, allow `'unsafe-hashes'` for them or theme with your own CSS only.

## RTL

```ts
createQikbar({ dir: 'rtl' })
```

## Mobile

Under 640px wide, the dialog sits at the top with a full-width layout. The footer hints and the detail and metadata panels are hidden, and forms switch to a single column.


---

# Inline mode

> Embed Qikbar directly in a page, as a search page, a launcher, or a live demo.

Source: https://qikbar.com/docs/inline-mode

By default Qikbar is a modal. Set `inline` to render it inside an element, always open:

```html
<div id="launcher"></div>
```

```ts
createQikbar({
  inline: '#launcher', // or an HTMLElement
  hotkey: false,       // or keep it: the hotkey focuses the input
  commands,
})
```

In inline mode:

- No overlay, no scroll lock and no focus trap. The bar sits in normal page flow and fills its container's width.
- The search input isn't focused automatically, so it doesn't steal focus on page load.
- <kbd>Esc</kbd> at the root clears the search and blurs. `close()` resets to the root view.
- `data-qikbar-open` triggers only open inline bars that target them by `namespace`: `data-qikbar-open="my-namespace"`.

The homepage demos on this site are inline bars.

## Several bars on one page

Give each instance its own `namespace`, so their storage and recents stay separate. Turn off global shortcuts on secondary bars:

```ts
createQikbar({ inline: '#demo', namespace: 'demo', hotkey: false, shortcuts: false, commands: demoCommands })
```

## In React

```tsx
<Qikbar inline commands={commands} className="h-[480px]" />
```


---

# React

> The Qikbar component, hooks for contextual commands, and a trigger button.

Source: https://qikbar.com/docs/react

```bash
npm install @qikbar/qikbar
```

## `<Qikbar>`

Render it once, near the root. Every [config option](/docs/api#config) is a prop:

```tsx
import { Qikbar } from '@qikbar/qikbar/react'
import { calculator, themeSwitcher } from '@qikbar/qikbar/extensions'

const extensions = [calculator(), themeSwitcher()]

export function App() {
  const navigate = useNavigate() // React Router
  return (
    <>
      <Qikbar
        routes={routes}
        commands={commands}
        extensions={extensions}
        navigate={(href) => navigate(href)}
        theme="linear"
      />
      <Routes>…</Routes>
    </>
  )
}
```

Props update the running instance, and only changed keys are applied. Callbacks (`navigate`, `onOpen`, `onClose`, `onRun`) can be inline functions. They're wrapped, so changing them never reconfigures the bar.

> [!IMPORTANT]
> Create extension instances **outside** the component, or memoize them, so they aren't reinstalled on every render.

`<Qikbar>` can also wrap your app and act as a provider, though hooks work without it:

```tsx
<Qikbar routes={routes}>
  <App />
</Qikbar>
```

## `useCommands`

Register commands while a component is mounted. This is ideal for page-specific actions:

```tsx
import { useCommands } from '@qikbar/qikbar/react'

function ProjectPage({ project }) {
  useCommands(
    [
      { title: `Rename ${project.name}`, icon: 'pencil', section: 'This project', run: () => openRename(project) },
      { title: 'Archive project', icon: 'trash', section: 'This project', run: () => archive(project.id) },
    ],
    [project.id, project.name],
  )
  return …
}
```

The second argument is a dependency list. If you omit it, the commands re-register whenever the array identity changes.

## `useSource`

```tsx
useSource({
  id: 'members',
  title: 'Members',
  search: ({ query, signal }) => api.members.search(query, { signal }).then((ms) => ms.map(toItem)),
}, [])
```

## `useExtension`

```tsx
useExtension(github, { token: session.githubToken }, [session.githubToken])
```

## `useQikbar`

```tsx
const { open, close, toggle, ask, isOpen, query, depth, loading, bar } = useQikbar()

<button onClick={() => open()}>Search</button>
<button onClick={() => ask('Summarize my week')}>Ask AI</button>
```

`open({ query, view })` can prefill the search or open straight into a view.

## `<QikbarTrigger>`

A search-box style button. Style it with `className`:

```tsx
<QikbarTrigger className="flex w-64 items-center gap-2 rounded-lg border px-3 py-1.5 text-sm text-muted-foreground" label="Search…" />
```

It renders the label and the platform-correct shortcut (⌘K or Ctrl K) after hydration, so server and client markup match.

## Inline

```tsx
<Qikbar inline className="mx-auto max-w-2xl" commands={commands} hotkey={false} />
```

## Server components

`@qikbar/qikbar/react` is marked `"use client"`. Import it from a client component.


---

# Next.js

> Add Qikbar to a Next.js App Router project, with client-side navigation and an AI route handler.

Source: https://qikbar.com/docs/nextjs

## 1. A client component

```tsx title="app/command-bar.tsx"
'use client'

import { useRouter } from 'next/navigation'
import { Qikbar } from '@qikbar/qikbar/react'
import { proxy } from '@qikbar/qikbar'
import { calculator, themeSwitcher, shortcuts } from '@qikbar/qikbar/extensions'

const extensions = [calculator(), themeSwitcher(), shortcuts()]

const routes = [
  { path: '/dashboard', title: 'Dashboard', icon: 'layout-dashboard' },
  { path: '/projects', title: 'Projects', icon: 'folder' },
  { path: '/settings', title: 'Settings', icon: 'settings' },
]

export function CommandBar() {
  const router = useRouter()
  return (
    <Qikbar
      routes={routes}
      extensions={extensions}
      navigate={(href, { newTab }) => (newTab ? window.open(href) : router.push(href))}
      sources={[
        {
          id: 'projects',
          title: 'Projects',
          search: async ({ query, signal }) => {
            const res = await fetch(`/api/projects/search?q=${encodeURIComponent(query)}`, { signal })
            return (await res.json()).map((p: { id: string; name: string }) => ({ title: p.name, icon: 'folder', href: `/projects/${p.id}` }))
          },
        },
      ]}
      ai={proxy('/api/qikbar')}
    />
  )
}
```

Define the `sources` array outside the component, or memoize it, if you don't want it re-registered on every render.

## 2. Mount it in the root layout

```tsx title="app/layout.tsx"
import { CommandBar } from './command-bar'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <CommandBar />
      </body>
    </html>
  )
}
```

## 3. Optional: an AI route

```ts title="app/api/qikbar/route.ts"
import { createHandler, anthropic } from '@qikbar/qikbar/server'
import { auth } from '@/auth'

export const POST = createHandler({
  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  authorize: async () => !!(await auth()),
})
```

## Page-specific commands

```tsx
'use client'
import { useCommands } from '@qikbar/qikbar/react'

export function InvoiceActions({ invoice }) {
  useCommands([{ title: `Download invoice ${invoice.number}`, icon: 'download', url: invoice.pdfUrl }], [invoice.id])
  return null
}
```

## Pages Router

Use `useRouter` from `next/router` and render `<CommandBar />` in `_app.tsx`. Everything else is the same.


---

# Vue & Nuxt

> Use Qikbar's vanilla API from Vue 3 or Nuxt, with Vue Router navigation and composables.

Source: https://qikbar.com/docs/vue

Qikbar doesn't need a Vue wrapper. Create it once and use it from anywhere.

```ts title="src/command-bar.ts"
import { createQikbar } from '@qikbar/qikbar'
import { calculator, themeSwitcher } from '@qikbar/qikbar/extensions'
import router from './router'

export const bar = createQikbar({
  navigate: (href) => router.push(href),
  routes: router.getRoutes()
    .filter((r) => r.meta?.title)
    .map((r) => ({ path: r.path, title: String(r.meta.title), icon: (r.meta.icon as string) ?? 'file' })),
  extensions: [calculator(), themeSwitcher()],
})
```

```ts title="src/main.ts"
import './command-bar'
```

## A composable for contextual commands

```ts title="src/composables/useCommands.ts"
import { onMounted, onUnmounted, watch, type Ref } from 'vue'
import type { Command } from '@qikbar/qikbar'
import { bar } from '../command-bar'

export function useCommands(commands: Ref<Command[]> | Command[]) {
  let off: (() => void) | undefined
  const register = (cmds: Command[]) => {
    off?.()
    off = bar.register(cmds)
  }
  if (Array.isArray(commands)) onMounted(() => register(commands))
  else watch(commands, register, { immediate: true })
  onUnmounted(() => off?.())
}
```

```vue
<script setup lang="ts">
import { computed } from 'vue'
import { useCommands } from '@/composables/useCommands'
const props = defineProps<{ project: { id: string; name: string } }>()
useCommands(computed(() => [{ title: `Archive ${props.project.name}`, icon: 'trash', run: () => archive(props.project.id) }]))
</script>
```

## Trigger button

```vue
<button data-qikbar-open>Search… <kbd>⌘K</kbd></button>
```

## Nuxt

Create a client-only plugin:

```ts title="plugins/qikbar.client.ts"
import { createQikbar } from '@qikbar/qikbar'

export default defineNuxtPlugin(() => {
  const bar = createQikbar({ navigate: (href) => navigateTo(href), autoIndex: true })
  return { provide: { qikbar: bar } }
})
```

Add an AI endpoint in `server/api/qikbar.post.ts`:

```ts
import { createHandler, anthropic } from '@qikbar/qikbar/server'
const handler = createHandler({ provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) })
export default defineEventHandler((event) => handler(toWebRequest(event)))
```


---

# Svelte & SvelteKit

> Create Qikbar in your root layout and navigate with goto.

Source: https://qikbar.com/docs/svelte

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { onMount } from 'svelte'
  import { goto } from '$app/navigation'
  import { createQikbar } from '@qikbar/qikbar'
  import { calculator } from '@qikbar/qikbar/extensions'

  let { children } = $props()

  onMount(() => {
    const bar = createQikbar({
      navigate: (href) => goto(href),
      routes: [
        { path: '/', title: 'Home', icon: 'home' },
        { path: '/settings', title: 'Settings', icon: 'settings' },
      ],
      extensions: [calculator()],
    })
    return () => bar.destroy()
  })
</script>

{@render children()}
```

SvelteKit intercepts anchor clicks, so the [default navigator](/docs/routing#the-default-navigator) already does client-side navigation. `navigate` is optional.

## Share the instance

```ts title="src/lib/qikbar.ts"
import { createQikbar } from '@qikbar/qikbar'
export const bar = typeof window !== 'undefined' ? createQikbar({ autoIndex: true }) : undefined
```

## Page-level commands

```svelte
<script lang="ts">
  import { bar } from '$lib/qikbar'
  let { data } = $props()
  $effect(() => bar?.register([{ title: `Edit ${data.post.title}`, icon: 'pencil', href: `/posts/${data.post.id}/edit` }]))
</script>
```

`$effect` cleans up automatically because `register` returns the unregister function.

## AI endpoint

```ts title="src/routes/api/qikbar/+server.ts"
import { createHandler, anthropic } from '@qikbar/qikbar/server'
import { ANTHROPIC_API_KEY } from '$env/static/private'

const handler = createHandler({ provider: anthropic({ apiKey: ANTHROPIC_API_KEY }) })
export const POST = ({ request }) => handler(request)
```


---

# Vanilla, Angular & more

> Use Qikbar with no framework, a script tag, Angular, Solid, htmx, Rails, Django or Laravel.

Source: https://qikbar.com/docs/vanilla

## No build step

```html
<script src="https://unpkg.com/@qikbar/qikbar/dist/qikbar.global.js"></script>
<script>
  const { createQikbar, extensions } = Qikbar
  createQikbar({
    autoIndex: true,
    extensions: [extensions.calculator(), extensions.themeSwitcher()],
    commands: [{ title: 'Contact support', icon: 'mail', url: 'mailto:help@acme.co' }],
  })
</script>
```

With `autoIndex`, server-rendered apps (Rails, Django, Laravel, Phoenix, WordPress, plain HTML) get a working command bar with no JavaScript config. Qikbar reads your navigation links and any element with `data-qikbar`:

```html
<nav aria-label="Account">
  <a href="/account">Account</a>
  <a href="/billing">Billing</a>
</nav>
<form action="/logout" method="post">
  <button data-qikbar="Log out" data-qikbar-icon="log-out">Log out</button>
</form>
```

## ES modules

```ts
import { createQikbar } from '@qikbar/qikbar'

const bar = createQikbar({ routes, commands })
document.querySelector('#search')!.addEventListener('click', () => bar.open())
```

## Angular

```ts title="command-bar.service.ts"
import { Injectable, OnDestroy, inject } from '@angular/core'
import { Router } from '@angular/router'
import { createQikbar, type QikbarInstance } from '@qikbar/qikbar'

@Injectable({ providedIn: 'root' })
export class CommandBarService implements OnDestroy {
  private router = inject(Router)
  readonly bar: QikbarInstance = createQikbar({
    navigate: (href) => this.router.navigateByUrl(href),
    routes: [{ path: '/dashboard', title: 'Dashboard', icon: 'home' }],
  })
  ngOnDestroy() {
    this.bar.destroy()
  }
}
```

Inject the service once in your root component. For SSR, create the bar only in the browser (`isPlatformBrowser`).

## Solid

```tsx
import { onCleanup, onMount } from 'solid-js'
import { useNavigate } from '@solidjs/router'
import { createQikbar } from '@qikbar/qikbar'

export function CommandBar() {
  const navigate = useNavigate()
  onMount(() => {
    const bar = createQikbar({ navigate: (href) => navigate(href), routes })
    onCleanup(() => bar.destroy())
  })
  return null
}
```

## htmx and Turbo

The default navigator clicks a temporary link, so `hx-boost` and Turbo Drive handle navigation for you. To trigger htmx requests from commands, use `htmx.ajax('GET', url, target)` in `run`.

## SSR safety

`createQikbar` is safe to call on the server. It does nothing until it runs in a browser. Still, prefer creating it in client-only code.


---

# Search your backend

> Connect sources to REST, Algolia, Supabase, GraphQL, tRPC and TanStack Query.

Source: https://qikbar.com/docs/recipes-backend-search

A [source](/docs/sources) is just an async function, so any backend works. Each recipe returns items with `href`, so selecting one navigates with your router.

## REST

```ts title="sources/projects.ts"
import type { Source } from '@qikbar/qikbar'

export const projects: Source = {
  id: 'projects',
  title: 'Projects',
  minQueryLength: 2,
  async search({ query, signal }) {
    const res = await fetch(`/api/projects?q=${encodeURIComponent(query)}&limit=8`, { signal })
    if (!res.ok) return []
    const rows: { id: string; name: string; owner: string; updatedAt: string }[] = await res.json()
    return rows.map((p) => ({
      id: `project:${p.id}`,
      title: p.name,
      subtitle: p.owner,
      icon: 'folder',
      href: `/projects/${p.id}`,
      accessories: [{ date: p.updatedAt }],
    }))
  },
}
```

> [!TIP]
> Always pass `signal` to `fetch`. Qikbar cancels the request when the user keeps typing, so stale responses never overwrite fresh ones.

## Algolia

Use the REST API directly (no SDK needed) and keep the **search-only** key in the client:

```ts title="sources/algolia.ts"
const APP_ID = 'YOUR_APP_ID'
const SEARCH_KEY = 'YOUR_SEARCH_ONLY_KEY'

export const docs: Source = {
  id: 'algolia',
  title: 'Docs',
  debounce: 80,
  async search({ query, signal }) {
    const res = await fetch(`https://${APP_ID}-dsn.algolia.net/1/indexes/docs/query`, {
      method: 'POST',
      signal,
      headers: { 'x-algolia-application-id': APP_ID, 'x-algolia-api-key': SEARCH_KEY },
      body: JSON.stringify({ query, hitsPerPage: 8 }),
    })
    const { hits } = await res.json()
    return hits.map((h: any) => ({ id: h.objectID, title: h.title, subtitle: h.section, icon: 'book', href: h.url }))
  },
}
```

## Supabase

```ts title="sources/customers.ts"
import { supabase } from '@/lib/supabase'

export const customers: Source = {
  id: 'customers',
  title: 'Customers',
  async search({ query, signal }) {
    const { data } = await supabase
      .from('customers')
      .select('id, name, email, plan')
      .or(`name.ilike.%${query}%,email.ilike.%${query}%`)
      .limit(8)
      .abortSignal(signal)
    return (data ?? []).map((c) => ({
      id: `customer:${c.id}`,
      title: c.name,
      subtitle: c.email,
      icon: 'user',
      href: `/customers/${c.id}`,
      accessories: [{ tag: { value: c.plan, color: c.plan === 'pro' ? 'purple' : 'gray' } }],
    }))
  },
}
```

> [!WARNING]
> Row-level security still applies. The source runs as the signed-in user, so they only see what they're allowed to see.

## GraphQL

```ts
async search({ query, signal }) {
  const res = await fetch('/graphql', {
    method: 'POST',
    signal,
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ query: 'query($q: String!) { searchIssues(q: $q, first: 8) { id title number } }', variables: { q: query } }),
  })
  const { data } = await res.json()
  return data.searchIssues.map((i) => ({ title: i.title, subtitle: `#${i.number}`, icon: 'circle', href: `/issues/${i.number}` }))
}
```

## tRPC

```ts
import { trpc } from '@/utils/trpc' // a vanilla tRPC client

export const issues: Source = {
  id: 'issues',
  title: 'Issues',
  search: async ({ query, signal }) =>
    (await trpc.issues.search.query({ q: query }, { signal })).map((i) => ({ title: i.title, href: `/issues/${i.id}` })),
}
```

## TanStack Query cache

Reuse your query cache so results that are already loaded appear instantly:

```ts
import { queryClient } from '@/lib/query'

export const teams: Source = {
  id: 'teams',
  title: 'Teams',
  search: ({ query, signal }) =>
    queryClient.fetchQuery({
      queryKey: ['teams', 'search', query],
      queryFn: () => api.teams.search(query, { signal }),
      staleTime: 30_000,
    }).then((teams) => teams.map((t) => ({ title: t.name, icon: 'users', href: `/teams/${t.slug}` }))),
}
```

## Search everything once, filter locally

For small datasets (fewer than about 5,000 rows), fetch everything once and let Qikbar rank it. Every keystroke after the first is instant:

```ts
let cache: Promise<Item[]> | undefined

export const people: Source = {
  id: 'people',
  title: 'People',
  filter: true,
  debounce: 0,
  search: () => (cache ??= fetch('/api/people').then((r) => r.json()).then((ps) => ps.map(toItem))),
}
```


---

# Workspace switcher

> Let users switch workspaces, accounts or projects from the bar, with the current one marked.

Source: https://qikbar.com/docs/recipes-switcher

A switcher is a [list view](/docs/views#list) whose items run a function. Mark the current item with an accessory, and give the command a shortcut so power users can switch without the mouse.

```ts title="command-bar/switcher.ts"
import { list, type Command } from '@qikbar/qikbar'

export function switcher(workspaces: Workspace[], current: Workspace, switchTo: (id: string) => Promise<void>): Command {
  return {
    title: 'Switch Workspace',
    subtitle: current.name,
    icon: 'layers',
    shortcut: 'mod+shift+o',
    keywords: ['team', 'org', 'account', 'change'],
    view: list({
      title: 'Workspaces',
      placeholder: 'Switch to…',
      items: workspaces.map((w) => ({
        id: w.id,
        title: w.name,
        subtitle: `${w.members} members`,
        icon: w.logoUrl ?? { icon: 'layers', color: w.color },
        accessories: w.id === current.id ? [{ tag: { value: 'Current', color: 'green' } }] : [{ text: w.plan }],
        async run(ctx) {
          if (w.id === current.id) return false
          const t = ctx.toast({ title: `Switching to ${w.name}…`, style: 'loading' })
          await switchTo(w.id)
          t.update({ title: `Now in ${w.name}`, style: 'success' })
        },
      })),
      actions: [{ title: 'Create Workspace', icon: 'plus', run: (ctx) => ctx.navigate('/workspaces/new') }],
    }),
  }
}
```

## Keep it fresh

Register the switcher wherever your workspace data lives, so it updates when the data changes:

```tsx title="React"
const { data: workspaces } = useWorkspaces()
const current = useCurrentWorkspace()
useCommands(workspaces ? [switcher(workspaces, current, switchWorkspace)] : [], [workspaces, current.id])
```

## Also searchable from the root

To let users type a workspace name straight from the root, add a source as well:

```ts
sources: [{
  id: 'workspaces',
  title: 'Workspaces',
  filter: true,
  debounce: 0,
  search: () => workspaces.map((w) => ({ title: `Switch to ${w.name}`, icon: 'layers', run: () => switchWorkspace(w.id) })),
}]
```


---

# Settings menus

> Build nested, toggleable settings that update in place with ctx.render.

Source: https://qikbar.com/docs/recipes-settings

Settings are a great fit for the bar: users can change a preference without visiting a settings page. The trick is `ctx.render`, which re-renders the current view after a change so the checkmarks stay accurate.

```ts title="command-bar/settings.ts"
import { grid, list, type ListView } from '@qikbar/qikbar'

function settingsView(): ListView {
  const s = store.settings
  const toggle = (key: keyof typeof s, label: string, icon: string) => ({
    id: key,
    title: label,
    icon,
    section: 'Preferences',
    accessories: [{ tag: s[key] ? { value: 'On', color: 'green' } : { value: 'Off', color: 'gray' } }],
    run: (ctx) => {
      store.update({ [key]: !s[key] })
      ctx.render(settingsView())   // re-render in place
      return false                  // keep the bar open
    },
  })

  return list({
    title: 'Settings',
    items: [
      toggle('compactMode', 'Compact mode', 'list'),
      toggle('emailDigest', 'Weekly email digest', 'mail'),
      toggle('sounds', 'Sounds', 'bell'),
      {
        title: 'Language',
        subtitle: s.language,
        icon: 'languages',
        section: 'Region',
        view: grid({
          title: 'Language',
          columns: 4,
          items: LANGUAGES.map((l) => ({
            title: l.name,
            subtitle: l.native,
            icon: l.flag, // an emoji
            run: (ctx) => {
              store.update({ language: l.code })
              ctx.pop()
              return false
            },
          })),
        }),
      },
    ],
  })
}

export const settingsCommand = { title: 'Settings', icon: 'settings', shortcut: 'mod+,', view: settingsView }
```

Because `ctx.render` keeps the query and selection, users can type “sound”, press <kbd>↵</kbd> repeatedly, and watch the toggle flip.

> [!TIP]
> `ctx.pop()` followed by `return false` goes back one level and keeps the bar open. Omit `return false` to close the bar after the change.


---

# Permissions & feature flags

> Show commands only to the right users, and roll out new commands behind flags.

Source: https://qikbar.com/docs/recipes-permissions

## `when` for simple checks

`when` runs every time the bar opens, so it always reflects the current state:

```ts
const commands: Command[] = [
  { title: 'Admin dashboard', icon: 'layout-dashboard', href: '/admin', when: () => session.user.role === 'admin' },
  { title: 'Try the new editor', icon: 'sparkles', run: openEditor, when: () => flags.isEnabled('new-editor') },
  { title: 'Upgrade to Pro', icon: 'zap', href: '/billing/upgrade', when: () => session.plan === 'free' },
]
```

## Register by role

For large sets of admin-only commands, register them as a group when the session loads:

```ts
let removeAdmin: (() => void) | undefined

auth.onChange((session) => {
  removeAdmin?.()
  removeAdmin = session?.isAdmin ? bar.register(adminCommands) : undefined
})
```

## Hide dangerous commands until searched

`searchOnly: true` keeps rare or destructive commands out of the default list. They only appear when the user types for them:

```ts
{ title: 'Delete workspace', icon: 'trash', searchOnly: true, actions: [deleteWorkspaceAction] }
```

## AI respects the same rules

The AI only sees commands that are currently registered and pass `when`. Hidden commands are invisible to the model too. For server-side authorization, always check permissions in your API as well. The bar is a UI, not a security boundary.

> [!CAUTION]
> Never rely on hiding a command for security. Anyone can call your API directly.


---

# Analytics

> Learn what users search for, what they run, and where the bar falls short.

Source: https://qikbar.com/docs/recipes-analytics

The bar is a direct line into what users want. Three hooks cover most needs.

```ts title="command-bar/analytics.ts"
import { createQikbar } from '@qikbar/qikbar'

const bar = createQikbar({
  // …
  onOpen: () => analytics.track('command_bar_opened', { path: location.pathname }),
  onRun: (item, action) =>
    analytics.track('command_run', {
      id: item.id,
      title: item.title,
      action: action.title,
      query: bar.query,
    }),
})

// Searches, debounced, so you learn what people look for.
let timer: ReturnType<typeof setTimeout>
bar.on('change', ({ open, query, depth }) => {
  clearTimeout(timer)
  if (!open || depth > 1 || query.length < 3) return
  timer = setTimeout(() => analytics.track('command_bar_search', { query }), 800)
})
```

## Find the gaps

Add a fallback that records searches that came up empty, and turns them into feedback:

```ts
fallbacks: [
  {
    title: 'Request “{query}”',
    icon: 'message',
    run: (ctx) => {
      analytics.track('command_bar_request', { query: ctx.query })
      ctx.toast({ title: 'Thanks! We’ll look into it.', style: 'success' })
    },
  },
]
```

> [!NOTE]
> Qikbar itself sends no telemetry. These hooks are yours to wire to PostHog, Segment, Plausible or anything else.


---

# In-app AI copilot

> Turn the bar into a copilot that understands your domain and takes real actions.

Source: https://qikbar.com/docs/recipes-copilot

This recipe builds a copilot for an invoicing app. Users can say “create an invoice for Acme for $1,200 due next Friday” or “which invoices are overdue?”.

## 1. The server route

```ts title="app/api/qikbar/route.ts"
import { createHandler, anthropic } from '@qikbar/qikbar/server'
import { auth } from '@/auth'

export const POST = createHandler({
  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, effort: 'medium' }),
  system: 'You help small businesses manage invoices in Ledgerly. Amounts are in the workspace currency.',
  maxTokens: 4000,
  authorize: async () => !!(await auth()),
})
```

## 2. Domain tools

Tools run in the browser with the user's session, calling your existing API:

```ts title="command-bar/tools.ts"
import { defineTool } from '@qikbar/qikbar'

export const findInvoices = defineTool<{ status?: 'draft' | 'sent' | 'paid' | 'overdue'; customer?: string }>({
  name: 'find_invoices',
  description: 'List invoices, optionally filtered by status or customer name. Returns number, customer, amount, due date and status.',
  parameters: {
    type: 'object',
    properties: {
      status: { type: 'string', enum: ['draft', 'sent', 'paid', 'overdue'] },
      customer: { type: 'string' },
    },
  },
  run: (args) => api.invoices.list(args),
})

export const createInvoice = defineTool<{ customer: string; amount: number; due: string; memo?: string }>({
  name: 'create_invoice',
  description: 'Create a draft invoice. `due` is an ISO date. Resolve relative dates like "next Friday" yourself.',
  parameters: {
    type: 'object',
    properties: {
      customer: { type: 'string' },
      amount: { type: 'number' },
      due: { type: 'string', description: 'YYYY-MM-DD' },
      memo: { type: 'string' },
    },
    required: ['customer', 'amount', 'due'],
  },
  confirm: (a) => `Create a $${a.amount} invoice for ${a.customer}, due ${a.due}?`,
  async run(args) {
    const invoice = await api.invoices.create(args)
    // The model links to it in its answer; the user stays in the chat.
    return { id: invoice.id, number: invoice.number, url: `/invoices/${invoice.id}` }
  },
})
```

## 3. Wire it up

```ts
createQikbar({
  routes,
  commands,
  sources: [customersSource, invoicesSource],
  tools: [findInvoices, createInvoice],
  ai: {
    provider: proxy('/api/qikbar'),
    name: 'Ledgerly AI',
    system: `Today is ${new Date().toDateString()}.`,
    suggestions: ['Which invoices are overdue?', 'Create an invoice for Acme', 'Go to reports'],
  },
})
```

## Why this works well

- **Your commands are already tools.** The model can navigate to any route or run any command through the built-in `run` tool. You only add tools for things that need parameters.
- **Your sources are already searchable.** “Open the Acme customer” works through the built-in `search` tool.
- **Writes are confirmed.** `confirm` asks the user before anything is created.
- **Keys stay server-side.** The browser only talks to your route.

> [!TIP]
> Return structured results from tools (ids, counts, URLs). The model uses them to write accurate answers and links.


---

# Testing

> Unit test commands and extensions, run DOM tests with happy-dom, and drive the bar in Playwright.

Source: https://qikbar.com/docs/recipes-testing

## Unit test commands

Commands and extensions are plain objects. Call them with a fake context:

```ts title="commands.test.ts"
import { describe, expect, it, vi } from 'vitest'
import type { Context } from '@qikbar/qikbar'
import { deployCommand } from './commands'

const fakeCtx = (overrides: Partial<Context> = {}): Context =>
  ({
    query: '',
    signal: new AbortController().signal,
    arguments: {},
    preferences: {},
    storage: { get: () => undefined, set: () => {}, remove: () => {} },
    toast: vi.fn(() => ({ update: vi.fn(), hide: vi.fn() })),
    confirm: vi.fn(async () => true),
    navigate: vi.fn(),
    ...overrides,
  }) as unknown as Context

it('deploys after confirmation', async () => {
  const ctx = fakeCtx()
  await deployCommand.run!(ctx)
  expect(ctx.confirm).toHaveBeenCalled()
  expect(ctx.toast).toHaveBeenCalledWith(expect.objectContaining({ style: 'loading' }))
})
```

## DOM tests

Qikbar runs in happy-dom and jsdom. Open it, type, press keys:

```ts title="command-bar.test.ts"
import { createQikbar } from '@qikbar/qikbar'

it('finds and runs a command', async () => {
  const run = vi.fn()
  const bar = createQikbar({ commands: [{ title: 'Export CSV', run }] })
  await bar.preload()
  bar.open({ query: 'export' })
  await new Promise((r) => setTimeout(r, 0))
  document.activeElement!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
  await new Promise((r) => setTimeout(r, 0))
  expect(run).toHaveBeenCalled()
  bar.destroy()
})
```

## Playwright

The markup is accessible, so role-based locators work:

```ts title="e2e/command-bar.spec.ts"
import { expect, test } from '@playwright/test'

test('navigate with the command bar', async ({ page }) => {
  await page.goto('/')
  await page.keyboard.press('ControlOrMeta+k')
  const search = page.getByRole('combobox', { name: 'Search' })
  await search.fill('billing')
  await expect(page.getByRole('option', { name: /Billing/ })).toBeVisible()
  await page.keyboard.press('Enter')
  await expect(page).toHaveURL(/\/settings\/billing/)
})
```

> [!TIP]
> Call `bar.preload()` in tests so the UI chunk loads before you interact. Otherwise the first `open()` waits for the lazy import.


---

# API reference

> Every configuration option, instance method, event and export.

Source: https://qikbar.com/docs/api

## `createQikbar(config)`

Creates a command bar and returns an [instance](#instance). It's safe to call during SSR, where it does nothing until it runs in a browser.

```ts
import { createQikbar } from '@qikbar/qikbar'
const bar = createQikbar({ /* config */ })
```

## Config

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `commands` | `Command[]` | `[]` | Root [commands](/docs/commands) |
| `routes` | `Route[]` | `[]` | `{ path, title, subtitle?, icon?, keywords?, section?, shortcut? }`. See [Routing](/docs/routing). |
| `sources` | `Source[]` | `[]` | Async [search providers](/docs/sources) |
| `extensions` | `(Extension \| [Extension, prefs])[]` | `[]` | [Extensions](/docs/extensions), optionally with preference values |
| `fallbacks` | `Item[]` | `[]` | Shown when the user has typed something. `{query}` is substituted. |
| `navigate` | `(href, { newTab }) => void` | Clicks a link | Your router |
| `hotkey` | `string \| string[] \| false` | `'mod+k'` | Toggles the bar |
| `actionsHotkey` | `string` | `'mod+.'` | Opens the action panel |
| `shortcuts` | `boolean` | `true` | Enables global command shortcuts |
| `placeholder` | `string` | `'Search for commands, pages and more…'` | Root input placeholder |
| `recents` | `boolean \| number` | `4` | How many recent items to show with an empty query |
| `autoIndex` | `boolean \| AutoIndexOptions` | `false` | Indexes page links and `[data-qikbar]` elements |
| `ai` | `AIProvider \| AIOptions` | — | See [AI](/docs/ai) |
| `tools` | `Tool[]` | `[]` | [AI tools](/docs/ai-tools) |
| `theme` | `ThemePresetName \| ThemeConfig` | — | See [Theming](/docs/theming) |
| `appearance` | `'auto' \| 'light' \| 'dark' \| () => …` | `'auto'` | Light or dark mode |
| `classNames` | `Partial<Record<Slot, string>>` | — | See [Styling](/docs/styling) |
| `unstyled` | `boolean` | `false` | Don't inject CSS |
| `nonce` | `string` | — | CSP nonce for the injected `<style>` |
| `inline` | `HTMLElement \| string` | — | Renders [inline](/docs/inline-mode) |
| `container` | `HTMLElement` | `document.body` | Where the modal mounts |
| `namespace` | `string` | `'qikbar'` | Storage namespace |
| `storage` | `StorageAdapter` | `localStorage` | `{ getItem, setItem, removeItem }` |
| `dir` | `'ltr' \| 'rtl'` | — | Text direction |
| `footer` | `string` | — | Footer text when idle |
| `branding` | `boolean` | `false` | Shows a small “qikbar” link in the footer |
| `onOpen` / `onClose` | `() => void` | — | Lifecycle callbacks |
| `onRun` | `(item, action) => void` | — | Called for every run, for example for analytics |

## Instance

| Member | Description |
| --- | --- |
| `open(options?)` | Open. Options: `{ query?, view? }`. |
| `close()` / `toggle()` | Close or toggle |
| `isOpen` | Whether the bar is open |
| `query` | Current search text |
| `setQuery(text)` | Set the search text |
| `push(view)` / `pop()` | Navigate views |
| `ask(prompt?)` | Open an AI chat, optionally sending a prompt |
| `register(commands)` | Add commands. Returns an unregister function. |
| `addSource(source)` | Add a source. Returns a remove function. |
| `use(extension, prefs?)` | Install an extension. Returns an uninstall function. |
| `configure(partial)` | Update any config option at runtime |
| `toast(options)` | Show a toast, or a HUD when closed |
| `commands()` | All root items currently registered |
| `ai` | The AI client (`ask`, `stream`), if configured |
| `on(event, handler)` | Subscribe to `open`, `close`, `change` or `run`. Returns an unsubscribe function. |
| `preload()` | Load the UI chunk now instead of waiting for idle time |
| `destroy()` | Remove listeners and DOM |

### Events

```ts
bar.on('open', () => analytics.track('command_bar_opened'))
bar.on('run', ({ item, action }) => analytics.track('command_run', { id: item.id, action: action.title }))
bar.on('change', ({ open, query, depth, loading }) => {})
```

## Exports

### `@qikbar/qikbar`

`createQikbar`, `list`, `grid`, `detail`, `form`, `chat`, `action`, `defineExtension`, `defineCommands`, `defineSource`, `defineTool`, `anthropic`, `openai`, `openaiCompatible`, `ollama`, `gemini`, `browserAI`, `proxy`, `byok`, `formatHotkey`, `parseHotkey`, `matchesHotkey`, `isMac`, `memoryStorage`, `version`, and all types.

### `@qikbar/qikbar/react`

`Qikbar`, `QikbarProvider`, `QikbarTrigger`, `useQikbar`, `useCommands`, `useSource`, `useExtension`.

### `@qikbar/qikbar/server`

`createHandler`, `toNodeHandler`, `anthropic`, `openai`, `openaiCompatible`, `ollama`, `gemini`.

### `@qikbar/qikbar/extensions`

`calculator`, `themeSwitcher`, `page`, `aiActions`, `shortcuts`, `shortcutLabel`, `evaluate`, `convert`, `formatNumber`.

### `@qikbar/qikbar/theme`

`presets`, `baseLight`, `baseDark`, `resolveThemeVars`, `themeToCss`, `cssVarName`, `css`.

### `@qikbar/qikbar/utils`

`rank`, `matchItem`, `fuzzyMatch`, `normalize`, `renderMarkdown`, `escapeHtml`, `icons`, `iconSvg`, `Frecency`, `SequenceMatcher`, `copyText`, `defaultNavigate`, and the storage and hotkey helpers. Use these to build your own UI on Qikbar's ranking.

## Types

All types are exported from `@qikbar/qikbar`: `QikbarConfig`, `QikbarInstance`, `Command`, `Item`, `Action`, `Accessory`, `Icon`, `View`, `ListView`, `GridView`, `DetailView`, `FormView`, `FormField`, `ChatView`, `Source`, `Extension`, `ExtensionCommand`, `Preference`, `Argument`, `Tool`, `Context`, `AIProvider`, `AIEvent`, `AIMessage`, `ThemeVars`, `ThemeConfig` and more.


---

# Performance

> How Qikbar stays fast, from boot to the 100,000th row.

Source: https://qikbar.com/docs/performance

## Boot: about 3.5 KB

`createQikbar()` returns a tiny shell (about 3.5 KB gzipped) that only listens for the hotkey and `data-qikbar-open` clicks. The UI, about 35 KB gzipped, loads in an `requestIdleCallback`, or immediately on first use, as a separate chunk. Calls you make before it loads (`register`, `use`, `on`…) are queued and replayed.

Nothing renders until the first open, and no styles are injected before then either.

To load the UI earlier, for example when the pointer hovers your search button:

```ts
button.addEventListener('pointerenter', () => bar.preload(), { once: true })
```

The script-tag build bundles everything (about 47 KB gzipped).

## Ranking: about 3 ms for 10,000 items

- Each item's searchable text is normalized once and cached in a `WeakMap`.
- A 27-bit character mask rejects non-matching items before any fuzzy work.
- The matcher is linear time per field. It does a greedy pass with boundary preference, plus a contiguous-substring check. There's no O(n·m) dynamic programming.
- Sorting is stable and limited to the top 300 results at the root.

## Rendering

- Lists over 150 rows are **virtualized**: only visible rows plus overscan are in the DOM. 100,000 rows scroll at 60fps.
- Rows are keyed and reused between keystrokes. Changing selection only flips two `aria-selected` attributes.
- Async updates are batched into one render per microtask. Streaming Markdown is throttled to animation frames.
- There's no framework runtime and no virtual DOM. The renderer updates the DOM directly.

## Network

- Sources are debounced (150 ms by default) and cancelled with `AbortSignal` when the query changes.
- Results from the previous query that still match stay visible while new ones load, so the list never flashes empty.
- AI providers stream over `fetch`. There's no SDK to download.

## Measuring

```ts
import { rank } from '@qikbar/qikbar/utils'

console.time('rank')
rank(items, 'set inv')
console.timeEnd('rank')
```


---

# Accessibility

> Keyboard support, screen readers, focus management and reduced motion.

Source: https://qikbar.com/docs/accessibility

Qikbar follows the WAI-ARIA **combobox with listbox popup** pattern:

- The search input has `role="combobox"`, `aria-expanded`, `aria-controls` and `aria-activedescendant`, which point at the selected option.
- Results are a `role="listbox"` with `role="option"` rows and `aria-selected`. Section headings are presentational.
- The modal is a `role="dialog"` with `aria-modal="true"` and a label.
- The action panel and confirmation dialogs have their own dialog roles and keyboard handling.
- Toasts are announced through `aria-live="polite"` regions.

## Focus

- Opening the bar saves the focused element. Closing it restores focus.
- While the modal is open, focus is trapped inside it.
- Inline mode never steals focus on load.

## Keyboard

Everything works without a mouse. See [Keyboard](/docs/keyboard). Letter shortcuts use physical keys, so they work on any keyboard layout.

## Motion

With `prefers-reduced-motion: reduce`, all animations are disabled, and the loading indicator moves more slowly.

## Color

The default themes meet WCAG AA contrast for body text. If you customize colors, check the contrast of `fg`, `fgMuted` and `selection` against `bg`.


---

# Migrating

> Move from cmdk, kbar, ninja-keys or the original Qikbar SaaS.

Source: https://qikbar.com/docs/migrating

## From cmdk

cmdk is a set of unstyled React primitives. You compose `<Command.Input>`, `<Command.List>` and `<Command.Item>` yourself. Qikbar is a complete command bar driven by data.

```tsx
// cmdk
<Command.Dialog open={open} onOpenChange={setOpen}>
  <Command.Input />
  <Command.List>
    <Command.Group heading="Pages">
      <Command.Item onSelect={() => router.push('/settings')}>Settings</Command.Item>
    </Command.Group>
  </Command.List>
</Command.Dialog>

// Qikbar
<Qikbar routes={[{ path: '/settings', title: 'Settings', section: 'Pages' }]} navigate={router.push} />
```

You no longer need open state, hotkey wiring, nested-page state or a filter function. If you need total control over markup, use `rank` from `@qikbar/qikbar/utils` with your own UI.

## From kbar

| kbar | Qikbar |
| --- | --- |
| `actions: [{ id, name, shortcut, keywords, section, perform }]` | `commands: [{ id, title, shortcut, keywords, section, run }]` |
| `parent: 'theme'` (nested actions) | `view: list({ items: [...] })` |
| `useRegisterActions` | `useCommands` |
| `KBarProvider` + `KBarPortal` + `KBarPositioner` + `KBarAnimator` + `KBarSearch` + `KBarResults` | `<Qikbar />` |
| `shortcut: ['g', 's']` | `shortcut: 'g s'` |

## From ninja-keys

`hotkeys` become `commands`. `handler` becomes `run`, `children` becomes `view: list(...)`, and `mdIcon` becomes `icon`.

## From the original Qikbar

The original Qikbar was a hosted SaaS with a drop-in script and dashboard-configured links. Qikbar is now a free open-source library:

- No account or project key. Install from npm or a CDN.
- Static links from the dashboard become `routes` or `commands`.
- Dynamic content from your API becomes `sources`.
- Client-side routing becomes `navigate`.
- The drop-in script still exists: use the [script tag](/docs/vanilla) with `autoIndex: true`.


---

# Troubleshooting

> Fixes for the most common problems.

Source: https://qikbar.com/docs/troubleshooting

### The hotkey doesn't open the bar

- Make sure `createQikbar` runs in the browser, not only on the server.
- Another library might handle <kbd>⌘</kbd><kbd>K</kbd> first and call `preventDefault()`. Try `hotkey: 'mod+shift+k'` to confirm, then remove the conflict.
- Single-key hotkeys like `/` are ignored while focus is in a text field. That's on purpose.

### Navigation reloads the page

Pass your router's function as `navigate`. Without it, Qikbar clicks a link, which only stays client-side if your router intercepts anchor clicks. See [Routing](/docs/routing#connect-your-router).

### Commands registered in React disappear or duplicate

`useCommands(commands, deps)` re-registers whenever `deps` change. With no `deps`, it re-registers whenever the array identity changes, which happens on every render if you create the array inline. Pass a dependency list, or `useMemo` the array.

### An extension asks for preferences every time

Required preferences must be non-empty. If you pass values when installing (`[ext, { token }]`), make sure they're defined when the bar is created. In React, pass a stable object.

### Styles look wrong

- Another stylesheet may target `.qb-*` classes or global elements with high specificity. Qikbar's reset has zero specificity, so a rule like `div { padding: 8px }` doesn't affect it, but `#app div` would.
- If your CSP blocks inline styles, pass `nonce`, or import `@qikbar/qikbar/styles.css` with `unstyled: true`.

### The bar is behind my modal or header

Raise `--qb-z` (default `2147483000`):

```css
.qb-root { --qb-z: 2147483646; }
```

### AI says “AI is not configured”

Pass `ai` to `createQikbar`. With `byok()`, the user needs to add a key in **AI Settings** first.

### AI requests fail with CORS errors

Anthropic, OpenAI and Gemini allow browser requests, but many OpenAI-compatible providers don't. Use a [server proxy](/docs/ai-server).

### The first open is slow

The UI chunk loads when the browser is idle. If the user opens the bar right after page load, it loads then. Call `bar.preload()` earlier, for example when the pointer enters your search button.


---

# FAQ

> Common questions about Qikbar.

Source: https://qikbar.com/docs/faq

### Is it really free?

Yes. Qikbar is MIT licensed with no paid tier, no telemetry and no account. AI features use your own provider and keys.

### Does it work without React?

Yes. The core has no dependencies and works in any framework or none. `@qikbar/qikbar/react` is an optional thin wrapper.

### Does it work with SSR?

Yes. `createQikbar` does nothing on the server. `@qikbar/qikbar/react` is marked `"use client"`.

### How do I open it from a button?

Add `data-qikbar-open` to any element, call `bar.open()`, or use `<QikbarTrigger>` in React.

### Can I prefill the search?

`bar.open({ query: 'invoices' })`, or `<button data-qikbar-open data-qikbar-query="invoices">`.

### Can I change the hotkey?

`hotkey: 'mod+p'`, `hotkey: ['mod+k', '/']`, or `hotkey: false`.

### How do I hide a command unless it's relevant?

Use `when: () => user.isAdmin` to hide it conditionally, or `searchOnly: true` to show it only when the user searches.

### Will AI cost me money?

Only if you configure a paid provider. You can use `byok()` so users bring their own key, `browserAI()` for Chrome's free on-device model, or `ollama()` for local models.

### Is my API key safe?

In the browser, no key is safe. Use [`createHandler`](/docs/ai-server) on your server with `proxy()` on the client for production.

### Can the AI do something destructive?

Only through the commands and tools you provide. Actions with `style: 'destructive'` and tools with `confirm` ask the user first. Turn off tool use entirely with `ai: { provider, tools: false }`.

### How do I test commands?

Commands are data. Call `command.run(fakeCtx)` in a unit test, or open the bar in a DOM test environment (happy-dom or jsdom) and dispatch key events. The Qikbar repo has examples.

### Can I use it in a browser extension or Electron?

Yes. It's plain DOM code with no framework or Node APIs.

### How do I contribute?

See [CONTRIBUTING.md](https://github.com/nearbycoder/qikbar-next/blob/main/CONTRIBUTING.md). Issues, extensions and themes are welcome.


---

# Changelog

> What's new in each release.

Source: https://qikbar.com/docs/changelog

## 0.1.0

The first open-source release, published as `@qikbar/qikbar`. Qikbar is now a free MIT-licensed library instead of a hosted SaaS.

**Library**

- `createQikbar` with commands, routes, sources, fallbacks, extensions and `autoIndex`
- Fuzzy ranking with word-boundary and acronym awareness, frecency and highlighting
- Views: list (with detail panel and virtualization), grid, detail (streaming Markdown), form, chat
- Actions: primary and secondary actions, the action panel, shortcuts, confirmations, toasts and HUD
- Inline arguments, global shortcuts and key sequences
- A lazy UI chunk: about 3.5 KB boots the shell
- 14 theme presets, CSS variables, class name slots, unstyled mode, automatic light and dark

**AI**

- Providers: `anthropic`, `openai`, `openaiCompatible`, `ollama`, `gemini`, `browserAI`, `proxy`, `byok`
- An agent loop where the model can `search`, `run` and `read_page`, plus your own tools
- `createHandler` and `toNodeHandler` in `@qikbar/qikbar/server`

**Ecosystem**

- `@qikbar/qikbar/react`: `<Qikbar>`, hooks and `<QikbarTrigger>`
- Built-in extensions: calculator, theme switcher, page tools, AI actions, shortcuts, AI settings
- Eleven example extensions, a theme builder, a playground, and docs for AI agents (`llms.txt`)