Styling - DocSearch

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:

import '@docsearch/css';

import '@docsearch/css';

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

Apply a Theme

DocSearch supports light and dark themes:

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:

: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;
}

All CSS variables are scoped to :root and can be overridden at any level.

Color Variables

Primary Colors

Control brand colors throughout the interface:

: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

: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

: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

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

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:

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 ... */
}

Complete Dark Theme Variables

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);
}

Component Styling

Search Button

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

.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);
}

Resize and position the modal:

:root {
  --docsearch-modal-width: 900px;
  --docsearch-modal-height: 700px;
}

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

Search Input

.DocSearch-Input {
  font-size: 18px;
  color: var(--docsearch-text-color);
}

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

Search Results

Style individual hits:

.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;
}

.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

.DocSearch-AskAiScreen-Container {
  padding: 24px;
}

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

Messages

.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

.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

.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

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

@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

/* 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

: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

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

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>
  )}
/>

<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

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

.DocSearch-Footer - Footer container
.DocSearch-Logo - Algolia logo
.DocSearch-Commands - Keyboard shortcuts

Best Practices

Use CSS Variables

Override variables instead of component classes for maintainability.

Test Both Themes

Ensure your customizations work in both light and dark modes.

Maintain Accessibility

Keep sufficient color contrast for readability.

Mobile First

Test responsive behavior on various screen sizes.

Debugging Styles

Use browser DevTools to inspect and override styles:

// Test variables in console
getComputedStyle(document.documentElement)
  .getPropertyValue('--docsearch-primary-color');

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

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

Next Steps

View Source Styles

Explore the complete CSS source code on GitHub

​Quick Start

​Import Default Styles

​Apply a Theme

​CSS Variables

​Color Variables

​Primary Colors

​Text Colors

​Background Colors

​Semantic Colors

​Dark Theme

​Component Styling

​Search Button

​Search Modal

​Search Input

​Search Results

​Footer

​Ask AI Styling

​Ask AI Screen

​Messages

​Markdown Content

​Source Citations

​Action Buttons

​Responsive Styles

​Custom Themes Example

​Brand Integration

​High Contrast Theme

​Minimal Theme

​Advanced Customization

​Custom Hit Component

​Custom Footer

​CSS Class Reference

​Container

​Search

​Results

​Ask AI

​Footer

​Best Practices

Use CSS Variables

Test Both Themes

Maintain Accessibility

Mobile First

​Debugging Styles

​Next Steps

View Source Styles

Quick Start

Import Default Styles

Apply a Theme

CSS Variables

Color Variables

Primary Colors

Text Colors

Background Colors

Semantic Colors

Dark Theme

Component Styling

Search Button

Search Modal

Search Input

Search Results

Footer

Ask AI Styling

Ask AI Screen

Messages

Markdown Content

Source Citations

Action Buttons

Responsive Styles

Custom Themes Example

Brand Integration

High Contrast Theme

Minimal Theme

Advanced Customization

Custom Hit Component

Custom Footer

CSS Class Reference

Container

Search

Results

Ask AI

Footer

Best Practices

Debugging Styles

Next Steps