Theme Options

Customize DocSearch appearance with theme configuration.

DocSearch supports theme customization through the theme prop, which controls the visual appearance of the search modal and button.

Theme Type

The theme prop accepts a simple string value:

type DocSearchTheme = 'dark' | 'light';

Usage

theme · 'dark' | 'light'

Controls the visual theme of DocSearch components. The theme affects:

• Search button appearance
• Modal background and text colors
• Search results styling
• Icon colors
• Border and shadow styles

Light Theme

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

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

Dynamic Theme Switching

You can dynamically switch themes based on your application’s theme settings:

React State

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

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

  return (
    <div>
      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        Toggle Theme
      </button>
      <DocSearch
        appId="YOUR_APP_ID"
        apiKey="YOUR_API_KEY"
        indexName="docs"
        theme={theme}
      />
    </div>
  );
}

Custom Styling

While the theme prop provides basic light/dark mode support, you can further customize DocSearch appearance using CSS variables and custom CSS.

CSS Variables

DocSearch uses CSS custom properties that you can override:

:root {
  /* Light theme customization */
  --docsearch-primary-color: #5468ff;
  --docsearch-text-color: #1c1e21;
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: #969faf;
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  --docsearch-modal-background: #f5f6f7;
  --docsearch-searchbox-background: rgb(235, 237, 240);
  --docsearch-searchbox-focus-background: #fff;
  --docsearch-searchbox-shadow: inset 0 0 0 2px var(--docsearch-primary-color);
  --docsearch-hit-color: #444950;
  --docsearch-hit-active-color: #fff;
  --docsearch-hit-background: #fff;
  --docsearch-hit-shadow: 0 1px 3px 0 #d4d9e1;
  --docsearch-key-gradient: linear-gradient(-225deg, #d5dbe4, #f8f8f8);
  --docsearch-key-shadow: inset 0 -2px 0 0 #cdcde6, inset 0 0 1px 1px #fff,
    0 1px 2px 1px rgba(30, 35, 90, 0.4);
  --docsearch-footer-background: #fff;
  --docsearch-footer-shadow: 0 -1px 0 0 #e0e3e8, 0 -3px 6px 0 rgba(69, 98, 155, 0.12);
}

[data-theme='dark'] {
  /* Dark theme customization */
  --docsearch-text-color: #f5f6f7;
  --docsearch-container-background: rgba(9, 10, 17, 0.8);
  --docsearch-modal-background: #15172a;
  --docsearch-searchbox-background: #090a11;
  --docsearch-searchbox-focus-background: #000;
  --docsearch-hit-color: #bec3c9;
  --docsearch-hit-shadow: none;
  --docsearch-hit-background: #090a11;
  --docsearch-key-gradient: linear-gradient(-26.5deg, #565872, #31355b);
  --docsearch-key-shadow: inset 0 -2px 0 0 #282d55, inset 0 0 1px 1px #51577d,
    0 2px 2px 0 rgba(3, 4, 9, 0.3);
  --docsearch-footer-background: #1e2136;
  --docsearch-footer-shadow: inset 0 1px 0 0 rgba(73, 76, 106, 0.5),
    0 -4px 8px 0 rgba(0, 0, 0, 0.2);
  --docsearch-logo-color: #fff;
  --docsearch-muted-color: #7f8497;
}

Custom CSS Classes

You can target specific DocSearch classes for more granular control:

/* Button customization */
.DocSearch-Button {
  border-radius: 8px;
  padding: 0 12px;
}

.DocSearch-Button:hover {
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

/* Modal customization */
.DocSearch-Modal {
  border-radius: 12px;
}

/* Search results customization */
.DocSearch-Hit {
  border-radius: 6px;
}

.DocSearch-Hit[aria-selected='true'] {
  background: linear-gradient(to right, #667eea, #764ba2);
}

/* Footer customization */
.DocSearch-Footer {
  border-top: 1px solid var(--docsearch-muted-color);
}

Example: Custom Brand Colors

Component

import { DocSearch } from '@docsearch/react';
import './custom-docsearch.css';

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

Theme Implementation

The theme implementation in DocSearch uses a React hook that applies the appropriate CSS class to the document:

// Internal implementation (for reference)
import { useEffect } from 'react';

export function useTheme({ theme }: { theme?: DocSearchTheme }) {
  useEffect(() => {
    if (!theme) return;
    
    document.documentElement.setAttribute('data-theme', theme);
    
    return () => {
      document.documentElement.removeAttribute('data-theme');
    };
  }, [theme]);
}

This means you can also manually set the theme by adding the data-theme attribute to your HTML element:

<html data-theme="dark">
  <!-- Your app -->
</html>

Best Practices

Match Your Site's Theme

Always ensure DocSearch’s theme matches your site’s overall theme for a consistent user experience. Use dynamic theme switching to keep them in sync.

Test Both Themes

Always test your custom styling in both light and dark modes to ensure readability and proper contrast ratios.

Use CSS Variables

Prefer CSS variables over hard-coded values for easier theme maintenance and consistency.

Respect User Preferences

Consider detecting and respecting the user’s system theme preference using prefers-color-scheme media query.

Related Resources

• Configuration - Full configuration options
• Translations - Localization options
• DocSearch CSS Repository - Full CSS source code