{
"name": "Tabs",
"source": "src/components/Tabs.tsx",
"propsType": "TabsProps",
"import": "import { Tabs } from 'ionbase-ui';",
"status": "stable",
"summary": "A tab list and its panels, built on react-aria's tab collection. Children are TabItem.",
"useWhen": [
"one region of the page shows one of several peer views, and only one at a time",
"the views are peers — no ordering, no progression between them"
],
"useInstead": [
{
"when": "the steps must be completed in order",
"use": "Button",
"why": "tabs imply peers you may visit in any order; a wizard is a sequence"
},
{
"when": "the sections should all be readable at once, or printable",
"use": "Divider",
"why": "tabs hide everything but the active panel, including from Ctrl-F"
},
{
"when": "the options set a value — a view mode, a range, a unit — and no panel belongs to each",
"use": "SegmentedControl",
"why": "it looks like the pill type and is a radiogroup: a tab with no panel announces a relationship that does not exist"
},
{
"when": "it is navigation between pages rather than panels within one",
"use": "NavItem"
}
],
"composition": {
"order": [
"Tabs",
"TabItem"
],
"note": "TabItem comes from react-stately's collection Item — it takes no props of its own beyond `title` (the tab label) and `key`; its children are the panel.",
"example": "……"
},
"variants": {
"type": {
"pill": {
"use": "the default — a filled track, for switching views inside a panel or card"
},
"underline": {
"use": "a rule under the active tab, for page-level sections"
}
},
"size": {
"sm": {
"use": "dense panels and toolbars"
},
"md": {
"use": "the default"
},
"lg": {
"use": "page-level section switching"
}
},
"orientation": {
"horizontal": {
"use": "the default"
},
"vertical": {
"use": "a stacked track with up/down arrow keys",
"caveat": "keyboard and ARIA are complete, but the decoration is not — the underline rule and the pill track's padding are still written for the horizontal axis. Figma has not specified the vertical drawing"
}
}
},
"a11y": {
"role": "tablist / tab / tabpanel",
"guarantees": [
"roving tabindex, arrow-key navigation and the aria-controls/aria-labelledby pairing between each tab and its panel come from react-aria",
"the focus ring shows for keyboard focus only, and hover does not latch on touch"
],
"requires": [
"`aria-label` or `aria-labelledby` on Tabs — the tab list is a named region",
"a stable `key` on every TabItem"
]
},
"antiPatterns": [
{
"dont": "tabs whose panels the user must read in order",
"why": "the role announces peers, and nothing stops a user landing on the last one first"
},
{
"dont": "hiding required form fields behind a tab",
"why": "a validation error in an inactive panel is invisible; the user is told the form is invalid with nothing on screen to fix"
},
{
"dont": "one tab",
"why": "a tablist with a single tab is chrome with no choice in it"
},
{
"dont": "collecting TabItems into a `React.ReactElement[]` and passing the array as the children",
"why": "the children are typed `CollectionChildren`: one collection element, an array of them, or a render function. `ReactElement` defaults its props to `unknown`, which is not an item's props, so the array fails to compile. Write the tabs out, or `.map()` them as Tabs' only child"
}
],
"stylesheet": "src/styles/tabs.css",
"tokens": [
"--border-default",
"--border-primary",
"--border-width-default",
"--border-width-thick",
"--font-family-sans",
"--font-weight-medium",
"--icon-size-sm",
"--ion-duration-base",
"--ion-ease-out",
"--ion-tabs-icon-size",
"--ion-tabs-item-font-size",
"--ion-tabs-item-gap",
"--ion-tabs-item-line-height",
"--ion-tabs-item-padding-x",
"--ion-tabs-item-padding-y",
"--ion-tabs-item-size",
"--radius-full",
"--radius-md",
"--ring-focus",
"--spacing-12",
"--spacing-16",
"--spacing-2",
"--spacing-20",
"--spacing-32",
"--spacing-4",
"--spacing-40",
"--spacing-48",
"--spacing-6",
"--spacing-8",
"--surface-default",
"--surface-hover",
"--surface-muted",
"--surface-page",
"--text-default",
"--text-disabled",
"--text-tertiary",
"--type-body",
"--type-body-lg",
"--type-body-lg-line-height",
"--type-body-line-height",
"--type-body-sm",
"--type-body-sm-line-height"
],
"props": {
"type": {
"type": "TabsType | undefined",
"required": false,
"origin": "own",
"description": "Visual style. Matches the Figma `Type` variant.",
"values": [
"pill",
"underline"
],
"default": "pill"
},
"size": {
"type": "TabsSize | undefined",
"required": false,
"origin": "own",
"description": "Matches the Figma `Size` variant.",
"values": [
"sm",
"md",
"lg"
],
"default": "md"
},
"orientation": {
"type": "\"vertical\" | \"horizontal\" | undefined",
"required": false,
"origin": "own",
"description": "Drives both the arrow-key axis and the track layout.\n\n`vertical` is keyboard- and ARIA-complete — up/down move between tabs, and\nthe track stacks — but its *decoration* is not: the underline rule and the\npill track's padding are still written for the horizontal axis only. Those\nare Figma's to specify, not this file's to invent. See tabs.css.",
"values": [
"vertical",
"horizontal"
],
"tags": {
"default": "'horizontal'"
},
"default": "horizontal"
},
"className": {
"type": "string | undefined",
"required": false,
"origin": "own"
},
"keyboardActivation": {
"type": "\"manual\" | \"automatic\" | undefined",
"required": false,
"origin": "aria",
"description": "Whether tabs are activated automatically on focus or manually.",
"values": [
"manual",
"automatic"
],
"tags": {
"default": "'automatic'"
}
},
"isDisabled": {
"type": "boolean | undefined",
"required": false,
"origin": "other",
"description": "Whether the TabList is disabled.\nShows that a selection exists, but is not available in that circumstance."
},
"selectedKey": {
"type": "Key | undefined",
"required": false,
"origin": "other",
"description": "The currently selected key in the collection (controlled)."
},
"defaultSelectedKey": {
"type": "Key | undefined",
"required": false,
"origin": "other",
"description": "The initial selected keys in the collection (uncontrolled)."
},
"onSelectionChange": {
"type": "((key: Key) => void) | undefined",
"required": false,
"origin": "other",
"description": "Handler that is called when the selection changes."
},
"children": {
"type": "CollectionChildren",
"required": true,
"origin": "aria",
"description": "The contents of the collection."
},
"items": {
"type": "Iterable | undefined",
"required": false,
"origin": "aria",
"description": "Item objects in the collection."
},
"disabledKeys": {
"type": "Iterable | undefined",
"required": false,
"origin": "aria",
"description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise\ninteracted with."
},
"id": {
"type": "string | undefined",
"required": false,
"origin": "aria",
"description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
},
"aria-label": {
"type": "string | undefined",
"required": false,
"origin": "aria",
"description": "Defines a string value that labels the current element."
},
"aria-labelledby": {
"type": "string | undefined",
"required": false,
"origin": "aria",
"description": "Identifies the element (or elements) that labels the current element."
},
"aria-describedby": {
"type": "string | undefined",
"required": false,
"origin": "aria",
"description": "Identifies the element (or elements) that describes the object."
},
"aria-details": {
"type": "string | undefined",
"required": false,
"origin": "aria",
"description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
}
},
"propCounts": {
"own": 4,
"aria": 9,
"dom": 0,
"other": 4
}
}