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