Skip to main content
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: 
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

: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);
}

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;
}

: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

: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 */
}

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

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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us