Svelte Command Palette

Increase your productivity exponentially. 🚀🚀

A beautiful, accessible, and fully customizable command palette for Svelte 5 applications.

~2.1KB Minified | ~700B Gzipped

Demo

✨ Features

• 🔍 Fuzzy Search - Powered by Fuse.js for intelligent searching
• ⌨️ Keyboard Shortcuts - Define custom shortcuts for any action
• 🎨 Fully Customizable - Style every element with classes or inline styles
• 📱 Mobile Responsive - Bottom sheet UI on mobile devices
• ♿ Accessible - Full ARIA support and keyboard navigation
• 🎯 Conditional Actions - Run actions based on current state
• 📦 Action Grouping - Organize actions into logical groups
• 🔔 Event Callbacks - onOpen, onClose, onActionSelect hooks
• 🎭 Custom Empty State - Render custom UI when no results found
• 🌙 Dark Mode Ready - Built-in dark mode support
• 📝 TypeScript - Full type definitions included

What's New in v2.0

• Svelte 5 Support - Fully migrated to Svelte 5 with runes ($props, $state, $effect, $derived)
• Customizable Trigger Shortcut - Change the default $mod+k to any shortcut
• Component Callbacks - onOpen, onClose, onActionSelect props
• Action Icons - Add icons to your actions
• Action Grouping - Group related actions together
• Custom Empty State - Provide a custom snippet for empty results
• Focus Trap - Keyboard focus stays within the palette
• Improved Accessibility - Better ARIA attributes and keyboard handling
• Type Exports - Export action type for TypeScript users

⚠️ Breaking Changes (v1.x → v2.x)

Version 2.0 is a complete rewrite for Svelte 5 and includes breaking changes:

