Understanding Tabs

Tabs are top-level navigation contexts. When you click a tab, the entire sidebar switches to show that tab’s content. Tabs are perfect for organizing major documentation sections.

What are Tabs?

A tab is a promoted group that appears at the top of the sidebar:

[Learn] [Getting Started] [API Reference] [Guides]  <- Tabs
├── Group 1
├── Group 2
└── Group 3

Clicking a tab switches which groups appear below.

Tabs vs. Groups

Creating Tabs

To make a group a tab, add tab: true:

{
    id: "api",
    label: "API Reference",
    icon: "📖",
    tab: true,  // <- Makes this a tab
    groups: [
        {
            id: "endpoints",
            label: "Endpoints",
            autoGenerated: true,
        },
        {
            id: "authentication",
            label: "Authentication",
            entries: [
                { slug: "api/auth/oauth" },
                { slug: "api/auth/jwt" },
            ],
        },
    ],
}

Sidebar renders as:

[Learn] [API Reference]  <- Now it's a tab!

When "API Reference" tab is active:
├── Endpoints
└── Authentication
    ├── OAuth
    └── JWT

The Default Tab

Non-tabbed groups appear in a special “default” tab. Configure it in the defaultTab property:

export const SIDEBAR_NAVIGATION = {
    "my-docs": {
        defaultTab: {
            label: "Learn", // Label for the default tab
            icon: "📖", // Icon for the default tab
        },
        groups: [
            // Non-tabbed groups appear in the default tab
            {
                id: "getting-started",
                label: "Getting Started",
                // No tab: true, so appears in default tab
            },
            // This one becomes a separate tab
            {
                id: "api",
                label: "API Reference",
                tab: true,
            },
        ],
    },
};

Sidebar renders as:

[Learn] [API Reference]  <- Two tabs
     ↓
When "Learn" tab is active:
├── Getting Started
    ├── Introduction
    ├── Installation
    └── Quick Start

When "API Reference" tab is active:
├── Endpoints
├── Authentication
└── Rate Limiting

Multiple Tabs

You can have multiple tabs. They appear left-to-right in order:

groups: [
    {
        id: "guides",
        label: "Guides",
        tab: true,
        autoGenerated: true,
    },
    {
        id: "api",
        label: "API Reference",
        tab: true,
        autoGenerated: true,
    },
    {
        id: "patterns",
        label: "Common Patterns",
        tab: true,
        autoGenerated: true,
    },
];

Sidebar renders as:

[Guides] [API Reference] [Common Patterns]
    ↑ First tab  ↑ Second tab   ↑ Third tab

Tabs with Nested Groups

Tabs can contain complex hierarchies with nested groups:

{
    id: "documentation",
    label: "Documentation",
    icon: "📚",
    tab: true,
    groups: [
        {
            id: "getting-started",
            label: "Getting Started",
            entries: [
                { slug: "documentation/getting-started/installation" },
                { slug: "documentation/getting-started/quick-start" },
            ],
        },
        {
            id: "advanced",
            label: "Advanced Topics",
            groups: [
                {
                    id: "architecture",
                    label: "Architecture",
                    autoGenerated: true,
                },
                {
                    id: "performance",
                    label: "Performance Tuning",
                    autoGenerated: true,
                },
            ],
        },
    ],
}

Sidebar when “Documentation” tab is active:

📚 Documentation
├── Getting Started
│   ├── Installation
│   └── Quick Start
└── Advanced Topics
    ├── Architecture
    └── Performance Tuning

Real-World Example: This Site

This site showcases tabs with nested groups:

Navigation System (Tab)
├── Core Concepts
│   ├── Entries
│   ├── Groups
│   ├── Nested Groups
│   └── Tabs          <- You're reading this!
├── Hierarchy

Configuration (Tab)
├── Basics
├── Advanced
    ├── Nested Setup
    └── Tab Management

Generation Strategies (Tab)
├── Auto-Generation
├── Manual Creation
└── Hybrid Approach

Each major section is a tab. When you click a tab, the sidebar switches to show its content.

When to Use Tabs

✅ Multiple major sections: Documentation vs. API reference ✅ Different audiences: User guides vs. Developer guides ✅ Product versions: v1 vs. v2 vs. v3 ✅ Multiple collections worth highlighting

Tab Limitations

• Tabs are only top-level (you can’t nest tabs within tabs)
• Too many tabs (5+) clutters the interface
• Not recommended for simple documentation

Next Steps

Learn about:

• Nested Groups
• Creating Tabs in Configuration
• Real-World Examples