Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mintlify/components/llms.txt

Use this file to discover all available pages before exploring further.

The Search component provides a modal dialog with search functionality, keyboard navigation, and support for recent searches.

​
Basic Usage

import { useState } from 'react';
import { Search, SearchButton, SearchResult } from '@mintlify/components';

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false);
  const [results, setResults] = useState<SearchResult[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  const handleSearch = (query: string) => {
    if (!query) {
      setResults([]);
      return;
    }

    setIsLoading(true);
    fetch(`/api/search?q=${encodeURIComponent(query)}`)
      .then(res => res.json())
      .then(data => {
        setResults(data.results);
        setIsLoading(false);
      });
  };

  return (
    <>
      <SearchButton onClick={() => setIsOpen(true)} />
      <Search
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onSearch={handleSearch}
        results={results}
        isLoading={isLoading}
      />
    </>
  );
}

​
Search Component

The main search modal component with input, results display, and keyboard navigation.

​
Props

​
onSearch
(query: string) => void
required
Callback function called when the user types in the search input. Receives the current query string.
​
results
SearchResult[]
required
Array of search results to display. Each result should match the SearchResult type.
​
isOpen
boolean
required
Controls whether the search modal is visible.
​
onClose
() => void
required
Callback function called when the modal should close (ESC key, backdrop click, or result selection).
​
isLoading
boolean
default:"false"
When true, displays a loading state instead of results.
​
placeholder
string
default:"'Search...'"
Placeholder text displayed in the search input.
​
recentSearches
SearchResult[]
default:"[]"
Array of recent search results to display when the input is empty.
​
onSelectResult
(result: SearchResult, query: string) => void
Callback function called when a result is selected. Receives the selected result and the current query.
​
className
string
Additional CSS classes to apply to the modal wrapper.
​
emptyState
ReactNode
Custom component to display when no results are found. If not provided, a default empty state is shown.
​
loadingState
ReactNode
Custom component to display while loading. If not provided, a default loading spinner is shown.
​
position
'top' | 'center'
default:"'top'"
Position of the modal on screen. 'top' aligns the modal near the top of the viewport, 'center' centers it vertically.
​
paddingTop
string
default:"'64px'"
Distance from the top of the viewport when position is 'top'. Accepts any valid CSS value.

​
SearchResult Type

type SearchResult = {
  id: string;
  header: string;
  content: string;
  link: string;
  icon?: ReactNode;
  metadata?: {
    breadcrumbs?: string[];
    [key: string]: unknown;
  };
};
​
id
string
required
Unique identifier for the search result.
​
header
string
required
Main title text for the result.
​
content
string
required
Description or snippet text for the result.
​
link
string
required
URL or path for the result.
​
icon
ReactNode
Optional icon to display next to the result.
​
metadata.breadcrumbs
string[]
Optional array of breadcrumb strings displayed above the result header.

​
SearchButton Component

A styled button that opens the search modal, typically used with SearchProvider.

​
Props

​
showShortcut
boolean
default:"true"
Whether to display the keyboard shortcut text on the button.
​
shortcutText
string
default:"'⌘K'"
Text to display as the keyboard shortcut.
​
className
string
Additional CSS classes to apply to the button.
​
children
ReactNode
Content to display in the button. Defaults to "Search...".
Extends all standard HTML button attributes.

​
Example

<SearchButton 
  onClick={() => setIsOpen(true)}
  showShortcut={true}
  shortcutText="⌘K"
>
  Search documentation...
</SearchButton>

​
SearchProvider Component

A context provider that manages search state and keyboard shortcuts. Use this for app-wide search functionality.

​
Props

​
searchProps
Omit<SearchProps, 'isOpen' | 'onClose'>
required
Props to pass to the Search component (excluding isOpen and onClose which are managed by the provider).
​
shortcutKey
string
default:"'k'"
Key to use for the keyboard shortcut.
​
requireModifier
boolean
default:"true"
Whether the shortcut requires a modifier key (Cmd/Ctrl). When false, the key alone will trigger search (unless user is typing in an input).
​
children
ReactNode
required
Child components that can access the search context.

​
Example with Provider

import { SearchProvider, SearchButton } from '@mintlify/components';

function App() {
  const [results, setResults] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  const handleSearch = (query: string) => {
    // Your search implementation
  };

  return (
    <SearchProvider
      shortcutKey="k"
      requireModifier={true}
      searchProps={{
        onSearch: handleSearch,
        results,
        isLoading,
        placeholder: 'Search documentation...',
      }}
    >
      <div>
        <SearchButton />
        {/* Rest of your app */}
      </div>
    </SearchProvider>
  );
}

​
useSearch Hook

Access the search context from any component within SearchProvider. 
import { useSearch } from '@mintlify/components';

function MyComponent() {
  const search = useSearch();

  return (
    <button onClick={() => search?.open()}>
      Open Search
    </button>
  );
}
Context value: 
type SearchContextValue = {
  isOpen: boolean;
  open: () => void;
  close: () => void;
  toggle: () => void;
};

​
Features

​
Keyboard Navigation

The Search component includes full keyboard support:
  • ESC - Close the search modal
  • Arrow keys - Navigate through results
  • Enter - Select the highlighted result
  • Cmd/Ctrl + Enter - Select the first result
  • Tab - Prevented when results are visible (stays in search input)
  • Cmd/Ctrl + K - Global shortcut (when using SearchProvider)

​
Recent Searches

Display recent searches when the input is empty: 
const [recentSearches, setRecentSearches] = useState<SearchResult[]>([]);

const handleSelectResult = (result: SearchResult, query: string) => {
  // Add to recent searches (avoid duplicates)
  setRecentSearches(prev => {
    const filtered = prev.filter(item => item.id !== result.id);
    return [result, ...filtered].slice(0, 5); // Keep last 5
  });
};

<Search
  recentSearches={recentSearches}
  onSelectResult={handleSelectResult}
  // ... other props
/>

​
Custom States

Customize the loading and empty states: 
<Search
  emptyState={
    <div className="py-12 text-center">
      <p className="text-sm font-semibold">No matches found</p>
      <p className="text-xs text-stone-500">Try different keywords</p>
    </div>
  }
  loadingState={
    <div className="py-12 text-center">
      <div className="animate-spin">⏳</div>
      <p className="text-sm">Searching...</p>
    </div>
  }
  // ... other props
/>
Control where the modal appears: 
{/* Near the top of the viewport */}
<Search position="top" paddingTop="64px" />

{/* Centered vertically */}
<Search position="center" />

​
Source Code References

  • Search component: packages/components/src/components/search/search.tsx:113
  • SearchButton component: packages/components/src/components/search/button.tsx:11
  • SearchProvider component: packages/components/src/components/search/provider.tsx:27
  • SearchResult type: packages/components/src/components/search/search.tsx:30