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