Styling

CSS Variables

The plugin uses CSS custom properties that inherit from Starlight’s design tokens. This means the modal automatically matches your site’s theme without configuration. Override any of these to customize:

:root {
  /* Backgrounds */
  --telescope-overlay-bg: var(--sl-color-backdrop-overlay);
  --telescope-modal-bg: var(--sl-color-bg-nav);
  --telescope-modal-bg-alt: var(--sl-color-bg);

  /* Accent */
  --telescope-accent: var(--sl-color-accent);
  --telescope-accent-hover: color-mix(in srgb, var(--telescope-accent) 10%, transparent);
  --telescope-accent-selected: color-mix(in srgb, var(--telescope-accent) 18%, transparent);

  /* Text */
  --telescope-text-primary: var(--sl-color-white);
  --telescope-text-secondary: var(--sl-color-gray-3);

  /* Borders */
  --telescope-border: var(--sl-color-hairline-light);
  --telescope-border-active: var(--sl-color-gray-5);

  /* Features */
  --telescope-pin-color: var(--sl-color-purple);
  --telescope-tag-color: var(--sl-color-green);
}

Light/Dark Mode

Starlight handles theme detection via the data-theme attribute on the root element. The plugin inherits these values automatically. To customize colors per mode, target the attribute:

:root[data-theme='light'] {
  --telescope-accent: #6d28d9;
  --telescope-modal-bg: #ffffff;
}

Config-Based Theming

Colors can also be set via the plugin configuration instead of CSS. This is useful for quick customization without a separate stylesheet.

See Configuration → theme for available properties.

CSS Classes

The plugin uses BEM naming convention (telescope__element--modifier). All classes are prefixed with telescope to avoid conflicts with your existing styles.

Class	Element
.telescope	Modal container
.telescope__modal	Content wrapper
.telescope__search-input	Search input
.telescope__result-item	Result item
.telescope__result-item--selected	Selected state
.telescope__pin-button	Pin button
.telescope__pin-button--pinned	Pinned state
.telescope__highlight	Match highlight
.telescope__section-separator	Section header

Overriding Elements

Target specific elements to adjust sizing, spacing, or colors beyond what CSS variables provide:

.telescope__search-input {
  font-size: 20px;
}

.telescope__result-item {
  padding: 16px 24px;
}

.telescope__highlight {
  background-color: rgba(255, 200, 0, 0.3);
}

Accessibility

When customizing colors, maintain WCAG AA contrast ratios (4.5:1 minimum for text, 3:1 for UI components). Use WebAIM Contrast Checker to verify your choices.

The plugin respects prefers-reduced-motion. Animations are disabled automatically for users who prefer reduced motion:

@media (prefers-reduced-motion: reduce) {
  .telescope[open],
  .telescope__result-item {
    animation: none;
    transition: none;
  }
}

Responsive

The modal adapts to screen size automatically. Default behavior:

• Desktop: 640px max-width, centered
• Mobile: 95% width with reduced padding

Override breakpoint styles as needed:

@media (max-width: 768px) {
  .telescope__search-input {
    font-size: 16px;
  }
}