Tabs

Tabs organizes related content into switchable panels. It supports horizontal and vertical layouts, a quiet line treatment, controlled and uncontrolled state, keyboard navigation, disabled tabs, badges, icons, full-width layouts, manual activation, and lazy panel rendering. It is a presentational/client-side component: it does not fetch data, paginate records, or persist the active tab for you.

See the live Tabs showcase.

Basic usageCopy Anchor Link

import { Tabs } from '@mosmox/ui';

<Tabs
  items={[
    { key: 'overview', label: 'Overview', content: <p>Summary content</p> },
    { key: 'activity', label: 'Activity', content: <p>Recent activity</p> },
  ]}
/>

The first non-disabled tab is active by default. Every item requires a stable key and label; content is rendered in its associated panel.

Sizes and orientationCopy Anchor Link

Tabs use a line treatment with a text-color and thin underline accent for the active tab. There are no filled or pill-shaped active-tab variants. size accepts default, sm (small), or xs (extra small). orientation accepts horizontal or vertical.

<Tabs items={items} />
<Tabs items={items} size="sm" />
<Tabs items={items} orientation="vertical" />

fullWidth makes the tab list fill its container and distributes tabs across that width. fitted distributes each tab equally without changing the root width; use it when the parent already controls the tab area. When both are set, the list fills the container and the tabs share it equally.

Controlled and uncontrolled stateCopy Anchor Link

Use defaultActiveKey for local state or activeKey with onChange for controlled state.

<Tabs items={items} defaultActiveKey="activity" />

<Tabs
  activeKey={activeKey}
  items={items}
  onChange={(key, item) => {
    setActiveKey(key);
    analytics.track('tab-change', { key, label: item.label });
  }}
/>

Icons, badges, and disabled tabsCopy Anchor Link

<Tabs
  items={[
    { key: 'files', icon: <Folder size={16} />, label: 'Files', badge: 12, content: <Files /> },
    { key: 'settings', label: 'Settings', content: <Settings /> },
    { key: 'billing', label: 'Billing', disabled: true, content: <Billing /> },
  ]}
/>

Keyboard activationCopy Anchor Link

Tabs use roving tab focus. Left/Right arrows navigate horizontal tabs; Up/Down navigate vertical tabs; Home and End jump to the first or last enabled tab. With the default activationMode="automatic", moving focus also activates a tab. With manual, Enter or Space activates the focused tab.

<Tabs items={items} activationMode="manual" />

Lazy panelsCopy Anchor Link

lazy avoids rendering inactive panels. With lazy and keepMounted, inactive panels remain rendered in the DOM but stay hidden; without keepMounted, only the active panel is rendered. keepMounted has no effect unless lazy is also enabled.

<Tabs items={items} lazy />
<Tabs items={items} lazy keepMounted />

ConfigProviderCopy Anchor Link

Set defaults for all Tabs inside a provider. Local props override provider values.

<ConfigProvider components={{ tabs: { size: 'sm', orientation: 'horizontal', fullWidth: true } }}>
  <Tabs items={items} />
</ConfigProvider>

API ReferenceCopy Anchor Link

onChange receives the activated tab key and the complete TabItem. In uncontrolled mode it also updates the active panel; in controlled mode the parent must update activeKey in response to the callback.

TabItemCopy Anchor Link

Union valuesCopy Anchor Link

Custom contentCopy Anchor Link

All visual content fields are ReactNode, so labels, icons, badges, and panels can be composed from application components rather than plain strings.

<Tabs
  items={[
    {
      key: 'activity',
      label: <span>Activity</span>,
      icon: <ActivityIcon aria-hidden="true" />,
      badge: <Badge>4</Badge>,
      content: <ActivityFeed projectId="atlas" />,
    },
  ]}
/>

Complete controlled exampleCopy Anchor Link

import { useState } from 'react';
import { ConfigProvider, Tabs } from '@mosmox/ui';

const items = [
  { key: 'details', label: 'Details', content: <Details /> },
  { key: 'activity', label: 'Activity', content: <ActivityFeed /> },
  { key: 'settings', label: 'Settings', content: <Settings /> },
];

export function ProjectTabs() {
  const [activeKey, setActiveKey] = useState('details');

  return (
    <ConfigProvider components={{ tabs: { size: 'sm', fullWidth: true } }}>
      <Tabs
        activeKey={activeKey}
        activationMode="manual"
        items={items}
        onChange={(key) => setActiveKey(key)}
        orientation="horizontal"
      />
    </ConfigProvider>
  );
}

AccessibilityCopy Anchor Link

The component uses tablist, tab, and tabpanel roles, links each tab to its panel with aria-controls/aria-labelledby, and exposes the active state through aria-selected. Disabled tabs are removed from keyboard navigation. Panels remain keyboard focusable for users navigating content with a keyboard.