---
title: Fumadocs 16.2
description: UI Refactor
author: Fuma Nama
date: 2025-11-29
---

We are pleased to announce the release of Fumadocs 16.2, introducing a better layout system for Fumadocs UI.

## The New Layout System

Handling layouts in documentation frameworks can present significant challenges.

As a solution, Fumadocs UI implemented a [Grid System](/docs/ui/layouts/docs#the-layout-system) that is composable, flexible, cohesive and predictable.
See the linked docs for more details.

In short, the layout consists of a grid container, and layout components using `position: sticky`:

```css
#nd-docs-layout {
  grid-template:
    'sidebar header toc'
    'sidebar toc-popover toc'
    'sidebar main toc' 1fr / minmax(var(--fd-sidebar-col), 1fr) minmax(0, var(--fd-page-col))
    minmax(min-content, 1fr);

  --fd-docs-row-1: var(--fd-banner-height, 0px);
  --fd-docs-row-2: calc(var(--fd-docs-row-1) + var(--fd-header-height));
  --fd-docs-row-3: calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height));
}
```

The container defines the offsets of each row, layout components can leverage them according to their grid area:

```css
.layout-component {
  position: sticky;
  top: var(--fd-docs-row-1);
  height: calc(var(--fd-docs-height) - var(--fd-docs-row-1));
}
```

Layout components are also responsible to declare their heights via CSS variables, allowing container to calculate the right row offsets.

```css
#nd-docs-layout:has(.layout-component) {
  --fd-header-height: 56px;
}
```

For user-land customizations, we recommend the Fumadocs CLI customize command, or hooking the relevant grid areas like:

```css
.custom-component {
  /* depends on the layout, usually we have toc, toc-popover, sidebar, header, main */
  grid-area: main;
}
```

### Why the Change?

Previously, Fumadocs UI relied on `position: fixed` and mathematical computations (inspired by Vitepress). The older method often lacked composability and difficult for beginners to manage.

The new system fixed most of the flaws, allowing easier visualizations, while reducing the complexity of previous solutions.

## Breaking Changes

### Global Styles

While Fumadocs 16.2 preserves compatibility in several areas, notably:

- The `--fd-layout-width` CSS variable continues to function as expected.
- All ID and data attributes remain unchanged.

However, the shift to the new grid system may impact existing customizations, particularly those dependent on the prior fixed-position logic. We recommend reviewing your implementation carefully and testing thoroughly.

If you have already installed layout components via Fumadocs CLI, replace `preset.css` with `preset-legacy.css` to keep legacy styles & avoid unexpected breakages:

```css title="global.css"
/* [!code --] */
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import 'fumadocs-ui/css/preset-legacy.css';
```

### No Longer Exposing Internal Components

Layout components such as Root Toggle, Language Toggle, and Theme Toggle are no longer directly exposed.
This decision enables Fumadocs UI to iterate these elements without introducing unexpected breaking changes to usage outside of API surfaces.

**Migration Steps:** Override the relevant layout components with your own implementations, or utilize the Fumadocs CLI commands (`add` or `customize`) to install them locally.

### Removal of Internal Contexts

The following context modules are made private:

- `fumadocs-ui/contexts/sidebar`
- `fumadocs-ui/contexts/layout`

If you have already installed `<DocsLayout />` via Fumadocs CLI, import the legacy contexts instead:

```ts
// [!code --:2]
import {} from 'fumadocs-ui/contexts/sidebar';
import {} from 'fumadocs-ui/contexts/layout';

// [!code ++:2]
import {} from 'fumadocs-ui/legacy/sidebar';
import {} from 'fumadocs-ui/legacy/layout';
```

And wrap your app under the legacy `<SidebarProvider />`:

```tsx
import type { ReactNode } from 'react';
import { SidebarProvider } from 'fumadocs-ui/legacy/sidebar';

export function RootLayout({ children }: { children: ReactNode }) {
  return <SidebarProvider>{children}</SidebarProvider>;
}
```

<Callout title="What if I still use built-in layouts?">

The legacy contexts are made exclusively for layout components installed locally. If you still
import layout components (e.g. `<DocsLayout />`) from `fumadocs-ui`, migrate your usages as follows:

```tsx
// [!code --]
import { useSidebar } from 'fumadocs-ui/contexts/sidebar';
// [!code ++]
import { useSidebar } from 'fumadocs-ui/components/sidebar/base';
```

Ensure the contexts are only accessed within `<DocsLayout />`.

</Callout>

## Minor Changes

The changes below are backward compatible.

### Importing Page Layouts by Type

The notebook layout is now isolated from default layout, including their page components.

Make sure to import the appropriate page layout based on your docs layout:

```ts
// For docs layout
import { DocsPage } from 'fumadocs-ui/layouts/docs/page';
// For notebook layout
import { DocsPage } from 'fumadocs-ui/layouts/notebook/page';
```

**Migration Steps:** Update your imports accordingly. Although the default `fumadocs-ui/page` will redirect to the correct layout, we strongly advise explicit imports for clarity and future-proofing.

### Removal of Unused Styles

Styles related to the abandoned `container` utility, and `--spacing-fd-container` variable, have been dropped as they are no longer utilized.

**Migration Steps:** Remove references to these styles from your codebase.

## Conclusion

Fumadocs 16.2 aims to offer greater flexibility for developers. Welcome to share your thoughts about the new design on GitHub Discussion!
