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

# Styling

> Customize DocSearch appearance with CSS variables and themes

DocSearch provides extensive styling options through CSS custom properties (variables), allowing you to match your brand and design system without writing custom CSS.

## Quick Start

### Import Default Styles

First, import the base DocSearch CSS:

<CodeGroup>
  ```tsx React theme={null}
  import '@docsearch/css';
  ```

  ```javascript JavaScript theme={null}
  import '@docsearch/css';
  ```

  ```html CDN theme={null}
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
  ```
</CodeGroup>

### Apply a Theme

DocSearch supports light and dark themes:

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

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  theme="dark" // or "light"
/>
```

## CSS Variables

DocSearch uses CSS custom properties for styling. Override them to customize appearance:

```css theme={null}
:root {
  /* Colors */
  --docsearch-primary-color: rgb(0, 61, 255);
  --docsearch-text-color: #36395a;
  --docsearch-highlight-color: rgb(0, 61, 255);
  --docsearch-muted-color: rgba(150, 152, 195, 1);
  --docsearch-background-color: rgb(245, 245, 250);
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  
  /* Modal */
  --docsearch-modal-width: 800px;
  --docsearch-modal-height: 600px;
  --docsearch-modal-background: rgb(245, 246, 247);
  --docsearch-modal-shadow: rgba(0, 0, 0, 0.2) 0px 12px 28px 0px;
  
  /* Searchbox */
  --docsearch-searchbox-height: 56px;
  --docsearch-searchbox-background: #ffffffa6;
  --docsearch-searchbox-focus-background: #ffffffa6;
  
  /* Hit */
  --docsearch-hit-height: 56px;
  --docsearch-hit-color: rgb(68, 73, 80);
  --docsearch-hit-background: #fff;
  --docsearch-hit-highlight-color: rgba(0, 61, 255, 0.1);
  
  /* Footer */
  --docsearch-footer-height: 52px;
  --docsearch-footer-background: #ffffffa6;
  
  /* Spacing */
  --docsearch-spacing: 12px;
  --docsearch-border-radius: 4px;
}
```

<Note>
  All CSS variables are scoped to `:root` and can be overridden at any level.
</Note>

## Color Variables

### Primary Colors

Control brand colors throughout the interface:

```css theme={null}
:root {
  /* Main brand color for highlights and accents */
  --docsearch-primary-color: rgb(0, 61, 255);
  
  /* Soft version for backgrounds */
  --docsearch-soft-primary-color: rgba(0, 61, 255, 0.1);
  
  /* Text highlight color */
  --docsearch-highlight-color: rgb(0, 61, 255);
  
  /* Focus ring color */
  --docsearch-focus-color: rgb(0, 95, 204);
}
```

### Text Colors

```css theme={null}
:root {
  /* Main text color */
  --docsearch-text-color: #36395a;
  
  /* Secondary text (descriptions, metadata) */
  --docsearch-secondary-text-color: rgba(90, 94, 154, 1);
  
  /* Muted text (hints, help text) */
  --docsearch-muted-color: rgba(150, 152, 195, 1);
  
  /* Icon color */
  --docsearch-icon-color: rgba(90, 94, 154, 1);
}
```

### Background Colors

```css theme={null}
:root {
  /* Modal overlay backdrop */
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  
  /* Modal background */
  --docsearch-modal-background: rgb(245, 246, 247);
  
  /* General background color */
  --docsearch-background-color: rgb(245, 245, 250);
  
  /* Search result background */
  --docsearch-hit-background: #fff;
  
  /* Subtle borders and dividers */
  --docsearch-subtle-color: rgb(214, 214, 231);
}
```

### Semantic Colors

```css theme={null}
:root {
  /* Error states */
  --docsearch-error-color: #ef5350;
  
  /* Success states */
  --docsearch-success-color: #e8f5e9;
  
  /* Algolia logo tint */
  --docsearch-logo-color: rgba(0, 61, 255, 1);
}
```

## Dark Theme

DocSearch automatically switches to dark theme when `theme="dark"`:

```typescript theme={null}
import { useTheme } from '@docsearch/react';

