Theming

Customize DocSearch appearance with themes and CSS variables

DocSearch provides flexible theming options, including built-in light and dark modes, plus extensive CSS variable customization.

Theme Modes

DocSearch supports two built-in theme modes:

• Light: Default theme optimized for light backgrounds
• Dark: High-contrast theme for dark mode experiences

Setting the Theme

Use the theme prop to control the DocSearch appearance:

import { DocSearch } from '@docsearch/react';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      theme="dark"
    />
  );
}

Dynamic Theme Switching

You can dynamically change the theme based on user preferences:

import { DocSearch } from '@docsearch/react';
import { useState, useEffect } from 'react';

function App() {
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    // Listen to system theme preference
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    
    const handleChange = (e) => {
      setTheme(e.matches ? 'dark' : 'light');
    };
    
    handleChange(mediaQuery);
    mediaQuery.addEventListener('change', handleChange);
    
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);

  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      theme={theme}
    />
  );
}

Theme Context Integration

Integrate with your site’s theme system:

React Context

import { DocSearch } from '@docsearch/react';
import { useTheme } from './ThemeContext';

function SearchButton() {
  const { theme } = useTheme();
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      theme={theme}
    />
  );
}

How Theme Works

The theme prop sets a data-theme attribute on the document root:

export const useTheme = ({ theme }: UseThemeProps): void => {
  useEffect(() => {
    if (theme) {
      const previousTheme = document.documentElement.dataset.theme;
      if (theme !== previousTheme) {
        document.documentElement.dataset.theme = theme;
        return (): void => {
          if (previousTheme === undefined) {
            delete document.documentElement.dataset.theme;
          } else {
            document.documentElement.dataset.theme = previousTheme;
          }
        };
      }
    }
    return undefined;
  }, [theme]);
};

This allows CSS to target different themes using attribute selectors:

html[data-theme='dark'] {
  --docsearch-text-color: rgba(196, 199, 220, 1);
  --docsearch-modal-background: rgb(21, 23, 42);
}

CSS Variables

DocSearch uses CSS custom properties (variables) for all styling, making it easy to customize without overriding CSS classes.

Complete Variable Reference

Light Theme Variables

:root {
  /* Colors */
  --docsearch-primary-color: rgb(0, 61, 255);
  --docsearch-soft-primary-color: rgba(0, 61, 255, 0.1);
  --docsearch-subtle-color: rgb(214, 214, 231);
  --docsearch-text-color: #36395a;
  --docsearch-error-color: #ef5350;
  --docsearch-success-color: #e8f5e9;
  --docsearch-secondary-text-color: rgba(90, 94, 154, 1);
  --docsearch-background-color: rgb(245, 245, 250);
  --docsearch-icon-color: rgba(90, 94, 154, 1);
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  --docsearch-logo-color: rgba(0, 61, 255, 1);
  --docsearch-muted-color: rgba(150, 152, 195, 1);
  --docsearch-muted-color-darker: rgba(120, 122, 165, 0.25);

  /* Spacing & Layout */
  --docsearch-spacing: 12px;
  --docsearch-border-radius: 4px;
  --docsearch-icon-stroke-width: 1.4;

  /* Highlights & Focus */
  --docsearch-focus-color: rgb(0, 95, 204);
  --docsearch-highlight-color: rgb(0, 61, 255);

  /* Button */
  --docsearch-search-button-background: #fff;
  --docsearch-search-button-text-color: var(--docsearch-secondary-text-color);

  /* Modal */
  --docsearch-modal-width: 800px;
  --docsearch-modal-height: 600px;
  --docsearch-modal-variable-height: 60dvh;
  --docsearch-modal-background: rgb(245, 246, 247);
  --docsearch-modal-shadow: rgba(0, 0, 0, 0.2) 0px 12px 28px 0px,
    rgba(0, 0, 0, 0.1) 0px 2px 4px 0px,
    rgba(255, 255, 255, 0.05) 0px 0px 0px 1px inset;

  /* Searchbox */
  --docsearch-searchbox-height: 56px;
  --docsearch-searchbox-initial-height: 56px;
  --docsearch-searchbox-background: #ffffffa6;
  --docsearch-searchbox-focus-background: #ffffffa6;
  --docsearch-actions-width: 99px;
  --docsearch-actions-height: 44px;

  /* Hit */
  --docsearch-hit-height: 56px;
  --docsearch-hit-color: rgb(68, 73, 80);
  --docsearch-hit-highlight-color: rgba(0, 61, 255, 0.1);
  --docsearch-hit-background: #fff;

  /* Key */
  --docsearch-key-background: rgb(245, 245, 250);
  --docsearch-key-color: rgba(90, 94, 154, 1);
  --docsearch-key-pressed-shadow: inset 0 2px 4px rgba(120, 122, 165, 0.25);

  /* Footer */
  --docsearch-footer-height: 52px;
  --docsearch-footer-background: #ffffffa6;
  --docsearch-footer-shadow: 0 -1px 0 0 rgb(224, 227, 232),
    0 -3px 6px 0 rgba(69, 98, 155, 0.12);

  /* Dropdown Menu */
  --docsearch-dropdown-menu-background: var(--docsearch-hit-background);
  --docsearch-dropdown-menu-item-hover-background: var(--docsearch-modal-background);
}

