Document Search

Fumadocs UI gives you the visual layer for search, while the underlying search implementation is documented in Fumadocs Core.

Start with Document Search.

Search Interface

The default dialog can be opened with ⌘ K or Ctrl K.

Basic Configuration

Search UI settings live on the Root Provider in your root layout.

If you do not provide anything custom, Fumadocs uses the default fetch Search Client backed by Orama.

Empty-State Links

You can add your own quick links to the search dialog. These entries appear when the user has not typed a query yet.

app/layout.tsx

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    links: [
      ['Home', '/'],
      ['Docs', '/docs'],
    ],
  }}
>
  {children}
</RootProvider>;

Turning Search Off

If you do not want document search at all, disable it on the root provider.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    enabled: false,
  }}
>
  {children}
</RootProvider>;

Custom Hotkeys

The keyboard shortcut for opening the dialog is configurable.

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 Filters

The UI can expose filter controls as well. Before doing that, make sure your search backend already supports Tag Filter.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      defaultTag: 'value',
      tags: [
        {
          name: 'Tag Name',
          value: 'value',
        },
      ],
    },
  }}
>
  {children}
</RootProvider>;

Client Options

Search client options can be passed through directly, for example when changing the API endpoint used by an Orama server.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      api: '/api/search/docs',
    },
  }}
>
  {children}
</RootProvider>;

Replacing the Dialog

If the default search dialog is close to what you need, you can wrap it and add your own logic.

components/search.tsx

'use client';
import SearchDialog from 'fumadocs-ui/components/dialog/search-default';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';

export default function CustomDialog(props: SharedProps) {
  // your own logic here
  return <SearchDialog {...props} />;
}

To hand that custom dialog to the Root Provider, create a client wrapper:

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

Then swap your previous Root Provider usage for this wrapper:

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

Alternative Search Providers

Algolia

For the full setup flow, see Integrate Algolia Search.

In many cases we recommend building against Algolia's own client-side SDK, but if you prefer, the built-in dialog UI can still be connected to it.

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.
Replace the default search dialog with your new component.

Note

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

Tag Filter

Just like the default client, the Algolia dialog also supports Tag Filter.

components/search.tsx

import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

<SearchDialog
  defaultTag="value"
  tags={[
    {
      name: 'Tag Name',
      value: 'value',
    },
  ]}
/>;

Orama Cloud

Setup instructions are available at 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 />;
}

Replace endpoint, apiKey with your desired values.
Replace the default search dialog with your new component.

Community Integrations

The community also maintains additional integrations.

Trieve Search

Built-in UI Component

If you want the built-in search dialog UI without the default wiring, use the SearchDialog component directly.

import {
  SearchDialog,
  type SharedProps,
} from 'fumadocs-ui/components/dialog/search';

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} />;
}

Unstable

It is an internal API, might break during iterations

Fumadocs UI gives you the visual layer for search, while the underlying search implementation is documented in Fumadocs Core.

Start with Document Search.

Search Interface

The default dialog can be opened with ⌘ K or Ctrl K.

Basic Configuration

Search UI settings live on the Root Provider in your root layout.

If you do not provide anything custom, Fumadocs uses the default fetch Search Client backed by Orama.

Empty-State Links

You can add your own quick links to the search dialog. These entries appear when the user has not typed a query yet.

app/layout.tsx

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    links: [
      ['Home', '/'],
      ['Docs', '/docs'],
    ],
  }}
>
  {children}
</RootProvider>;

Turning Search Off

If you do not want document search at all, disable it on the root provider.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    enabled: false,
  }}
>
  {children}
</RootProvider>;

Custom Hotkeys

The keyboard shortcut for opening the dialog is configurable.

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 Filters

The UI can expose filter controls as well. Before doing that, make sure your search backend already supports Tag Filter.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      defaultTag: 'value',
      tags: [
        {
          name: 'Tag Name',
          value: 'value',
        },
      ],
    },
  }}
>
  {children}
</RootProvider>;

Client Options

Search client options can be passed through directly, for example when changing the API endpoint used by an Orama server.

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      api: '/api/search/docs',
    },
  }}
>
  {children}
</RootProvider>;

Replacing the Dialog

If the default search dialog is close to what you need, you can wrap it and add your own logic.

components/search.tsx

'use client';
import SearchDialog from 'fumadocs-ui/components/dialog/search-default';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';

export default function CustomDialog(props: SharedProps) {
  // your own logic here
  return <SearchDialog {...props} />;
}

To hand that custom dialog to the Root Provider, create a client wrapper:

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

Then swap your previous Root Provider usage for this wrapper:

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

Alternative Search Providers

Algolia

For the full setup flow, see Integrate Algolia Search.

In many cases we recommend building against Algolia's own client-side SDK, but if you prefer, the built-in dialog UI can still be connected to it.

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.
Replace the default search dialog with your new component.

Note

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

Tag Filter

Just like the default client, the Algolia dialog also supports Tag Filter.

components/search.tsx

import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

<SearchDialog
  defaultTag="value"
  tags={[
    {
      name: 'Tag Name',
      value: 'value',
    },
  ]}
/>;

Orama Cloud

Setup instructions are available at 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 />;
}

Replace endpoint, apiKey with your desired values.
Replace the default search dialog with your new component.

Community Integrations

The community also maintains additional integrations.

Trieve Search

Built-in UI Component

If you want the built-in search dialog UI without the default wiring, use the SearchDialog component directly.

import {
  SearchDialog,
  type SharedProps,
} from 'fumadocs-ui/components/dialog/search';

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} />;
}

Unstable

It is an internal API, might break during iterations

Author

Categories

More Posts

Writing with Markdown and MDX

Yes or No Tarot List — A 78-Card Direction Guide

Orelune Tarot Series: Seven of Wands - Courage Under Pressure and Steady Defense

Newsletter

Document Search

Author

Categories

More Posts

Writing with Markdown and MDX

Yes or No Tarot List — A 78-Card Direction Guide

Orelune Tarot Series: Seven of Wands - Courage Under Pressure and Steady Defense

Newsletter