Search Documentation

Search for pages and headings in the documentation

Grouping Tabs

When you have many tabs (5+), grouping them makes navigation clearer. Tabs can be organized into categories.

What Is Tab Grouping?

Tab Group 1: User Paths
├─ Getting Started
├─ How-To Guides
└─ FAQ

Tab Group 2: Reference
├─ API Documentation
├─ CLI Reference
└─ Configuration

Tab Group 3: Advanced
├─ Architecture
├─ Performance
└─ Troubleshooting

Related tabs cluster together, reducing cognitive load.

Without Tab Grouping (Flat)

[Getting Started] [Guides] [API] [CLI] [Config] [Architecture] [Performance] [FAQ]
 └─ User-focused  └─────────────────────────────────────────────┬─────────────────┘
                       └─ Reference-focused          └─ Advanced

Too many tabs. Users must scan to find what they need.

With Tab Grouping (Organized)

User Paths:    [Getting Started] [Guides] [FAQ]
Reference:     [API] [CLI] [Config]
Advanced:      [Architecture] [Performance]

Tabs grouped by purpose. Clear organization.

Configuration Structure

export const SIDEBAR_NAVIGATION = {
    docs: {
        defaultTab: {
            label: "Getting Started",
            icon: "🚀",
        },
        tabGroups: [
            // <- Group tabs
            {
                id: "user-paths",
                label: "User Paths",
                tabs: [
                    {
                        id: "getting-started",
                        label: "Getting Started",
                        icon: "🚀",
                        groups: [
                            { id: "setup", label: "Setup", autoGenerated: true },
                            { id: "first-project", label: "First Project", autoGenerated: true },
                        ],
                    },
                    {
                        id: "guides",
                        label: "How-To Guides",
                        icon: "📖",
                        autoGenerated: true,
                    },
                    {
                        id: "faq",
                        label: "FAQ",
                        icon: "❓",
                        entries: [{ slug: "faq/common-issues" }, { slug: "faq/troubleshooting" }],
                    },
                ],
            },
            {
                id: "reference",
                label: "Reference",
                tabs: [
                    {
                        id: "api",
                        label: "API",
                        icon: "🔗",
                        groups: [
                            { id: "authentication", label: "Auth", autoGenerated: true },
                            { id: "endpoints", label: "Endpoints", autoGenerated: true },
                        ],
                    },
                    {
                        id: "cli",
                        label: "CLI",
                        icon: "⌨️",
                        autoGenerated: true,
                    },
                    {
                        id: "config",
                        label: "Configuration",
                        icon: "⚙️",
                        entries: [
                            { slug: "reference/env-vars" },
                            { slug: "reference/config-file" },
                        ],
                    },
                ],
            },
            {
                id: "advanced",
                label: "Advanced",
                tabs: [
                    {
                        id: "architecture",
                        label: "Architecture",
                        icon: "🏗️",
                        autoGenerated: true,
                    },
                    {
                        id: "performance",
                        label: "Performance",
                        icon: "⚡",
                        autoGenerated: true,
                    },
                ],
            },
        ],
    },
};

Structure:

tabGroups
├─ "user-paths" (group)
│  ├─ "getting-started" (tab)
│  ├─ "guides" (tab)
│  └─ "faq" (tab)
├─ "reference" (group)
│  ├─ "api" (tab)
│  ├─ "cli" (tab)
│  └─ "config" (tab)
└─ "advanced" (group)
   ├─ "architecture" (tab)
   └─ "performance" (tab)

User Experience

Visual Representation

┌─────────────────────────────────────────────┐
│ User Paths:                                 │
│ [🚀 Getting Started] [📖 Guides] [❓ FAQ]   │
│                                             │
│ Reference:                                  │
│ [🔗 API] [⌨️ CLI] [⚙️ Config]              │
│                                             │
│ Advanced:                                   │
│ [🏗️ Architecture] [⚡ Performance]          │
└─────────────────────────────────────────────┘

Tab Navigation

User on “Getting Started” tab views:

Sidebar showing:
├─ Setup
├─ First Project

User clicks “API” tab (different group):

Sidebar switches to:
├─ Authentication
├─ Endpoints

User clicks “Guides” tab (same group as Getting Started):

Sidebar shows:
├─ [Auto-discovered guide files]

Switching tabs (any group) updates entire sidebar.

Group Label Options

Invisible Dividers (No Label)

