> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```typescript theme={null}
type DocSearchTheme = 'dark' | 'light';
```

## Usage

<ParamField path="theme" type="'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
</ParamField>

<CodeGroup>
  ```tsx Light Theme theme={null}
  import { DocSearch } from '@docsearch/react';

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

  ```tsx Dark Theme theme={null}
  import { DocSearch } from '@docsearch/react';

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

## Dynamic Theme Switching

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

<CodeGroup>
  ```tsx React State theme={null}
  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>
    );
  }
  ```

  ```tsx System Preference theme={null}
  import { DocSearch } from '@docsearch/react';
  import { useEffect, useState } from 'react';

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

    useEffect(() => {
      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
      setTheme(mediaQuery.matches ? 'dark' : 'light');

      const handler = (e: MediaQueryListEvent) => {
        setTheme(e.matches ? 'dark' : 'light');
      };

      mediaQuery.addEventListener('change', handler);
      return () => mediaQuery.removeEventListener('change', handler);
    }, []);

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

  ```tsx Next.js with next-themes theme={null}
  import { DocSearch } from '@docsearch/react';
  import { useTheme } from 'next-themes';

  function SearchComponent() {
    const { theme } = useTheme();

    return (
      <DocSearch
        appId="YOUR_APP_ID"
        apiKey="YOUR_API_KEY"
        indexName="docs"
        theme={theme === 'dark' ? 'dark' : 'light'}
      />
    );
  }
  ```
</CodeGroup>

## 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:

```css theme={null}
: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:

```css theme={null}
/* 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

<CodeGroup>
  ```tsx Component theme={null}
  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"
      />
    );
  }
  ```

  ```css custom-docsearch.css theme={null}
  :root {
    /* Override primary color with brand color */
    --docsearch-primary-color: #ff6b6b;
    --docsearch-searchbox-shadow: inset 0 0 0 2px #ff6b6b;
  }

  /* Custom button styling */
  .DocSearch-Button {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border: none;
    color: white;
  }

  .DocSearch-Button:hover {
    opacity: 0.9;
  }

  /* Active hit styling */
  .DocSearch-Hit[aria-selected='true'] {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  }
  ```
</CodeGroup>

## Theme Implementation

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

```typescript theme={null}
// 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 theme={null}
<html data-theme="dark">
  <!-- Your app -->
</html>
```

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Test Both Themes">
    Always test your custom styling in both light and dark modes to ensure readability and proper contrast ratios.
  </Accordion>

  <Accordion title="Use CSS Variables">
    Prefer CSS variables over hard-coded values for easier theme maintenance and consistency.
  </Accordion>

  <Accordion title="Respect User Preferences">
    Consider detecting and respecting the user's system theme preference using `prefers-color-scheme` media query.
  </Accordion>
</AccordionGroup>

## Related Resources

* [Configuration](/api/configuration) - Full configuration options
* [Translations](/api/translations) - Localization options
* [DocSearch CSS Repository](https://github.com/algolia/docsearch/tree/main/packages/docsearch-css) - Full CSS source code