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

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

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.
Always test your custom styling in both light and dark modes to ensure readability and proper contrast ratios.
Prefer CSS variables over hard-coded values for easier theme maintenance and consistency.
Consider detecting and respecting the user’s system theme preference using prefers-color-scheme media query.

Build docs developers (and LLMs) love

Get started for freeTalk to us