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