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.

Setup

You can create the search route handler from the source object, or search indexes.

From Source

Create a route handler from Source object.

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.

Each index needs a structuredData field. Usually, it has been provided by your content source (e.g. Fumadocs MDX).

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

It can also be processed from Markdown/MDX document using the Structure remark plugin.

Client

You can query it using:

• Fumadocs UI: The built-in Search UI supports it out-of-the-box.

• Search Client:

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

  Prop	Type	Default
  type	"fetch"	-
  api?	string	-

Tag Filter

Support filtering by tag, it's useful for implementing multi-docs similar to this documentation.

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,
  // use your desired value, like page.slugs[0]
  tag: '<value>',
}));

and update your search client:

• Fumadocs UI: Configure Tag Filter on Search UI.

• 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',
  );

Index by Content

Index with the raw content of document (unrecommended).

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

Internationalization

• createFromSource():

  Configure i18n on source object (in loader function).

  import { i18n } from '@/lib/i18n';
  import { loader } from 'fumadocs-core/source';
   
  export const source = loader({
    i18n,
  });

• createSearchAPI():

  Use createI18nSearchAPI for i18n functionality.

  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(({ language, pages }) =>
      pages.map((page) => ({
        title: page.data.title,
        description: page.data.description,
        structuredData: page.data.structuredData,
        id: page.url,
        url: page.url,
        locale: language,
      })),
    ),
  });

Update Search Client

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

Special Languages

If your language is not on the Orama Supported Languages list, you have to configure them manually:

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { createTokenizer } from '@orama/tokenizers/mandarin';
 
export const { GET } = createFromSource(source, undefined, {
  localeMap: {
    // you can customise search configs for specific locales, like:
    // [locale]: Orama options
 
    cn: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
 
    // use the English tokenizer
    'custom-locale': 'english',
  },
});

See Orama Docs for more details.

Static Export

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

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

and update your search clients:

• Fumadocs UI: See Static Export guide.

• Search Client:

  On your search client, use static instead of fetch.

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

  Prop	Type	Default
  type	"static"	-
  from?	string	-
  initOrama?	((locale?: string | undefined) => AnyOrama | Promise<AnyOrama>)	-

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.

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