Spotlight

Basic usage

Drop <Spotlight> once in your layout or page, passing an actions array. It registers the keyboard shortcut automatically.

const actions = [
  { id: 'home',   label: 'Home',   href: '/' },
  { id: 'docs',   label: 'Docs',   description: 'Read the documentation', href: '/docs' },
  { id: 'github', label: 'GitHub', href: 'https://github.com/davaux' },
]

<Spotlight actions={actions} />

Action groups

Add a group string to any action to render a section header. Actions with the same group value are collected under one header.

const actions = [
  { id: 'button',  label: 'Button',  group: 'Components', href: '/components/button' },
  { id: 'modal',   label: 'Modal',   group: 'Components', href: '/components/modal'  },
  { id: 'home',    label: 'Home',    group: 'Navigation', href: '/'                  },
]

<Spotlight actions={actions} />

Custom event for non-navigation actions

For actions that run JS (open a dialog, copy text, etc.) — omit href and listen for the dv-spotlight-select event dispatched on document. The event.detail.id value identifies which action was chosen.

<Spotlight
  actions={[
    { id: 'copy-url', label: 'Copy page URL' },
    { id: 'print',    label: 'Print page'    },
  ]}
/>

<script>
  document.addEventListener('dv-spotlight-select', (e) => {
    if (e.detail.id === 'copy-url') navigator.clipboard.writeText(location.href)
    if (e.detail.id === 'print')    window.print()
  })
</script>

Trigger button

Pass a CSS selector to trigger and Spotlight auto-binds a click handler to that element — no inline script needed. This is how the search button in the header of this docs site is wired up.

<Spotlight actions={actions} trigger=".search-btn" />

<Button class="search-btn" variant="default" leftSection={<Kbd>Ctrl K</Kbd>}>
  Search docs…
</Button>

Custom shortcut key

Override the key used with shortcutKey. The shortcut is alwaysCtrl+key on Windows/Linux and ⌘+key on Mac.

{/* Opens on Ctrl+/ or ⌘+/ */}
<Spotlight shortcutKey="/" actions={actions} />

Keyboard behaviour

• Ctrl+K / ⌘K — opens the palette (configurable with shortcutKey)
• ↑ / ↓ — navigate the action list
• Enter — trigger the active action
• Escape — close the palette
• Click overlay — close the palette