Tabs Component in Docusaurus

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Tabs let you show multiple versions of the same thing — different languages, different operating systems, different package managers — in one clean, switchable block. Your readers click what's relevant to them and ignore the rest.

Basic Tab Usage

Import the components and wrap your content:

console.log('Hello from JavaScript!');

print("Hello from Python!")

fn main() { println!("Hello from Rust!"); }

Visual Result: Three tab buttons labeled "JavaScript", "Python", and "Rust" appear above a content area. Clicking a tab reveals the corresponding code block while hiding others. The active tab has a highlighted underline/background.

TabItem Component Props

Each TabItem takes a few props:

Props Reference

Setting the Default Tab

First TabItem is active by default. Want a different one? Add default:

Or use defaultValue on the Tabs wrapper:

Synced Tabs with groupId

This is the killer feature. groupId syncs tab selections across your entire page — and even across pages via localStorage:

Visual Result: When a user clicks "macOS" in the first tab group, the second tab group automatically switches to "macOS" as well. The selection persists across page navigations because it's stored in localStorage.

:::tip[User Experience] Use groupId whenever you have multiple tab groups on a page (or across pages) that represent the same choice. Users only need to select their preference once — it persists throughout their session and even across visits. :::

Common groupId Patterns

Lazy Loading Tabs

By default, all tab content renders in the DOM but stays hidden with CSS. If you've got heavy content in some tabs, enable lazy loading so they only render on click:

:::caution[Lazy Loading Trade-off] Lazy-loaded tabs won't be indexed by search engines since the content isn't in the initial DOM. Use lazy loading only for heavy interactive content, not for text-based documentation. :::

Tabs with Code Blocks

This is the most common use case — showing code in multiple languages or configs:

module.exports = { title: 'My Site', url: 'https://example.com', baseUrl: '/', };

module.exports = { title: 'My Site', url: 'https://example.com', baseUrl: '/', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'my-org', projectName: 'my-project', presets: [ ['classic', { docs: { sidebarPath: './sidebars.js' }, blog: { showReadingTime: true }, theme: { customCss: './src/css/custom.css' }, }], ], };

:::note[Important Spacing] Always leave a blank line between the <TabItem> tag and your Markdown content (including code blocks). Without this blank line, MDX won't process the Markdown syntax correctly. :::

Custom Tab Styling

CSS Customization

Adding Icons to Tabs

Emoji in the label works great:

npm install @docusaurus/core

yarn add @docusaurus/core

pnpm add @docusaurus/core

Custom Tab Component with Attributes

You can also pass inline styles and classes per tab:

Query String Integration

Want the tab selection to show up in the URL so people can share a direct link to their choice?

When someone selects "Android", the URL becomes ?platform=android. Share that link and the recipient sees Android pre-selected.

Best Practices

:::tip[Tab Guidelines]

1. Keep tab counts reasonable — 2-5 tabs works best; more becomes unwieldy
2. Use consistent values — The same value and groupId across pages keeps sync working
3. Always include a default — Don't leave users guessing which tab to pick
4. Match content structure — Tabs within a group should have parallel content
5. Use groupId liberally — Sync related tab groups so users only choose once
6. Prefer labels over values — Make label human-readable; value can be a short ID
7. Test mobile layouts — Tabs wrap on small screens; keep labels concise

:::

Complete Example: Installation Guide

Here's a real-world example combining multiple tab features:

npm init docusaurus@latest my-site classic cd my-site npm start

yarn create docusaurus my-site classic cd my-site yarn start

pnpm create docusaurus my-site classic cd my-site pnpm start

Tabs turn long, repetitive docs into something scannable. Pair them with groupId and your readers only pick their preference once — then every tab on your site follows.