@bysivin/jumpbar

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:

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