Docs Layout

The layout of documentation pages, it includes a sidebar and mobile-only navbar.

It is a server component, you should not reference it in a client component.

Usage

Pass your page tree to the component.

layout.tsx

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/app/layout.config';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout {...baseOptions} tree={tree}>
      {children}
    </DocsLayout>
  );
}

Prop	Type	Default
`tree`	`Root`	-
`sidebar?`	`Partial<SidebarOptions>`	-
`containerProps?`	`HTMLAttributes<HTMLDivElement>`	-
`themeSwitch?`	`{ enabled?: boolean \| undefined; component?: ReactNode; mode?: "light-dark" \| "light-dark-system" \| undefined; }`	-
`i18n?`	`boolean \| I18nConfig`	`false`
`githubUrl?`	`string`	-
`links?`	`LinkItemType[]`	-
`nav?`	`Partial<NavOptions>`	-

layout.tsx

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout
  sidebar={{
    // sidebar options:
    enabled: true,
  }}
/>;

Prop	Type	Default
`enabled?`	`boolean`	-
`component?`	`ReactNode`	-
`collapsible?`	`boolean`	-
`components?`	`Partial<SidebarComponents>`	-
`tabs?`	`false \| Option[] \| TabOptions`	-
`banner?`	`ReactNode`	-
`footer?`	`ReactNode`	-
`hideSearch?`	`boolean`	`false`
`defaultOpenLevel?`	`number`	`0`
`prefetch?`	`boolean`	`true`

See Navigation Guide for usages.

Decoration

Change the icon/styles of tabs.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout
  sidebar={{
    tabs: {
      transform: (option, node) => ({
        ...option,
        icon: 'my icon',
      }),
    },
  }}
/>;

Nav

A mobile-only navbar, we recommend to customise it from baseOptions.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  githubUrl: 'https://github.com/fuma-nama/fumadocs',
  nav: {
    title: 'My App',
  },
};

Prop	Type	Default
`enabled?`	`boolean`	-
`component?`	`ReactNode`	-
`title?`	`ReactNode`	-
`url?`	`string`	`'/'`
`enableSearch?`	`boolean`	-
`transparentMode?`	`"always" \| "top" \| "none"`	`none`

Transparent Mode

To make the navbar background transparent, you can configure transparent mode.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  nav: {
    transparentMode: 'top',
  },
};

Mode	Description
`always`	Always use a transparent background
`top`	When at the top of page
`none`	Disable transparent background (default)

To replace the navbar in Docs Layout, set nav.component to your own component.

layout.tsx

import { baseOptions } from '@/app/layout.config';
import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout
      {...baseOptions}
      nav={{
        component: <CustomNavbar />,
      }}
    >
      {children}
    </DocsLayout>
  );
}

Fumadocs uses CSS Variables to share the size of layout components, and fit each layout component into appropriate position.

You need to override --fd-nav-height to the exact height of your custom navbar, this can be done with a CSS stylesheet (e.g. in global.css):

:root {
  --fd-nav-height: 80px !important;
}

Advanced

Disable Prefetching

By default, it uses the Next.js Link component with prefetch enabled. When the link component appears into the browser viewport, the content (RSC payload) will be prefetched.

On Vercel, this may cause a high usage of serverless functions and Data Cache. It can also hit the limits of some other hosting platforms.

You can disable prefetching to reduce the amount of RSC requests.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout sidebar={{ prefetch: false }} />;

Usage

Sidebar

Sidebar Tabs

Decoration

Nav

Transparent Mode

Replace Navbar

Advanced

Disable Prefetching

On this page