Command Palette · juxt.ui

Installation #

With the Nuxt module, every component and composable is auto-imported — there is nothing to add. In a plain Vue project, import what you use:

import { JCommandPalette, useRecentCommands } from '@juxtui/ui'

Usage #

<JCommandPalette v-model:open="open" :groups="groups" @select="run" />

⌘K on macOS and Ctrl K elsewhere toggles the palette from anywhere on the page. Change it with hotkey, or pass false.

Built-in ranking orders results the way people expect: exact, then prefix, then word start, then substring, then letters in order — and the matched characters are highlighted.

Every keystroke puts the best match under the cursor, so Enter almost always does what you meant.

Variants & examples #

Async search#

Set :filter="false", watch v-model:search, and toggle loading while you fetch.

<script setup lang="ts">
import type { CommandGroup, CommandItem } from '@juxtui/ui'
import { Package } from '@lucide/vue'

const open = ref(false)
const search = ref('')
const loading = ref(false)
const results = ref<CommandItem[]>([])

const registry = ['vue', 'nuxt', 'vite', 'vitest', 'vue-router', 'pinia', 'unhead', 'nitropack', 'ofetch', 'h3']

// Pretend to search a package registry.
let timer: ReturnType<typeof setTimeout> | undefined
watch(search, (query) => {
  clearTimeout(timer)
  loading.value = true
  timer = setTimeout(() => {
    results.value = registry
      .filter(name => name.includes(query.trim().toLowerCase()))
      .map(name => ({ id: name, label: name, icon: Package }))
    loading.value = false
  }, 450)
}, { immediate: true })

const groups = computed<CommandGroup[]>(() => [{ id: 'packages', label: 'Packages', items: results.value }])
</script>

<template>
  <JButton variant="outline" @click="open = true">Search packages</JButton>
  <JCommandPalette
    v-model:open="open"
    v-model:search="search"
    :groups="groups"
    :filter="false"
    :loading="loading"
    :hotkey="false"
    placeholder="Search packages…"
  />
</template>

Recent items#

useRecentCommands remembers what was used, per browser. Pass the result to recent.

<script setup lang="ts">
import type { CommandGroup, CommandItem } from '@juxtui/ui'
import { FileText } from '@lucide/vue'

const open = ref(false)
const recents = useRecentCommands({ key: 'juxt-example:recent' })

const files: CommandItem[] = ['README.md', 'nuxt.config.ts', 'app.vue', 'package.json', 'tokens.css'].map(name => ({
  id: name,
  label: name,
  icon: FileText,
}))

const groups: CommandGroup[] = [{ id: 'files', label: 'Files', items: files }]
const recent = computed(() => recents.resolve(files))
</script>

<template>
  <JButton variant="outline" @click="open = true">Open file…</JButton>
  <JCommandPalette
    v-model:open="open"
    :groups="groups"
    :recent="recent"
    :hotkey="false"
    placeholder="Search files…"
    @select="item => recents.record(item.id)"
  />
</template>

API #

Props

Prop	Type	Default	Description
open	`boolean`	`false`	Bound with `v-model:open`.
groups	`CommandGroup[]`	—	`{ id, label?, items: CommandItem[] }`.
search	`string`	`''`	Bound with `v-model:search`. Cleared on open.
recent	`CommandItem[]`	—	Shown as a “Recent” group while the search is empty.
placeholder	`string`	`'Type a command or search…'`	Search placeholder.
loading	`boolean`	`false`	Shows a progress hairline, and “Searching…” when empty.
filter	`boolean`	`true`	Built-in ranking. Turn off to filter yourself.
hotkey	`string \| false`	`'mod+k'`	Global shortcut that toggles the palette.
label	`string`	`'Command palette'`	Accessible name.
emptyText	`string`	`'No results'`	Empty state title.

Events

Event	Payload	Description
select	`CommandItem`	An item was chosen. The palette closes.
update:open	`boolean`	Open state changed.
update:search	`string`	Search text changed.

Slots

Slot	Props	Description
item	`{ item, active }`	Custom row content.
empty	`{ search }`	Custom empty state.
footer	—	Replace the keyboard hints.

CommandItem

Prop	Type	Default	Description
id	`string`	—	Unique within its group.
label	`string`	—	Main text; matched and highlighted.
description	`string`	—	Muted text after the label; also searchable.
icon	`Component`	—	Rendered at 16px.
shortcut	`string`	—	Display-only shortcut, e.g. `mod+shift+p`.
keywords	`string[]`	—	Extra terms that should find this item.
disabled	`boolean`	—	Shown but not selectable.
onSelect	`(item) => void`	—	Called before `select` is emitted.

useRecentCommands(options?)

Functions

Method	Signature	Description
record(id)	`(id: string) => void`	Remember an item as most recent.
resolve(items)	`(items: T[]) => T[]`	Map remembered ids back to items, most recent first.
clear()	`() => void`	Forget everything.
options	`{ key?, limit? }`	localStorage key (default `juxt:recent-commands`) and how many to keep (default 5).

Accessibility #

A modal dialog containing a combobox: the input owns aria-activedescendant, results are options in groups.
The number of results is announced politely as you type.
Focus is trapped while open and returns to where it was when the palette closes.
Hovering only changes the active row when the pointer actually moves, so keyboard navigation under a resting cursor is never hijacked.

Keyboard #

Key	Action
`⌘K`	Toggle the palette (Ctrl K on Windows and Linux).
`↓↑`	Move through results, wrapping around.
`CtrlN`	Next result.
`CtrlP`	Previous result.
`PageUpPageDown`	Move five results at a time.
`Enter`	Run the active item.
`Esc`	Close and return focus.