---
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)