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

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

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

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

<CodeGroup>
  ```jsx React Context theme={null}
  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}
      />
    );
  }
  ```

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

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

## How Theme Works

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

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

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

<Accordion title="Light Theme Variables">
  ```css theme={null}
  :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);
  }
  ```
</Accordion>

<Accordion title="Dark Theme Variables">
  ```css theme={null}
  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);
  }
  ```
</Accordion>

## Customizing Variables

You can override any CSS variable to match your brand:

### Brand Colors

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

```css theme={null}
:root {
  --docsearch-modal-width: 900px;
  --docsearch-modal-height: 700px;
}
```

### Border Radius

```css theme={null}
:root {
  --docsearch-border-radius: 8px;
}
```

### Typography

```css theme={null}
:root {
  --docsearch-text-color: #1a202c;
  --docsearch-secondary-text-color: #718096;
}
```

## Complete Custom Theme Example

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

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

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

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

## TypeScript Interface

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

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

## Best Practices

<Steps>
  <Step title="Match your site's theme">
    Use the `theme` prop to automatically sync DocSearch with your site's light/dark mode.
  </Step>

  <Step title="Test both themes">
    If you customize CSS variables, make sure to test both light and dark modes.
  </Step>

  <Step title="Use semantic colors">
    Stick to the semantic variable names (primary, highlight, focus) rather than hardcoding specific colors.
  </Step>

  <Step title="Maintain contrast">
    Ensure text remains readable by maintaining sufficient color contrast, especially in custom themes.
  </Step>

  <Step title="Consider accessibility">
    Follow WCAG guidelines for color contrast ratios (4.5:1 for normal text, 3:1 for large text).
  </Step>
</Steps>

## Common Customizations

<Accordion title="Match Tailwind CSS Colors">
  ```css theme={null}
  :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 */
  }
  ```
</Accordion>

<Accordion title="Rounded Modal">
  ```css theme={null}
  :root {
    --docsearch-border-radius: 16px;
  }
  ```
</Accordion>

<Accordion title="Compact Layout">
  ```css theme={null}
  :root {
    --docsearch-spacing: 8px;
    --docsearch-searchbox-height: 48px;
    --docsearch-hit-height: 48px;
    --docsearch-modal-height: 500px;
  }
  ```
</Accordion>

<Accordion title="High Contrast Mode">
  ```css theme={null}
  html[data-theme='dark'] {
    --docsearch-text-color: #ffffff;
    --docsearch-background-color: #000000;
    --docsearch-modal-background: #000000;
    --docsearch-hit-background: #1a1a1a;
  }
  ```
</Accordion>