Building a Tabs Component

Build an accessible Tabs component for MDX from scratch — keyboard nav, ARIA, controlled/uncontrolled modes, and localStorage persistence

Tabs show up everywhere in docs. "Show me the npm command. No wait, I use yarn." Or: "Give me the JavaScript version. Actually, TypeScript." Tabs let readers pick what's relevant without scrolling past stuff they don't care about.

Why Tabs in MDX?

You constantly need to show the same idea in different contexts — install commands for three package managers, code in multiple languages, platform-specific instructions. Without tabs, you'd stack all those variants vertically and make readers scroll past four versions of the same thing.

Tabs solve this. One spot, multiple views, reader picks.

Component Source Code

Here's the full component. It handles horizontal/vertical layout, controlled and uncontrolled modes, keyboard navigation, and localStorage persistence:

Example

// components/Tabs.jsx import React, { useState, useRef, useEffect, createContext, useContext } from 'react'; // Context for sharing tab state const TabsContext = createContext(null); // Main Tabs Container export function Tabs({ defaultValue, value, onChange, orientation = 'horizontal', children, className = '', persist, }) { const [internalValue, setInternalValue] = useState(defaultValue || ''); const isControlled = value !== undefined; const activeTab = isControlled ? value : internalValue; // Persist tab selection in localStorage useEffect(() => { if (persist && !isControlled) { const saved = localStorage.getItem(`mdx-tabs-${persist}`); if (saved) setInternalValue(saved); } }, [persist, isControlled]); const setActiveTab = (newValue) => { if (!isControlled) { setInternalValue(newValue); if (persist) { localStorage.setItem(`mdx-tabs-${persist}`, newValue); } } onChange?.(newValue); }; return ( <TabsContext.Provider value={{ activeTab, setActiveTab, orientation }}> <div className={`my-4 ${orientation === 'vertical' ? 'flex gap-4' : ''} ${className}`} data-orientation={orientation} > {children} </div> </TabsContext.Provider> ); } // Tab List (contains tab triggers) export function TabList({ children, className = '' }) { const { orientation } = useContext(TabsContext); const tabListRef = useRef(null); const handleKeyDown = (e) => { const tabs = tabListRef.current?.querySelectorAll('[role="tab"]'); if (!tabs) return; const currentIndex = Array.from(tabs).indexOf(document.activeElement); let nextIndex; const isHorizontal = orientation === 'horizontal'; const prevKey = isHorizontal ? 'ArrowLeft' : 'ArrowUp'; const nextKey = isHorizontal ? 'ArrowRight' : 'ArrowDown'; switch (e.key) { case nextKey: e.preventDefault(); nextIndex = (currentIndex + 1) % tabs.length; tabs[nextIndex].focus(); tabs[nextIndex].click(); break; case prevKey: e.preventDefault(); nextIndex = (currentIndex - 1 + tabs.length) % tabs.length; tabs[nextIndex].focus(); tabs[nextIndex].click(); break; case 'Home': e.preventDefault(); tabs[0].focus(); tabs[0].click(); break; case 'End': e.preventDefault(); tabs[tabs.length - 1].focus(); tabs[tabs.length - 1].click(); break; } }; return ( <div ref={tabListRef} role="tablist" aria-orientation={orientation} onKeyDown={handleKeyDown} className={` ${orientation === 'horizontal' ? 'flex border-b border-gray-200 dark:border-gray-700' : 'flex flex-col border-r border-gray-200 dark:border-gray-700 min-w-[150px]' } ${className} `} > {children} </div> ); } // Individual Tab Trigger export function Tab({ value, children, icon, className = '' }) { const { activeTab, setActiveTab, orientation } = useContext(TabsContext); const isActive = activeTab === value; return ( <button role="tab" aria-selected={isActive} aria-controls={`panel-${value}`} id={`tab-${value}`} tabIndex={isActive ? 0 : -1} onClick={() => setActiveTab(value)} className={` px-4 py-2 text-sm font-medium transition-all duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 ${orientation === 'horizontal' ? `border-b-2 -mb-px ${isActive ? 'border-blue-500 text-blue-600 dark:text-blue-400' : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 dark:text-gray-400 dark:hover:text-gray-200' }` : `border-r-2 -mr-px text-left ${isActive ? 'border-blue-500 text-blue-600 dark:text-blue-400 bg-blue-50 dark:bg-blue-900/20' : 'border-transparent text-gray-500 hover:text-gray-700 dark:text-gray-400' }` } ${className} `} > {icon && <span className="mr-2" aria-hidden="true">{icon}</span>} {children} </button> ); } // Tab Panel (content area) export function TabPanel({ value, children, className = '' }) { const { activeTab } = useContext(TabsContext); const isActive = activeTab === value; if (!isActive) return null; return ( <div role="tabpanel" id={`panel-${value}`} aria-labelledby={`tab-${value}`} tabIndex={0} className={`py-4 focus-visible:outline-none ${className}`} > {children} </div> ); }

