Built-in Search

Fumadocs supports searching document based on Orama.

As the built-in search of Fumadocs, It is the default but also recommended option since it's easier to setup and totally free.

If you're using a CMS, you may use the API provided by the CMS instead.

Advanced Search

Returns a detailed result with matching headings and contents.

It accepts structured data processed from a markdown/MDX document, and index it with Orama. You can extract the structured data using the Structure remark plugin.

It cannot extract content from rehype plugin generated content (remark plugins are supported).

Usage

From Source

Create a route handler from Source API.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
 
export const { GET } = createFromSource(source);

From Search Indexes

Pass search indexes to the function, see type information for required properties.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
 
export const { GET } = createSearchAPI('advanced', {
  indexes: source.getPages().map((page) => ({
    title: page.data.title,
    description: page.data.description,
    url: page.url,
    id: page.url,
    structuredData: page.data.structuredData,
  })),
});

Client

You can query it using headless search client.

import { useDocsSearch } from 'fumadocs-core/search/client';
 
const client = useDocsSearch({
  type: 'fetch',
});

Or use Fumadocs UI, which includes a built-in search UI.

Tag Filter

It's useful for implementing multi-docs similar to this documentation.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
 
export const { GET } = createFromSource(source, (page) => ({
  title: page.data.title,
  description: page.data.description,
  url: page.url,
  id: page.url,
  structuredData: page.data.structuredData,
  tag: '<value>',
}));

For Fumadocs UI

Remember to configure Tag Filter on Search UI.

You don't need to follow the steps below if you're using the built-in Search UI.

On your search client, pass a tag to the hook.

import { useDocsSearch } from 'fumadocs-core/search/client';
 
// Pass `tag` in your custom search dialog
const client = useDocsSearch(
  {
    type: 'fetch',
  },
  undefined, // locale code, can be `undefined`
  'tag',
);

Internationalization

Update the route handler (From Source)

You don't need to change anything, it handles i18n automatically.

Update the route handler (From Search Indexes)

Use createI18nSearchAPI for i18n functionality.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createI18nSearchAPI } from 'fumadocs-core/search/server';
import { i18n } from '@/lib/i18n';
 
export const { GET } = createI18nSearchAPI('advanced', {
  i18n,
  indexes: source.getLanguages().flatMap((entry) =>
    entry.pages.map((page) => ({
      title: page.data.title,
      description: page.data.description,
      structuredData: page.data.structuredData,
      id: page.url,
      url: page.url,
      locale: entry.language,
    })),
  ),
});

Update search client

For Fumadocs UI

You can ignore this, Fumadocs UI handles this when you have i18n configured correctly.

Add locale to the search client, this will only allow pages with specified locale to be searchable by the user.

const { search, setSearch, query } = useDocsSearch(
  {
    type: 'fetch',
  },
  locale,
);

Chinese

Orama requires extra configurations for Chinese, Japanese, and some other languages.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
// @ts-expect-error -- untyped
import { createTokenizer } from '@orama/tokenizers/mandarin';
import { stopwords } from '@orama/stopwords/mandarin';
 
export const { GET, search } = createFromSource(source, undefined, {
  localeMap: {
    cn: {
      tokenizer: await createTokenizer({
        stopWords: stopwords,
      }),
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
  },
});

See Orama Docs for more details.

Static Search

To work with Next.js static export, use staticGET from search server.

app/api/search/route.ts

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
 
// it should be cached forever
export const revalidate = false;
 
export const { staticGET: GET } = createFromSource(source);

staticGET is also available on createSearchAPI.

Search Client

On your search client, use static instead of fetch.

import { useDocsSearch } from 'fumadocs-core/search/client';
 
const client = useDocsSearch({
  type: 'static',
});

Search UI

You can pass search options from the Root Provider.

See Search UI options.

Be Careful

Static Search requires clients to download the exported search indexes. For large docs sites, its size can be really big.

Especially with i18n (e.g. Chinese tokenizers), the bundle size of tokenizers can exceed ~500MB. You should use 3rd party solutions like Algolia for these cases.

Simple Search

Index with the raw content of document.

app/api/search/route.ts

import { allDocs } from 'content-collections';
import { createSearchAPI } from 'fumadocs-core/search/server';
 
export const { GET } = createSearchAPI('simple', {
  indexes: allDocs.map((docs) => ({
    title: docs.title,
    content: docs.content, // Raw Content
    url: docs.url,
  })),
});

Search Client

useDocsSearch is a hook to search documents using the built-in search clients.

Client

Choose the client to use.

import { useDocsSearch } from 'fumadocs-core/search/client';
 
const client = useDocsSearch({
  type: 'static',
  // you can pass options for the client you specified
});

Type	Description
`fetch` (default)	send HTTP request to a search server with `fetch`
`static`	Load search map on client-side and query them
`algolia`	Use Algolia Search (See Algolia

Return Type

Prop	Type	Description
`query`	`Query`	Query status and results
`search`	`string`	Searching text (not debounced)
`setSearch`	`(v: string) => void`	Set searching text

Response Data

Type
`empty`	If the searching text is empty or blank
`SortedResult[]`	Array of matching pages, headings and contents.

Custom Algorithm

You can port your own search algorithm by returning a list of SortedResult from your custom /api/search/route.ts route handler (API Endpoint). You can also integrate it with Fumadocs UI.

Prop	Type	Default
`id`	`string`	-
`url`	`string`	-
`type`	`"page" \| "heading" \| "text"`	-
`content`	`string`	-

Headless

You can host the search server on Express or Elysia, without Next.js.

import { initAdvancedSearch } from 'fumadocs-core/search/server';
 
const server = initAdvancedSearch({
  // options
});
 
server.search('query', {
  // you can specify `locale` and `tag` here
});

Update the route handler (From Source)

Update the route handler (From Search Indexes)

Update search client

On this page