export const useTheme = ({ theme }: { theme?: 'light' | 'dark' }) => {
  useEffect(() => {
    if (theme) {
      document.documentElement.dataset.theme = theme;
    }
  }, [theme]);
};
```

This sets `data-theme="dark"` on the document, which activates dark mode variables:

```css theme={null}
html[data-theme='dark'] {
  --docsearch-text-color: rgba(196, 199, 220, 1);
  --docsearch-container-background: rgba(9, 10, 17, 0.8);
  --docsearch-modal-background: rgb(21, 23, 42);
  --docsearch-hit-background: rgb(9, 10, 17);
  --docsearch-searchbox-background: #000000a6;
  /* ... more dark theme variables ... */
}
```

<Accordion title="Complete Dark Theme Variables">
  ```css theme={null}
  html[data-theme='dark'] {
    --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-modal-shadow: inset 1px 1px 0 0 rgb(44, 46, 64), 0 3px 8px 0 rgb(0, 3, 9);
    --docsearch-searchbox-background: #000000a6;
    --docsearch-searchbox-focus-background: #000000a6;
    --docsearch-hit-color: rgb(190, 195, 201);
    --docsearch-hit-shadow: none;
    --docsearch-hit-background: rgb(9, 10, 17);
    --docsearch-key-background: rgba(54, 57, 90, 1);
    --docsearch-key-color: rgba(182, 183, 213, 1);
    --docsearch-footer-background: #000000a6;
    --docsearch-logo-color: rgb(255, 255, 255);
    --docsearch-muted-color: rgb(127, 132, 151);
  }
  ```
</Accordion>

## Component Styling

### Search Button

```css theme={null}
.DocSearch-Button {
  /* Button uses these variables */
  background: var(--docsearch-search-button-background);
  color: var(--docsearch-search-button-text-color);
}

:root {
  --docsearch-search-button-background: #fff;
  --docsearch-search-button-text-color: var(--docsearch-secondary-text-color);
}
```

Customize the button:

```css theme={null}
.DocSearch-Button {
  border-radius: 8px;
  padding: 0 16px;
  height: 40px;
  font-weight: 500;
}