Basic Usage in MDX

Drop this into any MDX file:

mdx example

import { Tabs, TabList, Tab, TabPanel } from '../components/Tabs';

# Installation Guide

<Tabs defaultValue="npm">
  <TabList>
    <Tab value="npm">npm</Tab>
    <Tab value="yarn">yarn</Tab>
    <Tab value="pnpm">pnpm</Tab>
  </TabList>

  <TabPanel value="npm">

npm install @mdx-js/react @mdx-js/loader ``` </TabPanel>

Example

yarn add @mdx-js/react @mdx-js/loader ``` </TabPanel> <TabPanel value="pnpm">

pnpm add @mdx-js/react @mdx-js/loader

html example

  </TabPanel>
</Tabs>

Code Language Tabs

This is the most common docs pattern — same logic in multiple languages:

mdx example

<Tabs defaultValue="js" persist="language-preference">
  <TabList>
    <Tab value="js" icon="🟨">JavaScript</Tab>
    <Tab value="ts" icon="🔷">TypeScript</Tab>
    <Tab value="py" icon="🐍">Python</Tab>
  </TabList>

  <TabPanel value="js">

function greet(name) { return Hello, ${name}!; }

console.log(greet('World')); ``` </TabPanel>

Code example

    function greet(name: string): string {
      return `Hello, ${name}!`;
    }

    console.log(greet('World'));
    ```
  </TabPanel>

  <TabPanel value="py">

def greet(name: str) -> str: return f"Hello, {name}!"

print(greet("World"))

html example

  </TabPanel>
</Tabs>

Controlled Tabs

Sometimes you need to drive the tabs from outside — say from a dropdown or URL param:

Example

import { useState } from 'react'; import { Tabs, TabList, Tab, TabPanel } from '../components/Tabs'; function ControlledExample() { const [activeTab, setActiveTab] = useState('overview'); return ( <> <select value={activeTab} onChange={(e) => setActiveTab(e.target.value)} > <option value="overview">Overview</option> <option value="api">API</option> <option value="examples">Examples</option> </select> <Tabs value={activeTab} onChange={setActiveTab}> <TabList> <Tab value="overview">Overview</Tab> <Tab value="api">API</Tab> <Tab value="examples">Examples</Tab> </TabList> <TabPanel value="overview">Product overview content...</TabPanel> <TabPanel value="api">API reference content...</TabPanel> <TabPanel value="examples">Code examples...</TabPanel> </Tabs> </> ); }

Vertical Tabs

Want sidebar-style navigation? Pass orientation="vertical":

mdx example

<Tabs defaultValue="general" orientation="vertical">
  <TabList>
    <Tab value="general">General</Tab>
    <Tab value="security">Security</Tab>
    <Tab value="notifications">Notifications</Tab>
    <Tab value="billing">Billing</Tab>
  </TabList>

  <TabPanel value="general">
    General settings panel with account configuration options.
  </TabPanel>

  <TabPanel value="security">
    Security settings including 2FA, password policies, and sessions.
  </TabPanel>

  <TabPanel value="notifications">
    Notification preferences for email, push, and in-app alerts.
  </TabPanel>

  <TabPanel value="billing">
    Billing information, subscription plans, and invoices.
  </TabPanel>
