---
title: "Understanding Tabs"
description: "Learn how to create top-level navigation contexts that switch the entire sidebar"
---

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

| Aspect     | Groups                      | Tabs                               |
| ---------- | --------------------------- | ---------------------------------- |
| Location   | Appear as sidebar sections  | Appear at top as clickable buttons |
| Navigation | Expand/collapse             | Complete sidebar switch            |
| Hierarchy  | Organized within each other | Top-level only                     |
| Use Case   | Organize entries            | Separate major sections            |

## Creating Tabs

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

```typescript
{
    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:

```typescript
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:

```typescript
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:

```typescript
{
    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](/docs/navigation-system/core-concepts/nested-groups)
- [Creating Tabs in Configuration](/docs/configuration/advanced/tab-management/creating-tabs)
- [Real-World Examples](/docs/navigation-system/hierarchy/real-world-examples)