Command palette
Expose a searchable set of application commands from a deliberate button or shortcut.
Components / Actions
Define an action once and present it consistently through palettes, context menus, sheets, toolbars, and opt-in shortcuts.
Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.
Aurora launch
ActiveChoose a project action
bunx --bun @getweini/cli@latest add action-surfaceImport the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.
<script setup lang="ts">
import { ref } from 'vue'
import ActionPalette from './components/ui/action-surface/ActionPalette.vue'
import ActionProvider from './components/ui/action-surface/ActionProvider.vue'
import Button from './components/ui/button/Button.vue'
const open = ref(false)
const actions = [
{ id: 'new', label: 'New project', keywords: ['create'], group: 'Projects' },
{ id: 'search', label: 'Search projects', group: 'Projects' },
]
const recent = ['search']
const messages = {
label: 'Commands',
searchLabel: 'Search commands',
clearSearch: 'Clear search',
empty: 'No commands found',
recent: 'Recent',
results: (count: number) => `${count} results`,
}
function run(id: string) {
console.log('Selected action:', id)
}
</script>
<template>
<ActionProvider :actions="actions" @select="run($event.action.id)">
<Button @click="open = true">Open commands</Button>
<ActionPalette v-model:open="open" hotkey="mod+k" :recent="recent" :messages="messages" />
</ActionProvider>
</template>The toolbar fills its container, shares space between actions, and moves lower-priority actions into More actions when space is tight. In the palette, Up and Down highlight commands while search keeps focus; Enter runs the highlighted command. The example also shows grouped commands, a recent section, a mod+k toggle, and an announced result count. Your app supplies execution, confirmation, and undo behavior. Shortcuts do not run while typing in editable controls.
Expose a searchable set of application commands from a deliberate button or shortcut.
Present the same action definitions through a toolbar and context menu while handling selections centrally.
The provider handles one selection event for all action surfaces.
<script setup lang="ts">
import { ref } from 'vue'
import ActionPalette from './components/ui/action-surface/ActionPalette.vue'
import ActionProvider from './components/ui/action-surface/ActionProvider.vue'
import Button from './components/ui/button/Button.vue'
const open = ref(false)
const actions = [
{ id: 'new', label: 'New project', keywords: ['create'] },
{ id: 'search', label: 'Search projects' },
]
const messages = {
label: 'Commands',
searchLabel: 'Search commands',
clearSearch: 'Clear search',
empty: 'No commands found',
}
function run(id: string) {
console.log('Selected action:', id)
}
</script>
<template>
<ActionProvider :actions="actions" @select="run($event.action.id)">
<Button @click="open = true">Open commands</Button>
<ActionPalette v-model:open="open" :messages="messages" />
</ActionProvider>
</template>The same definitions appear in a context menu and responsive toolbar. Higher-priority commands stay visible first; less frequent actions move into the toolbar overflow when space is limited.
<script setup lang="ts">
import ActionContextMenu from './components/ui/action-surface/ActionContextMenu.vue'
import ActionProvider from './components/ui/action-surface/ActionProvider.vue'
import ActionToolbar from './components/ui/action-surface/ActionToolbar.vue'
import Button from './components/ui/button/Button.vue'
const actions = [
{ id: 'open', label: 'Open', priority: 30, shortcut: '⌘O' },
{ id: 'share', label: 'Share', priority: 20 },
{ id: 'duplicate', label: 'Duplicate', priority: 10 },
{ id: 'rename', label: 'Rename', priority: 5 },
{ id: 'archive', label: 'Archive', destructive: true },
]
const messages = { label: 'Project actions', overflow: 'More actions' }
</script>
<template>
<ActionProvider :actions="actions" @select="$emit('action', $event.action.id)">
<ActionContextMenu label="Project actions">
<template #trigger><Button variant="outline">Project card</Button></template>
</ActionContextMenu>
<ActionToolbar :messages="messages" />
</ActionProvider>
</template>Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.
| Name | Type or signature | Default | What it does |
|---|---|---|---|
labelprop | string | Required | Visible or accessible name for this item. |
longPressDelayprop | number | undefined | Not set | Time a touch must be held before opening the menu. |
triggerslot | () => unknown | Required | Content for the trigger area of ActionContextMenu. |
itemslot | (props: { action: ActionDefinition; }) => unknown | Required | Content for the item area of ActionContextMenu. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
openmodel | boolean | undefined | Not set | Current open state. Use v-model:open to keep it in sync with your page. |
defaultOpenprop | boolean | undefined | false | Starting open state when the parent does not control open. |
hotkeyprop | string | undefined | Not set | Shortcut that toggles the palette from anywhere, e.g. `mod+k`. |
recentprop | readonly string[] | undefined | Not set | Action ids to list first while the search is empty. Needs `messages.recent`. |
messagesprop | ActionPaletteMessages | Required | Supply the text this component displays for its built-in actions and states. |
update:openevent | [open: boolean] | — | Requests a new open value from the parent. |
openChangeevent | [open: boolean] | — | Emitted after this value or state changes. |
itemslot | (props: { action: ActionDefinition; active: boolean; }) => unknown | Required | Content for the item area of ActionPalette. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
actionsprop | readonly ActionDefinition[] | Required | Provide the actions shown by this component. |
selectevent | [selection: ActionSelection] | — | Emitted when the user selects an item. |
shortcutConflictevent | [conflict: ActionShortcutConflict] | — | Emitted when shortcut conflict happens. |
defaultslot | (props: { actions: readonly ActionDefinition[]; select: (action: ActionDefinition, source: ActionSource) => void; }) => unknown | Required | Content shown inside ActionProvider. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
openmodel | boolean | undefined | Not set | Current open state. Use v-model:open to keep it in sync with your page. |
defaultOpenprop | boolean | undefined | false | Starting open state when the parent does not control open. |
messagesprop | ActionSheetMessages | Required | Supply the text this component displays for its built-in actions and states. |
sideprop | "top" | "right" | "bottom" | "left" | undefined | "bottom" | Choose the side on which this content appears. |
update:openevent | [open: boolean] | — | Requests a new open value from the parent. |
openChangeevent | [open: boolean] | — | Emitted after this value or state changes. |
triggerslot | () => unknown | Required | Content for the trigger area of ActionSheet. |
itemslot | (props: { action: ActionDefinition; }) => unknown | Required | Content for the item area of ActionSheet. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
actionIdprop | string | Required | Identify the action this item activates. |
shortcutprop | string | undefined | Not set | Keyboard shortcut displayed beside this action. |
sourceprop | ActionSource | undefined | "palette" | Data source used to populate this component. |
conflictevent | [conflict: ActionShortcutConflict] | — | Emitted when conflict happens. |
defaultslot | { action: ActionDefinition | undefined; } | Optional | Content shown inside ActionShortcut. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
messagesprop | ActionToolbarMessages | Required | Supply the text this component displays for its built-in actions and states. |
itemslot | (props: { action: ActionDefinition; overflow: boolean; }) => unknown | Required | Content for the item area of ActionToolbar. |
// packages/frameworks/vue/components/action-surface/types.ts
// ------- TYPES -------
export interface ActionDefinition {
id: string
label: string
description?: string
keywords?: readonly string[]
group?: string
shortcut?: string
disabled?: boolean
destructive?: boolean
priority?: number
}
export type ActionSource = 'palette' | 'context-menu' | 'sheet' | 'toolbar'
export interface ActionSelection {
action: ActionDefinition
source: ActionSource
}
export interface ActionPaletteMessages {
label: string
searchLabel: string
searchPlaceholder?: string
clearSearch: string
empty: string
/** Heading for the `recent` actions. Recent actions are only shown when this is set. */
recent?: string
/** Polite result count announced while searching, e.g. `(n) => `${n} results``. */
results?: (count: number) => string
}
export interface ActionSheetMessages {
label: string
}
export interface ActionToolbarMessages {
label: string
overflow: string
}
export interface ActionShortcutConflict {
shortcut: string
actionIds: readonly string[]
}
export interface ActionProviderProps {
actions: readonly ActionDefinition[]
}
export interface ActionPaletteProps {
open?: boolean
defaultOpen?: boolean
/** Shortcut that toggles the palette from anywhere, e.g. `mod+k`. */
hotkey?: string
/** Action ids to list first while the search is empty. Needs `messages.recent`. */
recent?: readonly string[]
messages: ActionPaletteMessages
}
export interface ActionContextMenuProps {
label: string
longPressDelay?: number
}
export interface ActionSheetProps {
open?: boolean
defaultOpen?: boolean
messages: ActionSheetMessages
side?: 'top' | 'right' | 'bottom' | 'left'
}
export interface ActionToolbarProps {
messages: ActionToolbarMessages
}
export interface ActionShortcutProps {
actionId: string
shortcut?: string
source?: ActionSource
}messages.results callback.