</Tabs>

Persistent Tab State

The persist prop saves the user's selection to localStorage. This is great for language tabs — once someone picks "TypeScript," every code tab on the site remembers that:

mdx example

{/* All tabs with the same persist key stay in sync */}
<Tabs defaultValue="ts" persist="code-language">
  <TabList>
    <Tab value="js">JavaScript</Tab>
    <Tab value="ts">TypeScript</Tab>
  </TabList>

  <TabPanel value="js">JavaScript example here...</TabPanel>
  <TabPanel value="ts">TypeScript example here...</TabPanel>
</Tabs>

Props API Documentation

Tabs Props

Prop	Type	Default	Description
`defaultValue`	`string`	`''`	Initially active tab (uncontrolled mode)
`value`	`string`	`undefined`	Active tab value (controlled mode)
`onChange`	`(value: string) => void`	`undefined`	Callback when active tab changes
`orientation`	`'horizontal' \	'vertical'`	`'horizontal'`	Tab layout direction
`persist`	`string`	`undefined`	localStorage key for persisting selection
`className`	`string`	`''`	Additional CSS classes

Tab Props

Prop	Type	Default	Description
`value`	`string`	required	Unique identifier for this tab
`children`	`ReactNode`	required	Tab label content
`icon`	`ReactNode`	`undefined`	Icon displayed before the label
`className`	`string`	`''`	Additional CSS classes

TabPanel Props

Prop	Type	Default	Description
`value`	`string`	required	Must match the corresponding Tab's value
`children`	`ReactNode`	required	Panel content (shown when tab is active)
`className`	`string`	`''`	Additional CSS classes

Styling with CSS

If you'd rather use CSS modules instead of Tailwind:

Example

