Configuration

All configuration options are optional. The plugin works out of the box with sensible defaults.

Overview

astro.config.mjs

starlightTelescope({
  shortcut: { /* keyboard shortcut config */ },
  fuseOptions: { /* search algorithm config */ },
  recentPagesCount: 5,
  maxResults: 20,
  debounceMs: 100,
  theme: { /* color customization */ },
})

Option	Type	Default	Description
shortcut	object	See below	Keyboard shortcut to open modal
fuseOptions	object	See below	Fuse.js search configuration
recentPagesCount	number	5	Recent pages to display (0-20)
maxResults	number	20	Maximum search results to display (1-100)
debounceMs	number	100	Search debounce delay (0-1000ms)
theme	object	{}	Theme color overrides

shortcut

Configure the keyboard shortcut to open the search modal.

Property	Type	Default	Description
key	string	'/'	The key to press
ctrl	boolean	true	Require Ctrl key
meta	boolean	true	Require Meta/Cmd key (Mac)
shift	boolean	false	Require Shift key
alt	boolean	false	Require Alt key

The default shortcut is Ctrl+/ on Windows/Linux and Cmd+/ on Mac.

Examples

Ctrl+K

shortcut: { key: 'k', ctrl: true, meta: true }

Ctrl+P

shortcut: { key: 'p', ctrl: true, meta: true }

Ctrl+Shift+F

shortcut: { key: 'f', ctrl: true, meta: true, shift: true }

fuseOptions

Configure Fuse.js fuzzy search behavior.

Property	Type	Default	Description
threshold	number	0.3	Match threshold (0 = exact, 1 = match all)
ignoreLocation	boolean	true	Ignore where match occurs in string
distance	number	100	Max distance for fuzzy matches
minMatchCharLength	number	2	Minimum characters to trigger match
findAllMatches	boolean	false	Continue searching after first match
keys	array	See below	Fields to search with weights

Default Keys

keys: [
  { name: 'title', weight: 1.0 },
  { name: 'path', weight: 0.6 },
  { name: 'tags', weight: 0.5 },
  { name: 'description', weight: 0.3 },
]

Threshold Values

Value	Behavior
0.0	Exact matches only
0.3	Minor typos allowed (default)
0.5	Moderate fuzziness
0.7	Very lenient matching

Example: Prioritize Descriptions

fuseOptions: {
  threshold: 0.4,
  keys: [
    { name: 'title', weight: 1.0 },
    { name: 'description', weight: 0.8 },
    { name: 'path', weight: 0.3 },
  ],
}

recentPagesCount

Number of recently visited pages to display. Set to 0 to disable the feature.

recentPagesCount: 10  // Show last 10 pages

recentPagesCount: 0   // Disable recent pages

maxResults

Maximum number of search results to display at once. This improves performance on large documentation sites by limiting DOM rendering. When there are more results than the limit, a message indicates how many total results were found.

maxResults: 30  // Show up to 30 results

maxResults: 50  // For larger monitors or power users

debounceMs

Milliseconds to wait after typing before searching. Higher values reduce CPU usage on slower devices.

debounceMs: 200  // Wait 200ms after typing stops

theme

Customize colors using CSS color values. All properties are optional and inherit from Starlight’s design tokens by default.

Property	CSS Variable	Inherits From
overlayBackground	--telescope-overlay-bg	--sl-color-backdrop-overlay
modalBackground	--telescope-modal-bg	--sl-color-bg-nav
modalBackgroundAlt	--telescope-modal-bg-alt	--sl-color-bg
accentColor	--telescope-accent	--sl-color-accent
accentHover	--telescope-accent-hover	Derived from accent
accentSelected	--telescope-accent-selected	Derived from accent
textPrimary	--telescope-text-primary	--sl-color-white
textSecondary	--telescope-text-secondary	--sl-color-gray-3
border	--telescope-border	--sl-color-hairline-light
borderActive	--telescope-border-active	--sl-color-gray-5
pinColor	--telescope-pin-color	--sl-color-purple
tagColor	--telescope-tag-color	--sl-color-green

Example: Purple Theme

theme: {
  accentColor: '#a855f7',
  accentHover: 'rgba(168, 85, 247, 0.1)',
  accentSelected: 'rgba(168, 85, 247, 0.15)',
  pinColor: '#ec4899',
}

See the Styling Guide for more theming options.

Complete Example

astro.config.mjs

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightTelescope from 'starlight-telescope'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightTelescope({
          shortcut: { key: 'k', ctrl: true, meta: true },
          fuseOptions: {
            threshold: 0.4,
            keys: [
              { name: 'title', weight: 1.0 },
              { name: 'description', weight: 0.5 },
            ],
          },
          recentPagesCount: 8,
          maxResults: 25,
          debounceMs: 150,
          theme: {
            accentColor: '#7c3aed',
            pinColor: '#f59e0b',
          },
        }),
      ],
      title: 'My Docs',
    }),
  ],
})