Search Client Integrations

Copyexport function useDocsSearch(
  clientOptions: ClientPreset & {
    /**
     * The debounced delay for performing a search (in ms).
     * .
     * @defaultValue 100
     */
    delayMs?: number;
 
    /**
     * still perform search even if query is empty.
     *
     * @defaultValue false
     */
    allowEmpty?: boolean;
  },
  customDeps?: DependencyList,
): UseDocsSearch {

Copyinterface UseDocsSearch {
  search: string;
  setSearch: (v: string) => void;
  query: {
    isLoading: boolean;
    data?: SortedResult[] | 'empty';
    error?: Error;
  };
}

Copyexport type ClientPreset =
  | ({
      /**
       * @deprecated Pass `client: fetchClient(...)` instead.
       */
      type: 'fetch';
    } & FetchOptions)
  | ({
      /**
       * @deprecated Pass `client: oramaStaticClient(...)` instead.
       */
      type: 'static';
    } & StaticOptions)
  | ({
      /**
       * @deprecated Pass `client: algoliaClient(...)` instead.
       */
      type: 'algolia';
    } & AlgoliaOptions)
  | ({
      /**
       * @deprecated Pass `client: oramaCloudClient(...)` instead.
       */
      type: 'orama-cloud';
    } & OramaCloudOptions)
  | ({
      /**
       * @deprecated Pass `client: oramaCloudLegacyClient(...)` instead.
       */
      type: 'orama-cloud-legacy';
    } & OramaCloudLegacyOptions)
  | ({
      /**
       * @deprecated Pass `client: flexsearchStaticClient(...)` instead.
       */
      type: 'flexsearch-static';
    } & FlexsearchStaticOptions)
  | ({
      /**
       * @deprecated Use `createMixedbreadSearchAPI` from `fumadocs-core/search/mixedbread` instead.
       * This client-side approach exposes your API key in the browser.
       * The server-side approach keeps the key secure and uses `client: fetchClient(...)` on the client.
       */
      type: 'mixedbread';
    } & MixedbreadOptions)
  | {
      client: SearchClient;
    };

Copyconst { delayMs = 100, allowEmpty = false, ...clientRest } = clientOptions;
const [search, setSearch] = useState('');
const [results, setResults] = useState<SortedResult[] | 'empty'>('empty');
const [error, setError] = useState<Error>();
const [isLoading, setIsLoading] = useState(false);
const debouncedValue = useDebounce(search, delayMs);

Copyconst [activeDeps, setActiveDeps] = useState<DependencyList | null>(null);
const activeTaskRef = useRef<{
  deps: DependencyList;
  start: () => void;
  interrupt: boolean;
} | null>(null);
 
if (
  !isEqualShallow(activeDeps, deps) &&
  (!activeTaskRef.current || !isEqualShallow(activeTaskRef.current.deps, deps))
) {
  if (activeTaskRef.current) activeTaskRef.current.interrupt = true;
 
  activeTaskRef.current = {
    deps,
    interrupt: false,
    async start() {
      try {
        setIsLoading(true);
 
        let res: SortedResult[] | 'empty';
        if (debouncedValue.length === 0 && !allowEmpty) res = 'empty';
        else res = await (await client).search(debouncedValue);
 
        if (!this.interrupt) {
          setActiveDeps(deps);
          setError(undefined);
          setResults(res);
        }
      } catch (err) {
        if (!this.interrupt) setError(err as Error);
      } finally {
        if (!this.interrupt) setIsLoading(false);
      }
    },
  };
  void activeTaskRef.current.start();
}

Copyconst globalCache = new Map();
 
export function fetchClient({
  api = '/api/search',
  locale,
  tag,
  cache = globalCache,
}: FetchOptions = {}): SearchClient {
  return {
    deps: [api, locale, tag],
    async search(query) {
      const url = new URL(api, window.location.origin);
      url.searchParams.set('query', query);
      if (locale) url.searchParams.set('locale', locale);
      if (tag) url.searchParams.set('tag', Array.isArray(tag) ? tag.join(',') : tag);
 
      const key = url.toString();
      const cached = cache.get(key);
      if (cached) return cached;
 
      const res = await fetch(url);
      if (!res.ok) throw new Error(await res.text());
      const result = (await res.json()) as SortedResult[];
      cache.set(key, result);
      return result;
    },
  };

Copyasync search(query) {
  const url = new URL(api, window.location.origin);
  url.searchParams.set('query', query);
  if (locale) url.searchParams.set('locale', locale);
  if (tag) url.searchParams.set('tag', Array.isArray(tag) ? tag.join(',') : tag);
 

Copyexport default function DefaultSearchDialog({
  defaultTag,
  tags = [],
  api,
  delayMs,
  allowClear = false,
  links = [],
  footer,
  ...props
}: DefaultSearchDialogProps) {
  const { locale } = useI18n();
  const [tag, setTag] = useState(defaultTag);
  const { search, setSearch, query } = useDocsSearch({
    client: fetchClient({
      api,
      locale,
      tag,
    }),
    delayMs,
  });

Copyconst defaultItems = useMemo<SortedResult[] | null>(() => {
  if (links.length === 0) return null;
  return links.map(([name, link]) => ({
    type: 'page',
    id: name,
    content: name,
    url: link,
  }));
}, [links]);

Copy<SearchDialogList items={query.data !== 'empty' ? query.data : defaultItems} />

Copyexport function oramaCloudClient(options: OramaCloudOptions): SearchClient {
  const { index = 'default', client, params: extraParams, tag } = options;
 
  return {
    deps: [index, client, tag],

Copyexport function oramaCloudLegacyClient(options: OramaCloudLegacyOptions): SearchClient {
  const { index = 'default', client, params: extraParams = {}, tag } = options;
 
  return {
    deps: [index, client, tag],

Copyif (index === 'crawler') {
  const result = await client.search({
    datasources: [],
    ...extraParams,
    term: query,
    where: {
      category: tag
        ? {
            eq: tag.slice(0, 1).toUpperCase() + tag.slice(1),
          }
        : undefined,
      ...extraParams?.where,
    },
    limit: 10,
  });

Copyconst result = await client.search({
  datasources: [],
  ...extraParams,
  term: query,
  limit: 20,
  where: removeUndefined({
    tag,
    ...extraParams?.where,
  }),
  groupBy: {
    properties: ['page_id'],
    max_results: 7,
    ...extraParams?.groupBy,
  },
});

Copyexport default function OramaSearchDialog({
  client,
  searchOptions,
  tags = [],
  defaultTag,
  showOrama = true,
  allowClear = false,
  index,
  footer,
  links = [],
  ...props
}: OramaSearchDialogProps) {
  const { locale } = useI18n();
  const [tag, setTag] = useState(defaultTag);
  const { search, setSearch, query } = useDocsSearch({
    client: oramaCloudClient({
      client,
      index,
      params: searchOptions,
      locale,
      tag,
    }),
  });

Copyexport interface StaticOptions {
  /**
   * Where to download exported search indexes (URL)
   *
   * @defaultValue '/api/search'
   */
  from?: string;
 
  initOrama?: (locale?: string) => AnyOrama | Promise<AnyOrama>;
 
  /**
   * Filter results with specific tag(s).
   */
  tag?: string | string[];
 
  /**
   * Filter by locale (unsupported at the moment)
   */
  locale?: string;
 
  /**
   * extra options for search
   */
  search?: Partial<SearchParams<Orama<unknown>>>;
}

Copyasync function loadDB(
  from: string,
  initOrama: StaticOptions['initOrama'] = (locale) =>
    create({ schema: { _: 'string' }, language: locale }),
): Promise<Database> {
  const res = await fetch(from);
 
  if (!res.ok)
    throw new Error(
      `failed to fetch exported search indexes from ${from}, make sure the search database is exported and available for client.`,
    );
 
  const data = (await res.json()) as ExportedData;
  const dbs: Database = new Map();
 
  if (data.type === 'i18n') {
    await Promise.all(
      Object.entries(data.data).map(async ([k, v]) => {
        const db = await initOrama(k);
 
        load(db, v);
        dbs.set(k, {
          type: v.type,
          db,
        });
      }),
    );
  } else {
    const db = await initOrama();
    load(db, data);
    dbs.set('', {
      type: data.type,
      db,
    });
  }
 
  return dbs;
}

Copyexport async function searchSimple(
  db: Orama<typeof simpleSchema>,
  query: string,
  params: Partial<SearchParams<Orama<typeof simpleSchema>, SimpleDocument>> = {},
): Promise<SortedResult[]> {
  const highlighter = createContentHighlighter(query);
  const result = await search(db, {
    term: query,
    tolerance: 1,
    ...params,
    boost: {
      title: 2,
      ...('boost' in params ? params.boost : undefined),
    },
  });

Copyexport async function searchAdvanced(
  db: Orama<typeof advancedSchema>,
  query: string,
  tag: string | string[] = [],
  {
    mode = 'fulltext',
    ...override
  }: Partial<SearchParams<Orama<typeof advancedSchema>, AdvancedDocument>> = {},
): Promise<SortedResult[]> {
  if (typeof tag === 'string') tag = [tag];
 
  const params = {
    limit: 60,
    mode,
    ...override,
    where: removeUndefined({
      tags:
        tag.length > 0
          ? {
              containsAll: tag,
            }
          : undefined,
      ...override.where,
    }),
    groupBy: {
      properties: ['page_id'],
      maxResult: 8,
      ...override.groupBy,
    },
    properties: mode === 'fulltext' ? ['content'] : ['content', 'embeddings'],
  } as SearchParams<typeof db, AdvancedDocument>;

Copyexport interface FlexsearchStaticOptions {
  /**
   * @defaultValue `/api/search`
   */
  from?: string;
  locale?: string;
  tag?: string | string[];
}

Copyfunction initDocument(data: Record<string, string>) {
  const document = createDocument();
  for (const [k, v] of Object.entries(data)) document.import(k, v);
  return document;
}

Copyasync function init(from: string) {
  const res = await fetch(from);
 
  if (!res.ok)
    throw new Error(
      `failed to fetch exported search indexes from ${from}, make sure the search database is exported and available for client.`,
    );
 
  const data = (await res.json()) as ExportedData;
  const dbs = new Map<string, Document<Doc>>();
 
  if (data.type === 'i18n') {
    for (const [locale, map] of Object.entries(data.raw)) {
      dbs.set(locale, initDocument(map));
    }
 
    return dbs;
  } else {
    dbs.set('', initDocument(data.raw));
  }
 
  return dbs;

Copyexport interface AlgoliaOptions {
  indexName: string;
  client: LiteClient;
 
  /**
   * Filter results with specific tag.
   */
  tag?: string;
 
  locale?: string;
 
  onSearch?: (
    query: string,
    tag?: string,
    locale?: string,
  ) => Promise<{
    results: SearchResponse<BaseIndex>[];
  }>;
}

Copyconst result = onSearch
  ? await onSearch(query, tag, locale)
  : await client.searchForHits<BaseIndex>({
      requests: [
        {
          type: 'default',
          indexName,
          query,
          distinct: 5,
          hitsPerPage: 10,
          filters: tag ? `tag:${tag}` : undefined,
        },
      ],
    });
 

Copyfunction groupResults(hits: Hit<BaseIndex>[]): SortedResult[] {
  const grouped: SortedResult[] = [];
  const scannedUrls = new Set<string>();
 
  for (const hit of hits) {
    if (!scannedUrls.has(hit.url)) {
      scannedUrls.add(hit.url);
 
      grouped.push({
        id: hit.url,
        type: 'page',
        breadcrumbs: hit.breadcrumbs,
        url: hit.url,
        content: hit.title,
      });
    }
 
    grouped.push({
      id: hit.objectID,
      type: hit.content === hit.section ? 'heading' : 'text',
      url: hit.section_id ? `${hit.url}#${hit.section_id}` : hit.url,
      content: hit.content,
    });
  }
 
  return grouped;
}

Copyexport interface MixedbreadOptions {
  /**
   * The identifier of the store to search in
   */
  storeIdentifier: string;
 
  /**
   * The Mixedbread SDK client instance
   */
  client: Mixedbread;
 
  /**
   * Filter results with specific tag.
   */
  tag?: string;
 
  /**
   * Filter by locale (unsupported at the moment)
   */
  locale?: string;
}

Copyasync search(query) {
  if (!query.trim()) {
    return [];
  }
 
  const res = await client.stores.search({
    query,
    store_identifiers: [storeIdentifier],
    top_k: 10,
    filters: {
      key: 'generated_metadata.tag',
      operator: 'eq',
      value: tag,
    },
    search_options: {
      return_metadata: true,
    },
  });

Copyreturn (res.data as StoreSearchResult[]).flatMap((item) => {
  const metadata = item.generated_metadata;
 
  const url = metadata.url || '#';
  const title = metadata.title || 'Untitled';
 
  const chunkResults: SortedResult[] = [
    {
      id: `${item.file_id}-${item.chunk_index}-page`,
      type: 'page',
      content: title,
      url,
    },
  ];
 
  const headingTitle =
    item.type === 'text' && item.text ? extractHeadingTitle(item.text) : '';
 
  if (headingTitle) {
    slugger.reset();
 
    chunkResults.push({
      id: `${item.file_id}-${item.chunk_index}-heading`,
      type: 'heading',
      content: headingTitle,
      url: `${url}#${slugger.slug(headingTitle)}`,
    });
  }
 
  return chunkResults;
});

Copyfunction extractHeadingTitle(text: string): string {
  const trimmedText = text.trim();
 
  if (!trimmedText.startsWith('#')) {
    return '';
  }
 
  const lines = trimmedText.split('\n');
  const firstLine = lines[0]?.trim();
 
  if (firstLine) {
    // Use remove-markdown to convert to plain text and remove colons
    return removeMd(firstLine, {
      useImgAltText: false,
    });
  }
 
  return '';
}

Copyexport function SearchProvider({
  SearchDialog = DefaultSearchDialog,
  children,
  preload = true,
  options,
  hotKey = DEFAULT_HOT_KEYS,
  links,
}: SearchProviderProps) {
  const [isOpen, setIsOpen] = useState(preload ? false : undefined);
  const onKeyDown = useEffectEvent((e: KeyboardEvent) => {
    if (hotKey.every((v) => (typeof v.key === 'string' ? e.key === v.key : v.key(e)))) {
      setIsOpen((open) => !open);
      e.preventDefault();
    }
  });
 
  useEffect(() => {
    window.addEventListener('keydown', onKeyDown);
    return () => {
      window.removeEventListener('keydown', onKeyDown);
    };
  }, []);
 
  return (
    <SearchContext
      value={useMemo(
        () => ({
          enabled: true,
          open: isOpen ?? false,
          hotKey,
          setOpenSearch: setIsOpen,
        }),
        [isOpen, hotKey],
      )}
    >
      <Suspense fallback={null}>
        {isOpen !== undefined && (
          <SearchDialog
            open={isOpen}
            onOpenChange={setIsOpen}
            // @ts-expect-error -- insert prop for official UIs
            links={links}
            {...options}
          />
        )}
      </Suspense>
 
      {children}
    </SearchContext>
  );
}

Copyconst DEFAULT_HOT_KEYS: HotKey[] = [
  {
    key: (e) => e.metaKey || e.ctrlKey,
    display: <MetaOrControl />,
  },
  {
    key: 'k',
    display: 'K',
  },
];

Copyfunction MetaOrControl() {
  const [key, setKey] = useState('⌘');
 
  useEffect(() => {
    if (/Windows|Linux/i.test(window.navigator.userAgent)) setKey('Ctrl');
  }, []);
 
  return key;
}

Copyexport function AISearch({ children }: { children: ReactNode }) {
  const [open, setOpen] = useState(false);
  const chat = useChat({
    id: 'search',
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  });
 
  return (
    <Context value={useMemo(() => ({ chat, open, setOpen }), [chat, open])}>{children}</Context>
  );
}

Copyexport function AISearchTrigger({
  position = 'default',
  className,
  ...props
}: ComponentProps<'button'> & { position?: 'default' | 'float' }) {
  const { open, setOpen } = useAISearchContext();
 
  return (
    <button
      data-state={open ? 'open' : 'closed'}
      className={cn(
        position === 'float' && [
          'fixed bottom-4 gap-3 w-24 inset-e-[calc(--spacing(4)+var(--removed-body-scroll-bar-size,0px))] shadow-lg z-20 transition-[translate,opacity]',
          open && 'translate-y-10 opacity-0',
        ],
        className,
      )}
      onClick={() => setOpen(!open)}
      {...props}
    >
      {props.children}
    </button>
  );
}