/* Tabs.module.css */ .tabs-container { margin: 1rem 0; } .tabs-container[data-orientation="vertical"] { display: flex; gap: 1rem; } .tab-list { display: flex; border-bottom: 1px solid #e5e7eb; } .tab-list[aria-orientation="vertical"] { flex-direction: column; border-bottom: none; border-right: 1px solid #e5e7eb; min-width: 150px; } .tab-trigger { padding: 0.5rem 1rem; font-size: 0.875rem; font-weight: 500; border: none; background: none; cursor: pointer; border-bottom: 2px solid transparent; margin-bottom: -1px; color: #6b7280; transition: all 0.15s ease; } .tab-trigger:hover { color: #374151; border-bottom-color: #d1d5db; } .tab-trigger[aria-selected="true"] { color: #2563eb; border-bottom-color: #2563eb; } .tab-trigger:focus-visible { outline: 2px solid #2563eb; outline-offset: -2px; border-radius: 4px; } .tab-panel { padding: 1rem 0; } .tab-panel:focus-visible { outline: 2px solid #2563eb; outline-offset: 2px; border-radius: 4px; }

This component follows the WAI-ARIA Tabs pattern. Here's what keyboard users get:

Key	Action
`ArrowRight` / `ArrowDown`	Move focus to next tab (wraps around)
`ArrowLeft` / `ArrowUp`	Move focus to previous tab (wraps around)
`Home`	Move focus to first tab
`End`	Move focus to last tab
`Enter` / `Space`	Activate focused tab (handled by click)
`Tab`	Move focus into the active panel, then to next focusable element

Accessibility Notes

Here's what's happening under the hood for screen readers:

role="tablist" — Tells assistive tech "this is a set of tabs."

role="tab" — Each button is identified as a tab trigger.

role="tabpanel" — Each content area is linked to its trigger.

aria-selected — The active tab says true, the rest say false.

aria-controls / aria-labelledby — These wire up the relationship between each tab and its panel. Screen readers announce "Tab controls panel-npm" etc.

aria-orientation — Tells screen readers which arrow keys to suggest (left/right for horizontal, up/down for vertical).

tabIndex management — Only the active tab gets tabIndex={0}. Inactive ones get -1. This is the "roving tabindex" pattern — one Tab press jumps in, another jumps out.

Panel tabIndex={0} — The panel itself is focusable so keyboard users can Tab into the content after selecting a tab.

Advanced: Synced Tab Groups

Want all code tabs on a page to switch together? Here's a hook that syncs multiple tab groups through localStorage + an in-memory listener map:

Example

// hooks/useSyncedTabs.js import { useEffect, useState } from 'react'; const listeners = new Map(); export function useSyncedTabs(group) { const [value, setValue] = useState(() => { if (typeof window !== 'undefined') { return localStorage.getItem(`synced-tabs-${group}`) || ''; } return ''; }); useEffect(() => { if (!listeners.has(group)) listeners.set(group, new Set()); listeners.get(group).add(setValue); return () => { listeners.get(group).delete(setValue); }; }, [group]); const setAll = (newValue) => { localStorage.setItem(`synced-tabs-${group}`, newValue); listeners.get(group)?.forEach((fn) => fn(newValue)); }; return [value, setAll]; }

Summary

Tabs are one of the trickier interactive components you'll build for MDX. There's real complexity here — accessibility, keyboard nav, state persistence, controlled vs. uncontrolled modes. But the compound component pattern (Tabs > TabList > Tab + TabPanel) gives authors a clean API while context handles the wiring behind the scenes.

Why Tabs in MDX?

Tabs solve this. One spot, multiple views, reader picks.

Component Source Code

Here's the full component. It handles horizontal/vertical layout, controlled and uncontrolled modes, keyboard navigation, and localStorage persistence:

Example

Basic Usage in MDX

Drop this into any MDX file:

mdx example

import { Tabs, TabList, Tab, TabPanel } from '../components/Tabs';

# Installation Guide

<Tabs defaultValue="npm">
  <TabList>
    <Tab value="npm">npm</Tab>
    <Tab value="yarn">yarn</Tab>
    <Tab value="pnpm">pnpm</Tab>
  </TabList>

  <TabPanel value="npm">

npm install @mdx-js/react @mdx-js/loader ``` </TabPanel>

Example

yarn add @mdx-js/react @mdx-js/loader ``` </TabPanel> <TabPanel value="pnpm">

pnpm add @mdx-js/react @mdx-js/loader

html example

  </TabPanel>
</Tabs>

Code Language Tabs

This is the most common docs pattern — same logic in multiple languages:

mdx example

<Tabs defaultValue="js" persist="language-preference">
  <TabList>
    <Tab value="js" icon="🟨">JavaScript</Tab>
    <Tab value="ts" icon="🔷">TypeScript</Tab>
    <Tab value="py" icon="🐍">Python</Tab>
  </TabList>

  <TabPanel value="js">

function greet(name) { return Hello, ${name}!; }

console.log(greet('World')); ``` </TabPanel>

Code example

    function greet(name: string): string {
      return `Hello, ${name}!`;
    }

    console.log(greet('World'));
    ```
  </TabPanel>

  <TabPanel value="py">

def greet(name: str) -> str: return f"Hello, {name}!"

print(greet("World"))

html example

  </TabPanel>
</Tabs>

Controlled Tabs

Sometimes you need to drive the tabs from outside — say from a dropdown or URL param:

Example

Vertical Tabs

Want sidebar-style navigation? Pass orientation="vertical":

mdx example

<Tabs defaultValue="general" orientation="vertical">
  <TabList>
    <Tab value="general">General</Tab>
    <Tab value="security">Security</Tab>
    <Tab value="notifications">Notifications</Tab>
    <Tab value="billing">Billing</Tab>
  </TabList>

  <TabPanel value="general">
    General settings panel with account configuration options.
  </TabPanel>

  <TabPanel value="security">
    Security settings including 2FA, password policies, and sessions.
  </TabPanel>

  <TabPanel value="notifications">
    Notification preferences for email, push, and in-app alerts.
  </TabPanel>

  <TabPanel value="billing">
    Billing information, subscription plans, and invoices.
  </TabPanel>
</Tabs>

Persistent Tab State

The persist prop saves the user's selection to localStorage. This is great for language tabs — once someone picks "TypeScript," every code tab on the site remembers that:

mdx example

{/* All tabs with the same persist key stay in sync */}
<Tabs defaultValue="ts" persist="code-language">
  <TabList>
    <Tab value="js">JavaScript</Tab>
    <Tab value="ts">TypeScript</Tab>
  </TabList>

  <TabPanel value="js">JavaScript example here...</TabPanel>
  <TabPanel value="ts">TypeScript example here...</TabPanel>
</Tabs>

Props API Documentation

Tabs Props

Prop	Type	Default	Description
`defaultValue`	`string`	`''`	Initially active tab (uncontrolled mode)
`value`	`string`	`undefined`	Active tab value (controlled mode)
`onChange`	`(value: string) => void`	`undefined`	Callback when active tab changes
`orientation`	`'horizontal' \	'vertical'`	`'horizontal'`	Tab layout direction
`persist`	`string`	`undefined`	localStorage key for persisting selection
`className`	`string`	`''`	Additional CSS classes

Tab Props

Prop	Type	Default	Description
`value`	`string`	required	Unique identifier for this tab
`children`	`ReactNode`	required	Tab label content
`icon`	`ReactNode`	`undefined`	Icon displayed before the label
`className`	`string`	`''`	Additional CSS classes

TabPanel Props

Prop	Type	Default	Description
`value`	`string`	required	Must match the corresponding Tab's value
`children`	`ReactNode`	required	Panel content (shown when tab is active)
`className`	`string`	`''`	Additional CSS classes

Styling with CSS

If you'd rather use CSS modules instead of Tailwind:

Example

This component follows the WAI-ARIA Tabs pattern. Here's what keyboard users get:

Key	Action
`ArrowRight` / `ArrowDown`	Move focus to next tab (wraps around)
`ArrowLeft` / `ArrowUp`	Move focus to previous tab (wraps around)
`Home`	Move focus to first tab
`End`	Move focus to last tab
`Enter` / `Space`	Activate focused tab (handled by click)
`Tab`	Move focus into the active panel, then to next focusable element

Accessibility Notes

Here's what's happening under the hood for screen readers:

role="tablist" — Tells assistive tech "this is a set of tabs."

role="tab" — Each button is identified as a tab trigger.

role="tabpanel" — Each content area is linked to its trigger.

aria-selected — The active tab says true, the rest say false.

aria-controls / aria-labelledby — These wire up the relationship between each tab and its panel. Screen readers announce "Tab controls panel-npm" etc.

aria-orientation — Tells screen readers which arrow keys to suggest (left/right for horizontal, up/down for vertical).

tabIndex management — Only the active tab gets tabIndex={0}. Inactive ones get -1. This is the "roving tabindex" pattern — one Tab press jumps in, another jumps out.

Panel tabIndex={0} — The panel itself is focusable so keyboard users can Tab into the content after selecting a tab.

Advanced: Synced Tab Groups

Want all code tabs on a page to switch together? Here's a hook that syncs multiple tab groups through localStorage + an in-memory listener map:

Example

Building a Tabs Component

Why Tabs in MDX?

Component Source Code

Basic Usage in MDX

Code Language Tabs

Controlled Tabs

Vertical Tabs

Persistent Tab State

Props API Documentation

Tabs Props

Tab Props

TabPanel Props

Styling with CSS

Keyboard Navigation

Accessibility Notes

Advanced: Synced Tab Groups

Summary

Continue learning this concept

Building a Tabs Component

Why Tabs in MDX?

Component Source Code

Basic Usage in MDX

Code Language Tabs

Controlled Tabs

Vertical Tabs

Persistent Tab State

Props API Documentation

Tabs Props

Tab Props

TabPanel Props

Styling with CSS

Keyboard Navigation

Accessibility Notes

Advanced: Synced Tab Groups

Summary

Continue learning this concept