Fumadocs

Search

Implement document search in your docs

Fumadocs UI provides a good-looking search dialog out-of-the-box.

Open with ⌘ K or Ctrl K.

Configure Document Search.

Search Dialog

You can customize the search dialog from Root Provider.

When not specified, it uses the Default Search Client powered by Flexsearch. It is lazy loaded using next/dynamic. This allows a better initial loading performance.

Add custom link items to search dialog. They are shown as fallbacks when the query is empty.

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    links: [
      ['Home', '/'],
      ['Docs', '/docs'],
    ],
  }}
>
  ...
</RootProvider>;

To opt-out of document search, disable it from root provider.

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    enabled: false,
  }}
>
  ...
</RootProvider>;

Hot Keys

Customise the hot keys to trigger search dialog.

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    hotKey: [
      {
        display: 'K',
        key: 'k', // key code, or a function determining whether the key is pressed
      },
    ],
  }}
>
  ...
</RootProvider>;

Tag Filter

Configure tag filtering on the default search client.

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    options: {
      defaultTag: 'value',
      tags: [
        {
          name: 'Tag Name',
          value: 'value',
        },
      ],
    },
  }}
>
  ...
</RootProvider>;

Algolia

For the setup guide, see Integrate Algolia Search. Make sure you have algoliasearch installed on your project.

While generally we recommend building your own search with their client-side SDK, you can also plug the built-in dialog interface.

Create a separate client component for the dialog.

components/search.tsx
'use client';
import algo from 'algoliasearch/lite';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';
 
const client = algo(appId, apiKey);
const index = client.initIndex(indexName);
 
export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog index={index} {...props} />;
}

Replace appId, apiKey and indexName with your desired values.

Create a new provider component and use it instead of the original Root Provider in the root layout.

Inside the new provider, lazy load the dialog and pass it to Root Provider.

app/provider.tsx
'use client';
import { RootProvider } from 'fumadocs-ui/provider';
import dynamic from 'next/dynamic';
import type { ReactNode } from 'react';
 
const SearchDialog = dynamic(() => import('@/components/search'));
 
export function Provider({ children }: { children: ReactNode }) {
  return (
    <RootProvider
      search={{
        SearchDialog,
      }}
    >
      {children}
    </RootProvider>
  );
}
Note

The built-in implementation doesn't use instant search (their official javascript client).

Tag Filter

Same as the default search client, you can configure tag filtering with the tags prop.

components/search.tsx
import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';
 
<SearchDialog
  defaultTag="value"
  tags={[
    {
      name: 'Tag Name',
      value: 'value',
    },
  ]}
/>;

Other Solutions

To use other search solutions such as ElasticSearch, you can replace the default dialog with your own.

Since you cannot pass a function to client components, wrap the provider in another client component, and use the new provider in your root layout instead.

'use client';
 
import { RootProvider } from 'fumadocs-ui/provider';
import dynamic from 'next/dynamic';
 
const SearchDialog = dynamic(() => import('@/components/search'));
 
export function Provider({ children }: { children: React.ReactNode }) {
  return (
    <RootProvider
      search={{
        SearchDialog,
      }}
    >
      {children}
    </RootProvider>
  );
}

Built-in UI

If you want to use the built-in search dialog UI instead of building your own, you may use the SearchDialog component.

import {
  SearchDialog,
  type SharedProps
} from 'fumadocs-ui/components/dialog/search'
 
export default function CustomSearchDialog(props: SharedProps) { ... }
Unstable

It is an internal API, might break during iterations

Last updated on

Previous

Manual Installation

Next

Theming

On this page

Search DialogCustom LinksDisable SearchHot KeysTag FilterAlgoliaTag FilterOther SolutionsBuilt-in UI
Edit on Github