Dark Theme Variables

html[data-theme='dark'] {
  /* Colors */
  --docsearch-text-color: rgba(196, 199, 220, 1);
  --docsearch-secondary-text-color: rgba(182, 183, 213, 1);
  --docsearch-subtle-color: rgba(33, 33, 57, 1);
  --docsearch-error-color: #ef5350;
  --docsearch-success-color: rgba(67, 160, 71, 0.2);
  --docsearch-highlight-color: rgba(69, 122, 255, 1);
  --docsearch-focus-color: rgb(154, 200, 255);
  --docsearch-background-color: rgba(54, 57, 90, 1);
  --docsearch-icon-color: rgba(182, 183, 213, 1);
  --docsearch-container-background: rgba(9, 10, 17, 0.8);
  --docsearch-modal-background: rgb(21, 23, 42);
  --docsearch-logo-color: rgb(255, 255, 255);
  --docsearch-muted-color: rgb(127, 132, 151);

  /* Modal */
  --docsearch-modal-shadow: inset 1px 1px 0 0 rgb(44, 46, 64),
    0 3px 8px 0 rgb(0, 3, 9);

  /* Searchbox */
  --docsearch-searchbox-background: #000000a6;
  --docsearch-searchbox-focus-background: #000000a6;

  /* Hit */
  --docsearch-hit-color: rgb(190, 195, 201);
  --docsearch-hit-shadow: none;
  --docsearch-hit-background: rgb(9, 10, 17);

  /* Key */
  --docsearch-key-background: rgba(54, 57, 90, 1);
  --docsearch-key-color: rgba(182, 183, 213, 1);
  --docsearch-key-pressed-shadow: inset 0 2px 4px rgba(12, 13, 20, 0.4);

  /* Footer */
  --docsearch-footer-background: #000000a6;
  --docsearch-footer-shadow: inset 0 1px 0 0 rgba(73, 76, 106, 0.5),
    0 -4px 8px 0 rgba(0, 0, 0, 0.2);

  /* Button */
  --docsearch-search-button-background: var(--docsearch-modal-background);
  --docsearch-search-button-text-color: var(--docsearch-text-color);

  /* Dropdown Menu */
  --docsearch-dropdown-menu-background: var(--docsearch-hit-background);
  --docsearch-dropdown-menu-item-hover-background: var(--docsearch-modal-background);
}

Customizing Variables

You can override any CSS variable to match your brand:

Brand Colors

:root {
  --docsearch-primary-color: #ff6b6b;
  --docsearch-soft-primary-color: rgba(255, 107, 107, 0.1);
  --docsearch-highlight-color: #ff6b6b;
  --docsearch-logo-color: #ff6b6b;
}

html[data-theme='dark'] {
  --docsearch-primary-color: #ff8787;
  --docsearch-highlight-color: #ff8787;
}

