Configuration

Configuration Options

The Starlight custom navigation plugin accepts an object with the following options. You can customize these options to fit your needs. The default values are provided for each option.

`showTooltip`

Type: boolean
Default: true
Description: Whether to show the custom tooltip (page title and keyboard shortcut) when hovering or focusing a navigation strip. When disabled, the browser’s native title tooltip shows the page name instead.

`navShortcuts`

Type: object
Default: { previous: { key: 'ArrowLeft', modifier: 'ctrl' }, next: { key: 'ArrowRight', modifier: 'ctrl' } }
Description: Configure keyboard shortcuts for page navigation.

`navShortcuts.previous`

Type: object
Default: { key: 'ArrowLeft', modifier: 'ctrl' }
Description: Configuration for the “previous page” shortcut.

`navShortcuts.previous.key`

Type: string
Default: 'ArrowLeft'
Description: The key to use for the “previous page” shortcut.

`navShortcuts.previous.modifier`

Type: 'ctrl' | 'alt' | 'shift' | 'meta'
Default: 'ctrl'
Description: The modifier key to use with the shortcut.

`navShortcuts.next`

Type: object
Default: { key: 'ArrowRight', modifier: 'ctrl' }
Description: Configuration for the “next page” shortcut.

`navShortcuts.next.key`

Type: string
Default: 'ArrowRight'
Description: The key to use for the “next page” shortcut.

`navShortcuts.next.modifier`

Type: 'ctrl' | 'alt' | 'shift' | 'meta'
Default: 'ctrl'
Description: The modifier key to use with the shortcut.

`scrollBehavior`

Type: object
Default: { hideDelay: 3000, hideThreshold: 100 }
Description: Auto-hide behavior of the compact floating buttons shown below 1280px.

`scrollBehavior.hideDelay`

Type: number
Default: 3000
Description: Time in milliseconds of inactivity before the floating buttons fade out.

`scrollBehavior.hideThreshold`

Type: number
Default: 100
Description: Scroll distance in pixels required to bring hidden buttons back.

Example Configuration

Here’s a complete example showing all available options:

import { starlight } from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightCustomNavigation from 'starlight-custom-navigation'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightCustomNavigation({
          // Show tooltip on hover/focus (default: true)
          showTooltip: true,
          // Keyboard shortcuts
          navShortcuts: {
            previous: { key: 'ArrowLeft', modifier: 'ctrl' },
            next: { key: 'ArrowRight', modifier: 'ctrl' }
          },
          // Auto-hide of the compact floating buttons (below 1280px)
          scrollBehavior: {
            hideDelay: 3000,
            hideThreshold: 100
          }
        }),
      ],
      title: 'My Docs',
    }),
  ],
})