---
title: "Creating Tabs"
description: "Learn how to promote groups to tabs and structure your documentation with top-level navigation"
---

Tabs are top-level navigation elements that split your documentation into separate sections. Think of tabs as completely independent view modes.

## What Are Tabs?

```
��������������������������������������
� Getting Started �  API  � Guides �  <- Tabs
������������������������������������
� Sidebar Content for selected tab �
�                                  �
� Current tab: Getting Started     �
��������������������������������������
```

Clicking a tab switches the entire sidebar navigation.

## Creating Your First Tab

### Step 1: Define in Configuration

```typescript
export const SIDEBAR_NAVIGATION = {
    docs: {
        defaultTab: {
            label: "Getting Started",
            icon: "",
        },
        groups: [
            {
                id: "quickstart",
                label: "Quick Start",
                tab: true, // <- This makes it a tab!
                autoGenerated: true,
            },
            {
                id: "guides",
                label: "How-To Guides",
                tab: true, // <- Another tab
                autoGenerated: true,
            },
            {
                id: "reference",
                label: "Reference",
                tab: true, // <- Third tab
                autoGenerated: true,
            },
        ],
    },
};
```

**Key:** Set `tab: true` to promote a group to a tab.

### Step 2: Create Folder Structure

```
content/docs/
�� quickstart/           <- Matches "quickstart" tab
�  �� intro.md
�  �� setup.md
�  ��� first-app.md
�� guides/               <- Matches "guides" tab
�  �� authentication.md
�  �� database.md
�  ��� deployment.md
��� reference/            <- Matches "reference" tab
   �� api.md
   �� cli.md
   ��� config.md
```

### Step 3: User Experience

Users see tabs:

```
�������������������������������������
� Quickstart � Guides � Reference �
�������������������������������������

Content below changes based on selected tab.

On Quickstart tab:
�� Introduction
�� Setup
��� First App

On Guides tab:
�� Authentication
�� Database
��� Deployment

On Reference tab:
�� API
�� CLI
��� Config
```

Clicking tabs switches navigation entirely.

## Tab with Nested Groups

Tabs can contain groups (creating another level of navigation):

```typescript
{
    id: "api",
    label: "API",
    tab: true,
    groups: [
        {
            id: "authentication",
            label: "Authentication",
            autoGenerated: true,
        },
        {
            id: "resources",
            label: "Resources",
            groups: [
                { id: "users", label: "Users", autoGenerated: true },
                { id: "posts", label: "Posts", autoGenerated: true },
                { id: "comments", label: "Comments", autoGenerated: true },
            ],
        },
        {
            id: "errors",
            label: "Error Handling",
            autoGenerated: true,
        },
    ],
}
```

**Navigation:**

```
Tabs: [Quickstart] [API] [Reference]

When on API tab, sidebar shows:
�� Authentication
�� Resources
�  �� Users
�  �� Posts
�  ��� Comments
��� Error Handling
```

Tabs + nested groups = powerful organization.

## Tab Icons

Icons help users identify tabs quickly:

```typescript
defaultTab: {
    label: "Getting Started",
    icon: "",  // <- Rocket for quick start
},
groups: [
    {
        id: "getting-started",
        label: "Getting Started",
        tab: true,
        icon: "�",  // <- Book icon
    },
    {
        id: "api",
        label: "API Reference",
        tab: true,
        icon: "�",  // <- Link icon
    },
    {
        id: "examples",
        label: "Examples",
        tab: true,
        icon: "�",  // <- Lightbulb icon
    },
],
```

Icons appear with tab labels. Users recognize patterns:

-  Getting Started
- � API
- � Examples
-  Configuration
- �� Advanced

## Tab Selection State

Tabs remember selection. If user navigates to:

```
/docs/api/endpoints
```

And selects "Reference" tab, sidebar updates but URL pattern changes:

```
/docs/reference/overview
```

**Breadcrumb updates:**

```
Before: Home > Docs > API > Endpoints
After:  Home > Docs > Reference > Overview
```

Each tab maintains its own content and breadcrumb trail.

## Common Tab Structures

### Structure 1: By User Journey

```
Getting Started -> Learn -> Build -> Deploy -> Reference
```

```typescript
groups: [
    { id: "getting-started", label: "Getting Started", tab: true, ... },
    { id: "learn", label: "Learn", tab: true, ... },
    { id: "build", label: "Build", tab: true, ... },
    { id: "deploy", label: "Deploy", tab: true, ... },
    { id: "reference", label: "Reference", tab: true, ... },
]
```

