Defining Actions

Actions are the building blocks of your command palette. Each action defines what appears in the palette and what happens when it's triggered.

Basic Structure

Use the defineActions helper to create properly typed actions:

  
actions.ts

import { defineActions } from '$lib'; // Use 'svelte-command-palette' in your project

const actions = defineActions([
  {
    title: 'Search Users',
    subTitle: 'Find users by name or email',
    description: 'Opens the user search modal',
    icon: '👥',
    group: 'Users',
    keywords: ['find', 'lookup', 'people'],
    shortcut: 'S U',
    onRun: ({ action, storeProps, storeMethods }) => {
      openUserSearch();
      storeMethods.closePalette();
    },
    canActionRun: ({ storeProps }) => {
      // Only show if user is authenticated
      return storeProps.isAuthenticated;
    }
  }
]);

Action Properties

Property	Type	Required	Description
`title`	`string`	✓	Main display text for the action
`actionId`	`string \| number`		Unique identifier (auto-generated if not provided)
`subTitle`	`string`		Secondary text displayed below the title
`description`	`string`		Additional description text
`icon`	`string \| Snippet`		Emoji, image URL, or Svelte snippet
`group`	`string`		Group name for organizing actions
`keywords`	`string[]`		Additional search terms
`shortcut`	`string`		Keyboard shortcut (e.g., "G D", "$mod+S")
`onRun`	`function`		Callback when action is executed
`canActionRun`	`function`		Conditional check before execution

Callback Parameters

Both onRun and canActionRun receive an object with:

`action`

The current action object being executed

`storeProps`

Current state of the palette store (commands, results, calledActions, etc.)

`storeMethods`

Methods to control the palette (openPalette, closePalette, togglePalette)

Conditional Actions

Use canActionRun to conditionally enable or disable actions:

  
Conditional Actions

const actions = defineActions([
  {
    actionId: 'admin-panel',
    title: 'Open Admin Panel',
    icon: '🔐',
    canActionRun: ({ storeProps }) => {
      // Only admins can see this action
      return storeProps.user?.role === 'admin';
    },
    onRun: () => goto('/admin')
  },
  {
    actionId: 'dependent-action',
    title: 'Run Follow-up Task',
    subTitle: 'Requires "admin-panel" to be run first',
    canActionRun: ({ storeProps }) => {
      // Check if admin-panel was executed
      return storeProps.calledActions.includes('admin-panel');
    },
    onRun: () => runFollowUp()
  }
]);

💡

Tip: When canActionRun returns false, the action still appears in search results but won't execute. You can show a message using alert() before returning false.

Grouped Actions

Organize related actions using the group property:

  
Grouped Actions

const actions = defineActions([
  // Navigation group
  { title: 'Go to Dashboard', group: 'Navigation', icon: '🏠', ... },
  { title: 'Go to Settings', group: 'Navigation', icon: '⚙️', ... },
  
  // Actions group
  { title: 'Create New Project', group: 'Actions', icon: '➕', ... },
  { title: 'Export Data', group: 'Actions', icon: '📤', ... },
  
  // Ungrouped actions appear first
  { title: 'Search Everything', icon: '🔍', ... }
]);

Keyboard Shortcuts

Shortcuts use the tinykeys format:

"G D" Press G, then D (sequence)

"$mod+S" Cmd/Ctrl + S (modifier)

"Shift+Alt+P" Multiple modifiers

"ArrowUp" Special keys