jumpbar

A lightweight command palette for Vue 3. The ranking core is plain JavaScript with no dependencies (about 1 KB gzipped); the shell is a native <dialog> rendered with Tailwind utilities (about 5 KB gzipped with the core).

• Fuzzy matching with accent folding, sections, nested pages and prefixes
• Frecency so the things you use rise to the top
• Sync commands sources ranked on every keystroke, async search sources with per-source debounce, minimum query length and AbortSignal
• Keyboard and pointer handling, open/close motion, skeleton rows while remote results load, RTL and IME aware

Install

pnpm add @bysivin/jumpbar

The package ships compiled ES modules with TypeScript declarations; Vue stays external. vue 3.4 or newer is needed for the shell.

Any framework

The ranking core has no framework dependency. React, Svelte, Solid or plain JavaScript projects import it from @bysivin/jumpbar/core and render their own list:

import { rank, groupBySection, createFrecency } from '@bysivin/jumpbar/core';

const ranked = rank(items, { text: query, scopes: ['conversation'] });
const sections = groupBySection(ranked);

The CommandBar shell and useCommandBar state are Vue 3.

Styling

The shell is built from Tailwind utilities and reads every colour from a small set of semantic tokens, so it adapts to any design system.

1. Add the preset and scan the package so its classes are generated:

   // tailwind.config.js
   module.exports = {
     presets: [require('@bysivin/jumpbar/tailwind')],
     content: ['./node_modules/@bysivin/jumpbar/dist/*.js'],
   };

   The preset registers the jumpbar-* colours as CSS variables and the open and close keyframes.

2. Theme it. Either import the neutral defaults and override what you like (dark values apply under a dark class on the root element):

   import '@bysivin/jumpbar/theme.css';

   :root {
     --jumpbar-primary: #2781f6;
   }

   or skip the import and map the tokens onto your existing Tailwind colours, which also carries your dark mode along:

   theme: {
     extend: {
       colors: {
         jumpbar: {
           background: colors.surface,
           foreground: colors.text,
           primary: colors.brand,
         },
       },
     },
   },

   | Token | Used for | | ------------------- | ------------------------------------------------- | | background | Panel | | foreground | Titles and input text | | muted-foreground | Subtitles, section labels, breadcrumbs, badges | | subtle-foreground | Placeholder, icons, hints, chevrons | | muted | Active row, chips, avatar fallback, skeleton rows | | subtle | Key caps, lighter skeleton bar | | border | Dividers and key cap outline | | ring | Panel outline | | primary | Active row marker, page chip text | | primary-soft | Page chip background | | overlay | Backdrop | | online busy offline | Presence dot |

3. Provide the icon classes i-lucide-search, i-lucide-loader-circle and i-lucide-chevron-right (for example through @egoist/tailwindcss-icons with the Lucide set). Items bring their own icon class.

Usage

<script setup>
import { CommandBar, createFrecency, useCommandBar } from '@bysivin/jumpbar';

const bar = useCommandBar();

bar.configure({
  prefixes: ['@', '#'],
  context: () => ({ scopes: ['conversation'] }),
  frecency: createFrecency({ storage: localStorage, key: 'palette-usage' }),
  onSelect: item => track(item),
  onClose: () => {},
  onError: (error, source) => report(error),
  limit: 100,
});

bar.register({
  id: 'navigation',
  commands: () => [
    {
      id: 'inbox',
      title: 'Go to inbox',
      section: 'Navigation',
      icon: 'i-lucide-inbox',
      shortcut: ['⌥', 'I'],
      run: () => router.push('/inbox'),
    },
  ],
});

bar.register({
  id: 'contacts',
  minQuery: 3,
  debounce: 300,
  when: ({ page }) => !page,
  search: async ({ text, signal }) => {
    const contacts = await api.search(text, { signal });
    return contacts.map(contact => ({
      id: `contact-${contact.id}`,
      title: contact.name,
      subtitle: contact.email,
      section: 'Contacts',
      avatar: { name: contact.name, src: contact.thumbnail },
      run: () => router.push(`/contacts/${contact.id}`),
    }));
  },
});
</script>

<template>
  <CommandBar
    placeholder="Search or jump to"
    empty-text="No matches"
    :hints="[
      { keys: ['↑', '↓'], label: 'navigate' },
      { keys: ['↵'], label: 'select' },
      { keys: ['esc'], label: 'close' },
    ]"
  />
</template>

Bind the global shortcut yourself and call bar.toggle(). bar.open({ page, query }) opens straight into a page, for example a snooze picker.

CommandBar props: placeholder, emptyText, scopeLabel (a chip before the input, for example the selected record), hints and dir (ltr or rtl).

Items

Sources return plain objects:

| Field | Meaning | | ---------------- | ------------------------------------------------------------------------ | | id | Unique across all sources. Frecency and dedupe key on it. | | title | Row label. Children are matched through parentTitle title too. | | subtitle | Muted text after the title. Takes only the space left after the breadcrumb and title. | | section | Group header. Groups keep the order of their first item. | | icon | CSS class rendered as the leading glyph. | | avatar | { name, src, status } instead of the icon, initials as fallback; status is online, busy or offline. | | badge | Short trailing text. | | shortcut | Trailing key labels, for example ['⌥', 'E']. | | keywords | Extra words the matcher sees (word-start matches only). | | scopes | Ranks first when one matches context.scopes. | | prefix | Typing this character first lists only items carrying it. | | weight | Static boost between 0 and 1. | | place | first or last: sorts around every other match, in declared order. | | searchFromRoot | false keeps a child out of root searches (prefix and page only). | | page | Selecting opens a page listing the items whose parent is its id. | | placeholder | Input placeholder while that page is open. | | parent | Id of the page this item lives under. | | run | Called with the context as the bar starts closing; the dialog leaves the top layer about 150 ms later. Rows without it are inert. |

Sources

bar.register({
  id: 'conversations',
  minQuery: 2,
  debounce: 300,
  when: ({ page }) => !page,
  commands: request => [],
  search: async request => [],
});

commands runs on every keystroke and is ranked. search runs after the debounce with an AbortSignal; its results keep their own order, append after the ranked commands at the root, and replace the static children on a page. The request carries query, text, prefix, page, context and, for search, matches (how many commands matched locally) and signal. register returns a function that removes the source again. A searcher that throws has its rows dropped and onError(error, source) called; the default rethrows. Text queries show at most limit ranked commands (default 50).

Ranking

Titles match by exact, prefix, word start, every-word-starts-a-word, then scattered characters. Subtitles and keywords only match on word starts, so a long description never floods the list. Items in context.scopes get a boost, recently used items another, weight a small static one. place: 'first' and place: 'last' sit outside the scoring entirely.

Keyboard

↑ ↓ move, Enter selects, Esc closes, Backspace on an empty query goes back one page. Hover only changes the selection when the pointer really moves, so arrow keys keep working under a resting cursor.

Development

pnpm install
pnpm test
pnpm build