Docs Theme Layout Component API Reference

The <Layout> component is the top-level wrapper for every nextra-theme-docs site. You pass it to your root app/layout.tsx file alongside a pageMap and any optional configuration props, and it orchestrates the entire documentation shell — sidebar, navbar, footer, search, TOC, theming, and navigation links — automatically.

<Layout> uses Zod to validate its props at runtime. Invalid prop values (for example a docsRepositoryBase that does not start with https://) will throw a descriptive error during development.

Import

import { Layout } from 'nextra-theme-docs'

Usage Example

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'

const navbar = <Navbar logo={<b>My Docs</b>} />
const footer = <Footer>MIT 2024 © My Company</Footer>

export default async function RootLayout({ children }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head />
      <body>
        <Layout
          navbar={navbar}
          footer={footer}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/my-org/my-docs"
          editLink="Edit this page on GitHub"
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

Props

Required props

children

ReactNode

required

The page content rendered inside the documentation shell. In the App Router this is the {children} slot automatically provided by Next.js to every layout.

pageMap

PageMapItem[]

required

The full page map of your documentation site. Always pass the result of the getPageMap() call from nextra/page-map. Nextra uses this to build the sidebar, navigation, and breadcrumb.

import { getPageMap } from 'nextra/page-map'
// inside an async Server Component:
const pageMap = await getPageMap()

A rendered <Navbar> component. Pass a pre-instantiated element so you can co-locate all navbar configuration in one place.

import { Navbar } from 'nextra-theme-docs'
const navbar = <Navbar logo={<b>Acme Docs</b>} projectLink="https://github.com/acme" />
// then: <Layout navbar={navbar} ... />

footer

ReactNode

A rendered <Footer> component. The footer area already includes locale and theme switchers; pass children to the Footer component for copyright text or additional links.

banner

ReactNode

A rendered <Banner> component from nextra/components used for site-wide announcements displayed above the navbar. Omit this prop entirely if you do not need a banner.

import { Banner } from 'nextra/components'
const banner = <Banner storageKey="v3-release">Nextra v3 is out 🎉</Banner>
// then: <Layout banner={banner} ... />

Repository & Links

docsRepositoryBase

string

default:"https://github.com/shuding/nextra"

Base URL of the documentation repository. Must begin with https://. Used to auto-generate the Edit this page link and the Feedback link that appears in the TOC panel.For a monorepo or non-root path, include the full tree path:

<Layout docsRepositoryBase="https://github.com/my-org/repo/tree/main/docs">

editLink

ReactNode

default:"'Edit this page'"

Content rendered inside the edit link shown at the bottom of the TOC. Set to null to disable the link entirely.

feedback

object

Configuration for the inline feedback link that opens a pre-filled GitHub issue.

Show feedback properties

feedback.content

ReactNode

default:"'Question? Give us feedback'"

Label text rendered for the feedback link. Set to null to disable.

feedback.labels

string

default:"'feedback'"

Comma-separated GitHub issue labels automatically added to new feedback issues.

feedback.link

string

Custom feedback URL. When omitted, Nextra constructs a GitHub issue URL from docsRepositoryBase with the current page title pre-filled.

Search

ReactNode

default:"<Search />"

The search component rendered in the navbar. Defaults to the built-in <Search /> from nextra/components. Replace with a custom component or set to null to disable search entirely.

Dark Mode & Theming

darkMode

boolean

default:"true"

Show or hide the dark mode toggle. When false, the theme-switch dropdown is hidden from both the sidebar footer and the standalone <ThemeSwitch> component.

themeSwitch

object

Localisation strings for the theme-switch dropdown options.

Show themeSwitch properties

themeSwitch.dark

string

default:"'Dark'"

Label for the dark theme option.

themeSwitch.light

string

default:"'Light'"

Label for the light theme option.

themeSwitch.system

string

default:"'System'"

Label for the system theme option.

nextThemes

object

Configuration passed directly to the underlying next-themes <ThemeProvider>.

Show nextThemes properties

nextThemes.attribute

'class' | `data-${string}` | Array

default:"'class'"

HTML attribute used to apply the theme. Accepts 'class' or any data-* attribute name.

nextThemes.defaultTheme

string

default:"'system'"

Default theme name applied on first load.

nextThemes.disableTransitionOnChange

boolean

default:"true"

Disables CSS transitions when the theme changes to prevent a flash of unstyled content.

nextThemes.forcedTheme

string

Forces a specific theme and prevents the user from changing it.

nextThemes.storageKey

string

default:"'theme'"

localStorage key used to persist the user’s theme preference.

sidebar

object

Controls the appearance and behaviour of the documentation sidebar.

Show sidebar properties

The heading depth at which sidebar folders are collapsed by default. Set to 1 to collapse everything, or Infinity to expand all folders.

sidebar.autoCollapse

boolean

When true, folders that do not contain the active route are automatically collapsed up to defaultMenuCollapseLevel.

sidebar.defaultOpen

boolean

default:"true"

Show or hide the sidebar by default on page load.

sidebar.toggleButton

boolean

default:"true"

Show or hide the sidebar collapse/expand toggle button.

Table of Contents (TOC)

toc

object

Configuration for the in-page Table of Contents panel shown on the right side of the content area.

Show toc properties

toc.title

ReactNode

default:"'On This Page'"

Title displayed above the TOC link list.

toc.float

boolean

default:"true"

When true, the TOC floats sticky on the right side of the page. When false, it is rendered inline within the page sidebar.

toc.backToTop

ReactNode

default:"'Scroll to top'"

Label of the “back to top” button rendered below the TOC links.

toc.extraContent

ReactNode

Additional content rendered beneath the TOC link list. Useful for placing ads, related links, or any custom element.

Controls the previous/next page navigation links shown at the bottom of each page. Pass true/false to enable or disable both links at once, or pass an object to control them individually.

// Disable only the "previous" link
<Layout navigation={{ prev: false, next: true }}>

Miscellaneous

copyPageButton

boolean

default:"true"

Show or hide the Copy page content button that appears at the top of the content area, allowing users to copy the full page text to the clipboard.

lastUpdated

ReactElement

default:"<LastUpdated />"

A <LastUpdated> element used to render the last-updated timestamp beneath each page. Must be a <LastUpdated> component — plain strings or other elements are rejected at runtime.

import { LastUpdated } from 'nextra-theme-docs'
<Layout lastUpdated={<LastUpdated locale="de">Zuletzt aktualisiert</LastUpdated>}>

i18n

Array<{ locale: string, name: string }>

default:"[]"

Language switcher configuration. Each entry maps a Next.js locale string (from next.config i18n.locales) to a human-readable display name shown in the dropdown. When the array is empty, the locale switcher is hidden.

<Layout
  i18n={[
    { locale: 'en', name: 'English' },
    { locale: 'zh-CN', name: '中文' },
    { locale: 'de', name: 'Deutsch' }
  ]}
>

Full configuration example

The example below shows a production-ready root layout with all commonly used props configured:

app/layout.tsx

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'

const banner = (
  <Banner storageKey="v4-release">
    🎉 Version 4.0 is out — <a href="/changelog">see what's new</a>
  </Banner>
)
const navbar = (
  <Navbar
    logo={<b>Acme Docs</b>}
    projectLink="https://github.com/acme/docs"
  />
)
const footer = (
  <Footer>MIT {new Date().getFullYear()} © Acme Inc.</Footer>
)

export default async function RootLayout({ children }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head />
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          footer={footer}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/acme/docs/tree/main/docs"
          editLink="Edit this page on GitHub"
          feedback={{ labels: 'feedback,docs' }}
          sidebar={{ autoCollapse: true, defaultMenuCollapseLevel: 1 }}
          toc={{ backToTop: 'Back to top', float: true }}
          navigation={{ prev: true, next: true }}
          darkMode
          i18n={[
            { locale: 'en', name: 'English' },
            { locale: 'fr', name: 'Français' },
          ]}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

Define your navbar, footer, and banner elements outside the layout function so they are not re-created on every render. Because these are Server Components the values are serialised once at build time.

Core API

Docs Theme API

Blog Theme API

Docs Theme Layout Component API Reference — Nextra

Import

Usage Example

Props

Required props

Navbar & Footer

Repository & Links

Search

Dark Mode & Theming

Sidebar

Table of Contents (TOC)

Navigation

Miscellaneous

Full configuration example

Build docs developers (and LLMs) love

Core API

Docs Theme API

Blog Theme API

Documentation Index

​Import

​Usage Example

​Props

​Required props

​Navbar & Footer

​Repository & Links

​Search

​Dark Mode & Theming

​Sidebar

​Table of Contents (TOC)

​Navigation

​Miscellaneous

​Full configuration example

Build docs developers (and LLMs) love

Import

Usage Example

Props

Required props

Navbar & Footer

Repository & Links

Search

Dark Mode & Theming

Sidebar

Table of Contents (TOC)

Navigation

Miscellaneous

Full configuration example