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