| Change | v1.x (Svelte 3/4) | v2.x (Svelte 5) | |--------|-------------------|-----------------| | Svelte version | Svelte 3/4 | Svelte 5+ | | Props syntax | export let | $props() runes | | Event handlers | on:click | onclick | | Slots | <slot /> | {#snippet} / {@render} | | Reactivity | $: statements | $derived, $effect |

New Props in v2.0

• shortcut - Customize the keyboard shortcut (default: $mod+k)
• onOpen - Callback when palette opens
• onClose - Callback when palette closes
• onActionSelect - Callback when an action is selected
• emptyState - Custom snippet for empty results

New Action Properties

• icon - Add an icon (emoji or string) to actions
• group - Group related actions together

Using with Svelte 3/4

If you're still using Svelte 3 or 4, install the legacy version:

# For Svelte 3/4 projects
npm install [email protected]

The v1.x documentation is available at the v1.2.1 release.

Version Compatibility

| svelte-command-palette | Svelte Version | |------------------------|----------------| | ^2.0.0 | Svelte 5+ | | ^1.2.1 | Svelte 3, 4 |

Installation

npm install svelte-command-palette

pnpm add svelte-command-palette

yarn add svelte-command-palette

Quick Start

<script>
  import CommandPalette, { defineActions, createStoreMethods } from 'svelte-command-palette';

  const storeMethods = createStoreMethods();

  const actions = defineActions([
    {
      title: 'Go to Dashboard',
      subTitle: 'Navigate to the main dashboard',
      onRun: () => {
        window.location.href = '/dashboard';
      },
      shortcut: '$mod+d',
      keywords: ['home', 'main'],
      group: 'Navigation'
    },
    {
      title: 'Toggle Dark Mode',
      subTitle: 'Switch between light and dark themes',
      onRun: () => {
        document.documentElement.classList.toggle('dark');
      },
      shortcut: '$mod+Shift+d',
      icon: '🌙',
      group: 'Settings'
    },
    {
      title: 'Open GitHub',
      subTitle: 'View source code on GitHub',
      onRun: () => {
        window.open('https://github.com/rohitpotato/svelte-command-palette');
      },
      icon: '📦'
    }
  ]);
</script>

<button onclick={() => storeMethods.openPalette()}>
  Open Command Palette
</button>

<CommandPalette 
  commands={actions}
  placeholder="What would you like to do?"
  shortcut="$mod+k"
  onOpen={() => console.log('Palette opened')}
  onClose={() => console.log('Palette closed')}
  onActionSelect={(action) => console.log('Selected:', action.title)}
/>

API Reference

CommandPalette Component Props

| Property | Type | Default | Description | |----------|------|---------|-------------| | commands | action[] | [] | Array of actions to display | | placeholder | string | "Search for an action..." | Input placeholder text | | shortcut | string | "$mod+k" | Keyboard shortcut to open palette | | onOpen | () => void | - | Callback when palette opens | | onClose | () => void | - | Callback when palette closes | | onActionSelect | (action) => void | - | Callback when action is selected | | unstyled | boolean | false | Disable default styles | | emptyState | Snippet | - | Custom empty state content |

Styling Props

All styling props accept either a class name (string) or style object (Properties).

| Class Prop | Style Prop | Description | |------------|------------|-------------| | overlayClass | overlayStyle | Backdrop overlay | | paletteWrapperInnerClass | paletteWrapperInnerStyle | Main palette container | | inputClass | inputStyle | Search input | | resultsContainerClass | resultsContainerStyle | Results list container | | resultContainerClass | resultContainerStyle | Individual result item | | optionSelectedClass | optionSelectedStyle | Active/selected result | | titleClass | titleStyle | Result title | | subtitleClass | subtitleStyle | Result subtitle | | descriptionClass | descriptionStyle | Result description | | keyboardButtonClass | keyboardButtonStyle | Keyboard shortcut badges |

Action API

Define actions using the defineActions helper:

type action = {
  actionId?: string | number;        // Unique identifier (auto-generated if not provided)
  title: string;                      // Main display text (required)
  subTitle?: string;                  // Secondary text
  description?: string;               // Additional description
  keywords?: string[];                // Search keywords
  shortcut?: string;                  // Keyboard shortcut (e.g., "$mod+k")
  icon?: string | Snippet;           // Icon (emoji, URL, or Snippet for custom SVG/component)
  group?: string;                     // Group name for organizing actions
  onRun?: (params) => void;          // Callback when action is executed
  canActionRun?: (params) => boolean; // Conditional execution
};

onRun and canActionRun Parameters

type onRunParams = {
  action: action;                     // The current action
  storeProps: storeParams;           // Current store state
  storeMethods: StoreMethods;        // Store manipulation methods
};

Store Methods

Access palette controls from anywhere in your app:

import { createStoreMethods } from 'svelte-command-palette';

const methods = createStoreMethods();

// Available methods:
methods.openPalette();           // Open the palette
methods.closePalette();          // Close the palette
methods.togglePalette();         // Toggle open/close
methods.resetPaletteStore();     // Reset to initial state
methods.getAllCalledActions();   // Get history of executed actions
methods.storeCalledAction(id);   // Add action to history
methods.revertLastAction(id);    // Remove last action from history
methods.resetActionLog();        // Clear action history

Direct Store Access

For advanced use cases, access the store directly:

import { paletteStore } from 'svelte-command-palette';

// Subscribe to changes
paletteStore.subscribe(state => {
  console.log('Palette visible:', state.isVisible);
  console.log('Search text:', state.textInput);
  console.log('Results:', state.results);
});

// Update directly
paletteStore.update(state => ({
  ...state,
  isVisible: true
}));

Examples

Conditional Actions

const actions = defineActions([
  {
    title: 'Admin Panel',
    subTitle: 'Only visible to admins',
    canActionRun: ({ storeProps }) => {
      return storeProps.user?.role === 'admin';
    },
    onRun: () => {
      window.location.href = '/admin';
    }
  }
]);

Action Groups

const actions = defineActions([
  { title: 'Dashboard', group: 'Navigation', onRun: () => goto('/') },
  { title: 'Settings', group: 'Navigation', onRun: () => goto('/settings') },
  { title: 'Profile', group: 'User', onRun: () => goto('/profile') },
  { title: 'Logout', group: 'User', onRun: () => signOut() }
]);

Custom Icons

The icon property supports multiple formats:

Emoji Icons

const actions = defineActions([
  { title: 'Settings', icon: '⚙️', onRun: () => {} },
  { title: 'Search', icon: '🔍', onRun: () => {} }
]);

Image URLs

const actions = defineActions([
  { title: 'GitHub', icon: 'https://github.com/favicon.ico', onRun: () => {} },
  { title: 'Logo', icon: '/images/logo.svg', onRun: () => {} }
]);

Custom SVG with Snippets

<script>
  import CommandPalette, { defineActions } from 'svelte-command-palette';

  // Define a snippet for custom SVG
  const settingsIcon = {
    icon: settingsIconSnippet
  };
</script>

{#snippet settingsIconSnippet()}
  <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <circle cx="12" cy="12" r="3"></circle>
    <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"></path>
  </svg>
{/snippet}

<!-- Use in actions -->
<script>
  const actions = defineActions([
    { 
      title: 'Settings', 
      icon: settingsIconSnippet,
      onRun: () => openSettings() 
    }
  ]);
</script>

<CommandPalette commands={actions} />

Third-Party Icon Libraries (Lucide, Heroicons, etc.)

<script>
  import CommandPalette, { defineActions } from 'svelte-command-palette';
  import { Settings, Search, User } from 'lucide-svelte';
</script>

{#snippet settingsIcon()}
  <Settings size={20} />
{/snippet}

{#snippet searchIcon()}
  <Search size={20} />
{/snippet}

{#snippet userIcon()}
  <User size={20} />
{/snippet}

<script>
  const actions = defineActions([
    { title: 'Settings', icon: settingsIcon, onRun: () => {} },
    { title: 'Search', icon: searchIcon, onRun: () => {} },
    { title: 'Profile', icon: userIcon, onRun: () => {} }
  ]);
</script>

<CommandPalette commands={actions} />

Custom Empty State

<CommandPalette commands={actions}>
  {#snippet emptyState()}
    <div class="empty-state">
      <p>No results found</p>
      <button onclick={() => createNewAction()}>Create new action</button>
    </div>
  {/snippet}
</CommandPalette>

Custom Styling

<CommandPalette
  commands={actions}
  overlayClass="bg-black/50 backdrop-blur-sm"
  paletteWrapperInnerClass="bg-gray-900 rounded-xl shadow-2xl"
  inputClass="bg-transparent text-white placeholder-gray-400"
  resultContainerClass="hover:bg-gray-800 transition-colors"
  optionSelectedClass="bg-blue-600"
  inputStyle={{ fontSize: '18px' }}
/>

Keyboard Shortcuts

Use tinykeys syntax for shortcuts:

const actions = defineActions([
  { title: 'Save', shortcut: '$mod+s', onRun: save },      // Cmd+S / Ctrl+S
  { title: 'Undo', shortcut: '$mod+z', onRun: undo },      // Cmd+Z / Ctrl+Z
  { title: 'Search', shortcut: '$mod+Shift+f', onRun: search }, // Cmd+Shift+F
  { title: 'Help', shortcut: 'F1', onRun: showHelp }       // F1
]);

Keyboard Navigation

| Key | Action | |-----|--------| | Cmd/Ctrl + K | Open/close palette (customizable) | | ↑ / ↓ | Navigate through results | | Enter | Execute selected action | | Escape | Close palette | | Tab | Cycle through focusable elements |

TypeScript

Full TypeScript support with exported types:

import type { action, commands, storeParams, ActionId, onRunParams } from 'svelte-command-palette';

const myAction: action = {
  title: 'My Action',
  onRun: ({ action, storeProps, storeMethods }: onRunParams) => {
    console.log(action.title);
  }
};

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

# Clone the repo
git clone https://github.com/rohitpotato/svelte-command-palette.git

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Run unit tests only
npm run test:unit

# Run E2E tests only
npm run test:e2e

License

MIT © Rohit Kashyap

Links

• Documentation
• GitHub
• npm