.DocSearch-Button:hover {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
```

### Search Modal

Resize and position the modal:

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

.DocSearch-Modal {
  margin: 80px auto;
  border-radius: 12px;
}
```

### Search Input

```css theme={null}
.DocSearch-Input {
  font-size: 18px;
  color: var(--docsearch-text-color);
}

.DocSearch-Input::placeholder {
  color: var(--docsearch-muted-color);
}
```

### Search Results

Style individual hits:

```css theme={null}
.DocSearch-Hit {
  /* Hit container */
}

.DocSearch-Hit a {
  background: var(--docsearch-hit-background);
  border-radius: 4px;
}

.DocSearch-Hit[aria-selected='true'] a {
  background: var(--docsearch-hit-highlight-color);
}

.DocSearch-Hit mark {
  color: var(--docsearch-highlight-color);
  text-decoration: underline;
}
```

### Footer

```css theme={null}
.DocSearch-Footer {
  background: var(--docsearch-footer-background);
  height: var(--docsearch-footer-height);
  border-top: 1px solid var(--docsearch-subtle-color);
}

.DocSearch-Logo {
  color: var(--docsearch-logo-color);
}
```

## Ask AI Styling

Customize the AI-powered search interface:

### Ask AI Screen

```css theme={null}
.DocSearch-AskAiScreen-Container {
  padding: 24px;
}

.DocSearch-AskAiScreen-Disclaimer {
  font-size: 0.85em;
  color: var(--docsearch-muted-color);
  margin-bottom: 16px;
}
```

### Messages

```css theme={null}
.DocSearch-AskAiScreen-Response {
  background: var(--docsearch-hit-background);
  border-radius: 8px;
  padding: 24px;
  margin-bottom: 16px;
}

.DocSearch-AskAiScreen-Message--user {
  /* User question styles */
}

.DocSearch-AskAiScreen-Message--assistant {
  /* AI response styles */
}
```

### Markdown Content

```css theme={null}
.DocSearch-Markdown-Content {
  color: var(--docsearch-text-color);
  line-height: 1.6;
}

.DocSearch-Markdown-Content code {
  background: var(--docsearch-key-background);
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Monaco', 'Courier New', monospace;
}

.DocSearch-Markdown-Content pre {
  background: var(--docsearch-key-background);
  padding: 16px;
  border-radius: 6px;
  overflow-x: auto;
}

.DocSearch-Markdown-Content a {
  color: var(--docsearch-highlight-color);
  text-decoration: none;
}
```

### Source Citations

```css theme={null}
.DocSearch-AskAiScreen-RelatedSources {
  margin-top: 16px;
}

.DocSearch-AskAiScreen-RelatedSources-Item-Link {
  background: var(--docsearch-hit-background);
  border-radius: 4px;
  padding: 12px;
  color: var(--docsearch-text-color);
  transition: background-color 0.2s ease;
}

.DocSearch-AskAiScreen-RelatedSources-Item-Link:hover {
  background: var(--docsearch-hit-highlight-color);
}
```

### Action Buttons

```css theme={null}
.DocSearch-AskAiScreen-ActionButton {
  padding: 8px;
  border-radius: 4px;
  transition: background-color 0.2s ease;
}

.DocSearch-AskAiScreen-ActionButton:hover {
  background: var(--docsearch-hit-highlight-color);
}

.DocSearch-AskAiScreen-CopyButton--copied {
  background-color: var(--docsearch-success-color);
}
```

## Responsive Styles

DocSearch adapts to mobile devices:

```css theme={null}
@media (max-width: 768px) {
  :root {
    --docsearch-spacing: 10px;
    --docsearch-footer-height: 48px;
  }

  .DocSearch-Modal {
    /* Full screen on mobile */
    width: 100%;
    height: 100dvh;
    margin: 0;
    border-radius: 0;
  }

  .DocSearch-Input {
    font-size: 1rem;
  }

  .DocSearch-Commands {
    /* Hide keyboard shortcuts on mobile */
    display: none;
  }
}
```

## Custom Themes Example

### Brand Integration

```css theme={null}
/* Match your brand colors */
:root {
  --docsearch-primary-color: #7c3aed; /* Purple brand */
  --docsearch-soft-primary-color: rgba(124, 58, 237, 0.1);
  --docsearch-highlight-color: #7c3aed;
  --docsearch-focus-color: #a78bfa;
  
  /* Custom modal styling */
  --docsearch-modal-width: 850px;
  --docsearch-border-radius: 12px;
  
  /* Custom fonts */
  --docsearch-font-family: 'Inter', -apple-system, sans-serif;
}

.DocSearch-Input {
  font-family: var(--docsearch-font-family);
}
```

### High Contrast Theme

```css theme={null}
:root {
  --docsearch-text-color: #000;
  --docsearch-background-color: #fff;
  --docsearch-primary-color: #0066cc;
  --docsearch-hit-background: #f5f5f5;
  --docsearch-highlight-color: #0066cc;
  --docsearch-container-background: rgba(0, 0, 0, 0.9);
}
```

### Minimal Theme

```css theme={null}
:root {
  --docsearch-border-radius: 2px;
  --docsearch-modal-shadow: 0 0 0 1px rgba(0, 0, 0, 0.1);
  --docsearch-hit-background: transparent;
  --docsearch-searchbox-background: transparent;
}

.DocSearch-Modal {
  border: 1px solid var(--docsearch-subtle-color);
}
```

## Advanced Customization

### Custom Hit Component

Replace the default hit rendering:

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

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  hitComponent={({ hit, children }) => (
    <a href={hit.url} className="custom-hit">
      <div className="custom-hit-icon">
        {hit.hierarchy.lvl0 === 'API' ? '⚡' : '📄'}
      </div>
      {children}
    </a>
  )}
/>
```

### Custom Footer

```tsx theme={null}
<DocSearch
  resultsFooterComponent={({ state }) => (
    <div className="custom-footer">
      <p>Found {state.context.nbHits} results</p>
      <a href="/introduction">View all docs</a>
    </div>
  )}
/>
```

## CSS Class Reference

<Accordion title="Complete CSS Classes">
  ### Container

  * `.DocSearch-Container` - Modal overlay
  * `.DocSearch-Modal` - Main modal

  ### Search

  * `.DocSearch-SearchBar` - Search bar container
  * `.DocSearch-Form` - Search form
  * `.DocSearch-Input` - Search input
  * `.DocSearch-MagnifierLabel` - Search icon
  * `.DocSearch-LoadingIndicator` - Loading spinner

  ### Results

  * `.DocSearch-Dropdown` - Results container
  * `.DocSearch-Hits` - Results list
  * `.DocSearch-Hit` - Individual result
  * `.DocSearch-Hit-Container` - Hit content wrapper
  * `.DocSearch-Hit-icon` - Hit icon
  * `.DocSearch-Hit-title` - Hit title
  * `.DocSearch-Hit-path` - Hit breadcrumb

  ### Ask AI

  * `.DocSearch-AskAiScreen` - AI screen container
  * `.DocSearch-AskAiScreen-Response` - Response bubble
  * `.DocSearch-AskAiScreen-Query` - User question
  * `.DocSearch-Markdown-Content` - AI response content
  * `.DocSearch-AskAiScreen-RelatedSources` - Source links
  * `.DocSearch-AskAiScreen-ActionButton` - Action buttons

  ### Footer

  * `.DocSearch-Footer` - Footer container
  * `.DocSearch-Logo` - Algolia logo
  * `.DocSearch-Commands` - Keyboard shortcuts
</Accordion>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use CSS Variables" icon="swatchbook">
    Override variables instead of component classes for maintainability.
  </Card>

  <Card title="Test Both Themes" icon="circle-half-stroke">
    Ensure your customizations work in both light and dark modes.
  </Card>

  <Card title="Maintain Accessibility" icon="universal-access">
    Keep sufficient color contrast for readability.
  </Card>

  <Card title="Mobile First" icon="mobile">
    Test responsive behavior on various screen sizes.
  </Card>
</CardGroup>

## Debugging Styles

Use browser DevTools to inspect and override styles:

```javascript theme={null}
// Test variables in console
getComputedStyle(document.documentElement)
  .getPropertyValue('--docsearch-primary-color');

// Override temporarily
document.documentElement.style
  .setProperty('--docsearch-primary-color', '#ff0000');
```

<Note>
  DocSearch uses the `@docsearch/css` package which contains all base styles. Import it before adding custom styles.
</Note>

## Next Steps

<Card title="View Source Styles" icon="github" href="https://github.com/algolia/docsearch/tree/main/packages/docsearch-css">
  Explore the complete CSS source code on GitHub
</Card>