Built-in Search

Fumadocs supports document search with Orama, It is the default but also the recommended option since it can be self-hosted and totally free.

Setup

Host the server for handling search requests.

From Source

Create the server from source object.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source, {
  // https://docs.orama.com/docs/orama-js/supported-languages
  language: 'english',
});

From Search Indexes

Create the server from search indexes, each index needs a structuredData field.

Usually, it is provided by your content source (e.g. Fumadocs MDX). You can also extract it from Markdown/MDX document using the Remark Structure plugin.

import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';

export const { GET } = createSearchAPI('advanced', {
  language: 'english',
  indexes: source.getPages().map((page) => ({
    title: page.data.title,
    description: page.data.description,
    url: page.url,
    id: page.url,
    structuredData: page.data.structuredData,
  })),
});

Searching Documents

You can search documents using:

• Fumadocs UI: Supported out-of-the-box, see Search UI for details.
• Search Client:

import { useDocsSearch } from 'fumadocs-core/search/client';
import { fetchClient } from 'fumadocs-core/search/client/fetch';

const client = useDocsSearch({
  client: fetchClient(),
});

Configurations

Tag Filter

Support filtering results 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';

const server = createFromSource(source, {
  buildIndex(page) {
    return {
      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 fetchClient.

import { useDocsSearch } from 'fumadocs-core/search/client';
import { fetchClient } from 'fumadocs-core/search/client/fetch';

const client = useDocsSearch({
  client: fetchClient({
    tag: '<value>',
  }),
});

Static Mode

To support usage with static site, use staticGET from search server and make the route static or pre-rendered.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

// statically cached
export const revalidate = false;
export const { staticGET: GET } = createFromSource(source);

and update your search clients:

• Fumadocs UI: use static client on Search UI.

• Search Client: use oramaStaticClient instead of fetchClient.

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

  Prop

  Type

  from?string

  initOrama?function

  tag?union

  locale?string

  search?union

Internationalization

Make sure your language is on the Orama Supported Languages list.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

const server = createFromSource(source, {
  localeMap: {
    // [locale]: Orama options
    ru: { language: 'russian' },
    en: { language: 'english' },
  },
});

For Static Mode, you should configure from client-side instead:

import { useDocsSearch } from 'fumadocs-core/search/client';
import { oramaStaticClient } from 'fumadocs-core/search/client/orama-static';
import { create } from '@orama/orama';

function initOrama(locale?: string) {
  return create({
    schema: { _: 'string' },
    language: locale === 'ru' ? 'russian' : 'english',
  });
}

function Search() {
  const client = useDocsSearch({
    client: oramaStaticClient({
      initOrama,
    }),
  });

  // ...
}

Special Languages

Chinese and Japanese require additional configurations:

npm i @orama/tokenizers

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { createTokenizer } from '@orama/tokenizers/mandarin';

export const { GET } = createFromSource(source, {
  localeMap: {
    // [locale]: Orama options
    cn: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
  },
});

and update your search clients:

• Fumadocs UI: No changes needed, Fumadocs UI handles this when you have i18n configured correctly.
• Search Client: Add locale to the search client, this will only allow pages with specified locale to be searchable by the user.

import { useDocsSearch } from 'fumadocs-core/search/client';
import { fetchClient } from 'fumadocs-core/search/client/fetch';

const { search, setSearch, query } = useDocsSearch({
  client: fetchClient({
    locale: 'cn',
  }),
});

Headless

You can host the search server on other backend such as Express and Elysia.

import { initAdvancedSearch } from 'fumadocs-core/search/server';

const server = initAdvancedSearch({
  // you still have to pass indexes
});

server.search('query', {
  // you can specify `locale` and `tag` here
});