Framework Setup

Last updated Oct 12, 2026100% grounded

Overview

Introduction

Fumadocs is designed to integrate smoothly with multiple React frameworks. To make sure navigation, routing, links, and parameters work correctly across different environments, Fumadocs uses specialized providers. These providers supply framework-specific implementations for links, page paths, and routers.

This guide explains how to configure Fumadocs within your existing project using one of the supported frameworks: Next.js, TanStack Start (or TanStack Router), React Router, or Waku.

Configuring the Root Provider

To set up Fumadocs in your project, wrap your application inside the appropriate root provider. Each framework package provides its own version of RootProvider which automatically configures the internal links and routing behavior for that specific environment.

Depending on your UI library package (such as Radix UI or Base UI), import the RootProvider corresponding to your chosen framework and wrap your main layout or app root with it.

Supported framework providers:

Next.js (fumadocs-core/framework/next)
TanStack Router / Start (fumadocs-core/framework/tanstack)
React Router (fumadocs-core/framework/react-router)
Waku (fumadocs-core/framework/waku)

Sources: packages/core/package.json, packages/base-ui/src/provider/next.tsx, packages/base-ui/src/provider/tanstack.tsx, packages/base-ui/src/provider/react-router.tsx, packages/base-ui/src/provider/waku.tsx

Framework Integration Steps

1. Next.js Setup

Import the Next.js RootProvider from your UI package.
Wrap your documentation layout or root component with the provider.

import { RootProvider } from 'fumadocs-ui/provider/next'; // or your preferred UI package
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return <RootProvider>{children}</RootProvider>;
}

2. TanStack Start / TanStack Router Setup

Import the TanStack RootProvider from your UI package.
Wrap your application or root route component with the provider.

import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 
export function RootComponent({ children }: { children: React.ReactNode }) {
  return <RootProvider>{children}</RootProvider>;
}

3. React Router Setup

Import the React Router RootProvider from your UI package.
Wrap your root route or layout with the provider.

import { RootProvider } from 'fumadocs-ui/provider/react-router';
 
export default function AppLayout({ children }: { children: React.ReactNode }) {
  return <RootProvider>{children}</RootProvider>;
}

4. Waku Setup

Import the Waku RootProvider from your UI package.
Wrap your root layout with the provider.

import { RootProvider } from 'fumadocs-ui/provider/waku';
 
export function Provider({ children }: { children: React.ReactNode }) {
  return <RootProvider>{children}</RootProvider>;
}

Sources: packages/base-ui/src/provider/next.tsx, packages/base-ui/src/provider/tanstack.tsx, packages/base-ui/src/provider/react-router.tsx, packages/base-ui/src/provider/waku.tsx

Customizing Framework Components

If you need to override default link or image behavior for your framework, you can pass custom components into the components prop of the RootProvider.

import { RootProvider } from 'fumadocs-ui/provider/next';
 
export default function CustomLayout({ children }: { children: React.ReactNode }) {
  return (
    <RootProvider
      components={{
        Link: ({ href, children, ...props }) => (
          <a href={href} data-custom-link="true" {...props}>
            {children}
          </a>
        ),
      }}
    >
      {children}
    </RootProvider>
  );
}

Note

If you attempt to use Fumadocs hooks like usePathname(), useRouter(), or useParams() outside of a framework provider, an error will be thrown stating that you need to wrap your application inside FrameworkProvider.

Warning

When using Waku, note that useParams() is not supported and will return an empty object along with a warning in the console.

Was this page helpful?

Quick Start

Content Authoring