--- title: "Grouping Tabs" description: "Organize multiple tabs into logical groups for complex documentation structures" --- 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 ```typescript 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) ```typescript 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 ```typescript 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) ```typescript 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) ```typescript 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 - [Creating Tabs](/docs/configuration/advanced/tab-management/creating-tabs) - [Organization Patterns](/docs/configuration/advanced/tab-management/organization-patterns) - [Tab Configuration Deep Dive](/docs/navigation-system/core-concepts/tabs)