Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

Action Surface

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.

Interactive showcase

Aurora launch

Active

Choose a project action

Project commands

Install

Run in your project
bunx --bun @getweini/cli@latest add action-surface

Start with this example

Import 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.

Commands

Recent

Projects

Vue
<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.

When to use it

Command palette

Expose a searchable set of application commands from a deliberate button or shortcut.

Shared action catalog

Present the same action definitions through a toolbar and context menu while handling selections centrally.

More examples

Searchable commands

The provider handles one selection event for all action surfaces.

Searchable commands
<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>

Context and toolbar actions

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.

Context and toolbar actions
<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>

Complete API

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.

ActionContextMenu

Complete API for ActionContextMenu
NameType or signatureDefaultWhat it does
labelpropstringRequiredVisible or accessible name for this item.
longPressDelaypropnumber | undefinedNot setTime a touch must be held before opening the menu.
triggerslot() => unknownRequiredContent for the trigger area of ActionContextMenu.
itemslot(props: { action: ActionDefinition; }) => unknownRequiredContent for the item area of ActionContextMenu.

ActionPalette

Complete API for ActionPalette
NameType or signatureDefaultWhat it does
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedfalseStarting open state when the parent does not control open.
hotkeypropstring | undefinedNot setShortcut that toggles the palette from anywhere, e.g. `mod+k`.
recentpropreadonly string[] | undefinedNot setAction ids to list first while the search is empty. Needs `messages.recent`.
messagespropActionPaletteMessagesRequiredSupply 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; }) => unknownRequiredContent for the item area of ActionPalette.

ActionProvider

Complete API for ActionProvider
NameType or signatureDefaultWhat it does
actionspropreadonly ActionDefinition[]RequiredProvide 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; }) => unknownRequiredContent shown inside ActionProvider.

ActionSheet

Complete API for ActionSheet
NameType or signatureDefaultWhat it does
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedfalseStarting open state when the parent does not control open.
messagespropActionSheetMessagesRequiredSupply 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() => unknownRequiredContent for the trigger area of ActionSheet.
itemslot(props: { action: ActionDefinition; }) => unknownRequiredContent for the item area of ActionSheet.

ActionShortcut

Complete API for ActionShortcut
NameType or signatureDefaultWhat it does
actionIdpropstringRequiredIdentify the action this item activates.
shortcutpropstring | undefinedNot setKeyboard shortcut displayed beside this action.
sourcepropActionSource | undefined"palette"Data source used to populate this component.
conflictevent[conflict: ActionShortcutConflict]—Emitted when conflict happens.
defaultslot{ action: ActionDefinition | undefined; }OptionalContent shown inside ActionShortcut.

ActionToolbar

Complete API for ActionToolbar
NameType or signatureDefaultWhat it does
messagespropActionToolbarMessagesRequiredSupply the text this component displays for its built-in actions and states.
itemslot(props: { action: ActionDefinition; overflow: boolean; }) => unknownRequiredContent for the item area of ActionToolbar.
Public type definitions
Public types
// 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
}

Implementation notes

  • ActionProvider emits an action and its source; the application performs authorization and side effects.
  • ActionToolbar moves lower-priority actions into an overflow menu when space is limited.

Accessibility and localization

  • Supply the required message objects in the application’s language.
  • Shortcuts are registered only through ActionShortcut; a displayed shortcut is merely a hint.
  • The palette hotkey ignores editable controls and IME composition. The result count uses the localized messages.results callback.

Source contract and editing guidance