tabGroups: [
    {
        id: "group1",
        label: "",  // <- No label shown
        tabs: [...]
    },
    {
        id: "group2",
        label: "",  // <- Visual space, no text
        tabs: [...]
    },
]

Tabs have visual separation but no labels.

Section Headers

tabGroups: [
    {
        id: "getting-started-group",
        label: "Getting Started",  // <- Shown as header
        tabs: [
            { id: "quickstart", label: "Quick Start", ... },
            { id: "tutorials", label: "Tutorials", ... },
        ],
    },
    {
        id: "reference-group",
        label: "Reference",  // <- Shown as header
        tabs: [
            { id: "api", label: "API", ... },
            { id: "config", label: "Config", ... },
        ],
    },
]

Group labels appear as section headers above tabs.

Common Tab Grouping Patterns

Pattern 1: By User Expertise

Getting Started (Beginners)
├─ Quick Start
├─ Tutorials
└─ FAQ

Reference (All Users)
├─ API
├─ CLI
└─ Configuration

Advanced (Experts)
├─ Architecture
├─ Performance Tuning
└─ Internals

Users find docs matching their skill level.

Pattern 2: By Function

Learning
├─ Getting Started
├─ Guides
└─ Examples

Building
├─ API Reference
├─ CLI
└─ Libraries

Operating
├─ Deployment
├─ Monitoring
└─ Troubleshooting

Users quickly jump to docs for their task.

Pattern 3: By Audience

Product Users
├─ Features
├─ How-To
└─ Support

Developers
├─ API
├─ SDK
└─ Webhooks

DevOps
├─ Installation
├─ Configuration
└─ Scaling

Each audience sees relevant tabs together.

Pattern 4: By Version

Current Release
├─ v3.0 (Latest)
└─ v3.1 (Stable)

Legacy
├─ v2.0 (LTS)
└─ v1.0 (Deprecated)

Experimental
└─ v4.0 (Beta)

Version users need grouped clearly.

Pattern 5: SaaS Platform

Platform
├─ Getting Started
├─ Features
└─ FAQ

Documentation
├─ API
├─ CLI
└─ SDKs

Resources
├─ Examples
├─ Pricing
└─ Blog

Platform docs, developer docs, and resources separated.

Collapsible Groups

Some implementations allow collapsing groups:

▼ Getting Started       (expanded)
  [Quick Start] [Guides] [FAQ]

▶ Reference            (collapsed)

▼ Advanced             (expanded)
  [Architecture] [Performance]

Users collapse groups they don’t need, focus on relevant tabs.

Migration: Flat to Grouped Tabs

Before (No Groups)

groups: [
    { id: "getting-started", label: "Getting Started", tab: true, ... },
    { id: "guides", label: "Guides", tab: true, ... },
    { id: "api", label: "API", tab: true, ... },
    { id: "cli", label: "CLI", tab: true, ... },
    { id: "architecture", label: "Architecture", tab: true, ... },
]

5 tabs in flat list.

After (Grouped)

tabGroups: [
    {
        id: "learning",
        label: "Learning",
        tabs: [
            { id: "getting-started", label: "Getting Started", ... },
            { id: "guides", label: "Guides", ... },
        ],
    },
    {
        id: "reference",
        label: "Reference",
        tabs: [
            { id: "api", label: "API", ... },
            { id: "cli", label: "CLI", ... },
        ],
    },
    {
        id: "advanced",
        label: "Advanced",
        tabs: [
            { id: "architecture", label: "Architecture", ... },
        ],
    },
]

Same tabs, better organized.

Performance Considerations

Tab grouping is purely organizational:

  • No performance impact
  • All tabs still lazy-load on click
  • Grouping is visual only

Whether flat or grouped, same number of tabs = same performance.

When to Use Tab Grouping

Use when:

  • 5+ tabs total
  • Tabs serve different purposes
  • Clear grouping emerges
  • Want to improve navigation

Skip grouping when:

  • < 5 tabs
  • Tabs already clearly organized
  • All tabs serve similar purpose

Responsive Behavior

On mobile, grouped tabs might collapse:

Desktop: [Getting Started] [Guides] [API] [CLI] [Architecture]
         └─ Getting Started Group  └─────────────────────────┘

Mobile: Getting Started ▼
(Dropdown expands to show all groups and tabs)

Grouping helps on small screens too.

Next Steps