New users start with "Getting Started" tab.
Advanced users jump to "Reference" tab.

### Structure 2: By Audience

```
Users | Developers | Operators
```

```typescript
groups: [
    { id: "users", label: "Users", tab: true, ... },
    { id: "developers", label: "Developers", tab: true, ... },
    { id: "operators", label: "Operators", tab: true, ... },
]
```

Each audience sees relevant content in their tab.

### Structure 3: By Product

```
Core | Extensions | Plugins | Marketplace
```

```typescript
groups: [
    { id: "core", label: "Core", tab: true, ... },
    { id: "extensions", label: "Extensions", tab: true, ... },
    { id: "plugins", label: "Plugins", tab: true, ... },
    { id: "marketplace", label: "Marketplace", tab: true, ... },
]
```

Each product/feature gets its own tab.

### Structure 4: By Version

```
v3 (Current) | v2 (LTS) | v1 (Legacy)
```

```typescript
groups: [
    { id: "v3-current", label: "v3 (Current)", tab: true, ... },
    { id: "v2-lts", label: "v2 (LTS)", tab: true, ... },
    { id: "v1-legacy", label: "v1 (Legacy)", tab: true, ... },
]
```

Users select their version, see relevant docs.

## Switching Between Tabs

### Manual Tab Click

User clicks "API" tab -> sidebar changes -> breadcrumb updates -> URL changes.

```
Was viewing: /docs/guides/authentication
Clicked: API tab
Now viewing: /docs/api/overview (or defaultTab for API)
```

### Default Tab

If user visits `/docs/` (no specific page), they see:

```typescript
defaultTab: { label: "Getting Started", icon: "" }
```

They land on Getting Started tab's first page.

### Deep Linking

Users can share direct links to specific tabs:

```
/docs/api/endpoints -> Opens API tab, shows endpoints
/docs/guides/setup -> Opens Guides tab, shows setup
/docs/reference/config -> Opens Reference tab, shows config
```

Clicking those links automatically switches to correct tab.

## Tab + Manual Control

Mix tabs with manual entries:

```typescript
groups: [
    {
        id: "essentials",
        label: "Essentials",
        tab: true,
        autoGenerated: false,
        entries: [
            { slug: "essentials/why-choose-us" },
            { slug: "essentials/features" },
            { slug: "essentials/pricing" },
        ],
    },
    {
        id: "guides",
        label: "Guides",
        tab: true,
        autoGenerated: true, // Auto-discover all files
    },
    {
        id: "api",
        label: "API",
        tab: true,
        autoGenerated: false,
        entries: [{ slug: "api/authentication" }, { slug: "api/endpoints" }],
    },
];
```

**Result:**

- Essentials tab: 3 specific pages only
- Guides tab: all files appear automatically
- API tab: only listed endpoints appear

## Performance Notes

Each tab loads sidebar content separately:

- **First load:** Tab 1 loads
- **Click Tab 2:** Tab 2's sidebar loads (lazy)
- **Click Tab 3:** Tab 3's sidebar loads (lazy)

No performance impact from multiple tabs.

## Responsive Behavior

On mobile, tabs stack or become dropdowns:

```
Desktop (3+ tabs):
[Getting Started] [API] [Reference] [Advanced]

Tablet (2-3 tabs):
[Getting Started] [API] [Reference] [�� More]

Mobile (1+ tab):
Getting Started ��  (dropdown)
```

Users can still access all tabs on mobile via dropdown.

## Migration: Groups to Tabs

Converting existing groups to tabs:

### Before (No tabs)

```typescript
groups: [
    { id: "intro", label: "Introduction", autoGenerated: true },
    { id: "guides", label: "Guides", autoGenerated: true },
    { id: "reference", label: "Reference", autoGenerated: true },
];
```

Sidebar shows 3 groups, all in same view.

### After (With tabs)

```typescript
groups: [
    { id: "intro", label: "Introduction", tab: true, autoGenerated: true },
    { id: "guides", label: "Guides", tab: true, autoGenerated: true },
    { id: "reference", label: "Reference", tab: true, autoGenerated: true },
];
```

Same content, now organized with tabs. Just add `tab: true`.

## Next Steps

- [Grouping Tabs](/docs/configuration/advanced/tab-management/grouping-tabs)
- [Organization Patterns](/docs/configuration/advanced/tab-management/organization-patterns)
- [Nested Groups](/docs/navigation-system/core-concepts/nested-groups)