Modal Size

:root {
  --docsearch-modal-width: 900px;
  --docsearch-modal-height: 700px;
}

Border Radius

:root {
  --docsearch-border-radius: 8px;
}

Typography

:root {
  --docsearch-text-color: #1a202c;
  --docsearch-secondary-text-color: #718096;
}

Complete Custom Theme Example

Here’s a complete example of a custom purple theme:

/* Custom Purple Theme */
:root {
  /* Brand Colors */
  --docsearch-primary-color: #7c3aed;
  --docsearch-soft-primary-color: rgba(124, 58, 237, 0.1);
  --docsearch-highlight-color: #7c3aed;
  --docsearch-logo-color: #7c3aed;
  --docsearch-focus-color: #8b5cf6;

  /* Layout */
  --docsearch-border-radius: 12px;
  --docsearch-spacing: 16px;

  /* Modal */
  --docsearch-modal-width: 840px;
  --docsearch-modal-background: #fafafa;
  
  /* Searchbox */
  --docsearch-searchbox-height: 64px;
  --docsearch-searchbox-background: #ffffff;
  
  /* Hit */
  --docsearch-hit-background: #ffffff;
  --docsearch-hit-highlight-color: rgba(124, 58, 237, 0.1);
}

html[data-theme='dark'] {
  /* Brand Colors for Dark Mode */
  --docsearch-primary-color: #a78bfa;
  --docsearch-highlight-color: #a78bfa;
  --docsearch-focus-color: #c4b5fd;
  
  /* Backgrounds */
  --docsearch-modal-background: #1a1a1a;
  --docsearch-searchbox-background: #2a2a2a;
  --docsearch-hit-background: #2a2a2a;
}

Scoped Theming

If you need DocSearch to have a different theme than your page:

/* Wrap DocSearch in a container with its own theme */
.docsearch-container[data-theme='dark'] {
  --docsearch-text-color: rgba(196, 199, 220, 1);
  --docsearch-modal-background: rgb(21, 23, 42);
  /* ... other dark theme variables */
}

<div className="docsearch-container" data-theme="dark">
  <DocSearch
    appId="YOUR_APP_ID"
    apiKey="YOUR_API_KEY"
    indexName="YOUR_INDEX_NAME"
  />
</div>

TypeScript Interface

export type DocSearchTheme = 'dark' | 'light';

export interface DocSearchProps {
  /**
   * Theme overrides applied to the modal and related components.
   */
  theme?: DocSearchTheme;
  // ... other props
}

Best Practices

1. Match your site's theme

   Use the theme prop to automatically sync DocSearch with your site’s light/dark mode.

2. Test both themes

   If you customize CSS variables, make sure to test both light and dark modes.

3. Use semantic colors

   Stick to the semantic variable names (primary, highlight, focus) rather than hardcoding specific colors.

4. Maintain contrast

   Ensure text remains readable by maintaining sufficient color contrast, especially in custom themes.

5. Consider accessibility

   Follow WCAG guidelines for color contrast ratios (4.5:1 for normal text, 3:1 for large text).

Common Customizations

Match Tailwind CSS Colors

:root {
  --docsearch-primary-color: rgb(59, 130, 246); /* blue-500 */
  --docsearch-highlight-color: rgb(59, 130, 246);
  --docsearch-text-color: rgb(17, 24, 39); /* gray-900 */
  --docsearch-secondary-text-color: rgb(107, 114, 128); /* gray-500 */
}

Rounded Modal

:root {
  --docsearch-border-radius: 16px;
}

Compact Layout

:root {
  --docsearch-spacing: 8px;
  --docsearch-searchbox-height: 48px;
  --docsearch-hit-height: 48px;
  --docsearch-modal-height: 500px;
}

High Contrast Mode

html[data-theme='dark'] {
  --docsearch-text-color: #ffffff;
  --docsearch-background-color: #000000;
  --docsearch-modal-background: #000000;
  --docsearch-hit-background: #1a1a1a;
}