Search

Implement document search in your docs

Search UI

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

Open with K or Ctrl K.

Configurations

You can customize search UI from the Root Provider component in root layout.

When not specified, it uses the Default fetch Search Client powered by Orama. 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.

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

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

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    enabled: false,
  }}
>
  {children}
</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
      },
    ],
  }}
>
  {children}
</RootProvider>;

Tag Filter

Configure Tag Filter on the default search client.

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

Search Options

Pass options to the search client. For example, using static client:

import { RootProvider } from 'fumadocs-ui/root-provider';
 
<RootProvider
  search={{
    options: {
      type: 'static',
    },
  }}
>
  {children}
</RootProvider>;

Replace Search Dialog

You can replace the default Search Dialog with:

components/search.tsx
'use client';
import SearchDialog from 'fumadocs-ui/components/dialog/search-default';
 
export default function CustomDialog(props) {
  // your own logic here
  return <SearchDialog {...props} />;
}

To pass it to the Root Provider, you need a wrapper with use client directive.

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')); // lazy load
 
export function Provider({ children }: { children: ReactNode }) {
  return (
    <RootProvider
      search={{
        SearchDialog,
      }}
    >
      {children}
    </RootProvider>
  );
}

Use it instead of your previous Root Provider

layout.tsx
import { Provider } from './provider';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  );
}

Tag Filter

Same as the default search client, you can configure Tag Filter on the dialog.

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 Algolia and ElasticSearch, you can replace the default dialog with your own.

Algolia

For the setup guide, see Integrate Algolia Search.

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

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} />;
}
  1. Replace appId, apiKey and indexName with your desired values.

  2. Replace the default search dialog with your new component.

Note

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

Orama Cloud

For the setup guide, see Integrate Orama Cloud.

components/search.tsx
'use client';
 
import { OramaClient } from '@oramacloud/client';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-orama';
 
const client = new OramaClient({
  endpoint: 'endpoint',
  api_key: 'apiKey',
});
 
export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} client={client} showOrama />;
}
  1. Replace endpoint, apiKey with your desired values.
  2. Replace the default search dialog with your new component.

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

Edit on GitHub

Last updated on

On this page