Tabs
Tabs make it easy to explore and switch between different views or functional aspects of an app, or to browse categorized data sets.
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs } from '@itwin/itwinui-react';
export default () => {
return (
<Tabs.Wrapper>
<Tabs.TabList>
<Tabs.Tab value='apple' label='Apple' key='apple' />
<Tabs.Tab value='orange' label='Orange' key='orange' />
<Tabs.Tab value='pear' label='Pear' key='pear' />
</Tabs.TabList>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Usage
Composition API
You can build Tabs with subcomponents that are fully customizable.
<Tabs.Wrapper> <Tabs.TabList> <Tabs.Tab value='apple' label='Apple' key='apple' /> <Tabs.Tab value='orange' label='Orange' key='orange' /> <Tabs.Tab value='pear' label='Pear' key='pear' /> </Tabs.TabList>
<Tabs.Panel value='apple' key='apple'> {/*...Content for apple*/} </Tabs.Panel> <Tabs.Panel value='orange' key='orange'> {/*...Content for orange*/} </Tabs.Panel> <Tabs.Panel value='pear' key='pear'> {/*...Content for pear*/} </Tabs.Panel></Tabs.Wrapper>Tabs.Tab and Tabs.Panel can be associated with each other by passing them the same value. Tabs.Panel will be shown when its value matches the value of the currently active Tabs.Tab.
Tabs.Tab has a label prop for ease of use. You can also build Tabs.Tab with subcomponents and add a sublabel or an icon to your tab.
<Tabs.Tab value='apple' key='apple' label='Apple' /><Tabs.Tab value='apple' key='apple'> <Tabs.TabIcon> <SvgAppleIcon /> </Tabs.TabIcon> <Tabs.TabLabel>Apple</Tabs.TabLabel> <Tabs.TabDescription>A red fruit</Tabs.TabDescription></Tabs.Tab>Legacy API
Alternatively, you can use Tabs directly with labels, actions, and children as panels. Although this pattern can suffice for simple cases, we strongly recommend using composition API for the best experience.
The following code is (mostly) equivalent to the composition example above:
<Tabs labels={[ <Tab key='apple' label='Apple' />, <Tab key='orange' label='Orange' />, <Tab key='pear' label='Pear' />, ]}> {/* … content for active tab */}</Tabs>One difference is that the legacy API requires the panel content to be conditionally rendered only for the currently active tab. This can be problematic if the content is expensive to render, or if you need to preserve some state when switching tabs.
Controlled state
By default, the tabs maintain their own state. You can specify the initially active tab using the defaultValue prop in Tabs.Wrapper; the tabs will continue to maintain their own state after the initial render.
If you need to manually maintain the active state, you can use value and onValueChange props in Tabs.Wrapper.
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs } from '@itwin/itwinui-react';
export default () => {
const [currentTabValue, setCurrentTabValue] = React.useState();
return (
<Tabs.Wrapper
value={currentTabValue}
onValueChange={(value) => setCurrentTabValue(value)}
defaultValue='pear'
>
<Tabs.TabList>
<Tabs.Tab value='apple' label='Apple' key='apple' />
<Tabs.Tab value='orange' label='Orange' key='orange' />
<Tabs.Tab value='pear' label='Pear' key='pear' />
</Tabs.TabList>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Resetting panel state
When using the composition API, inactive panels will be hidden but will not be unmounted. This approach is more performant and preserves state.
If you need to reset the state of the inactive panels, you can pass a key to Tabs.Panel. For example, you can set the key to the currently active tab’s value (following the controlled state example from above).
<Tabs.Panel value='apple' key={currentTabValue}> …</Tabs.Panel>Keyboard activation mode
By default, tabs are activated automatically when focused (e.g. with keyboard). In other words, when a tab has keyboard focus, pressing the arrow keys to focus a different tab will automatically activate that tab.
While the default behavior should work fine in many cases, it can hurt the user experience for keyboard users if the panel content is expensive to render or lazily loaded. In such cases, you can set focusActivationMode to "manual" to disable automatic activation. This will allow the user to navigate between tabs with the arrow keys without activating them. The user can then activate a tab by pressing the Enter or Space key.
Variants
Vertical
The orientation prop can be used to show vertical tabs.
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs } from '@itwin/itwinui-react';
import {
SvgDocument,
SvgFilter,
SvgAirplane,
} from '@itwin/itwinui-icons-react';
export default () => {
return (
<Tabs.Wrapper orientation='vertical'>
<Tabs.TabList>
<Tabs.Tab value='apple' key='apple'>
<Tabs.TabIcon>
<SvgDocument />
</Tabs.TabIcon>
<Tabs.TabLabel>Apple</Tabs.TabLabel>
<Tabs.TabDescription>A red fruit</Tabs.TabDescription>
</Tabs.Tab>
<Tabs.Tab value='orange' key='orange' disabled>
<Tabs.TabIcon>
<SvgFilter />
</Tabs.TabIcon>
<Tabs.TabLabel>Orange</Tabs.TabLabel>
<Tabs.TabDescription>A disabled fruit</Tabs.TabDescription>
</Tabs.Tab>
<Tabs.Tab value='pear' key='pear'>
<Tabs.TabIcon>
<SvgAirplane />
</Tabs.TabIcon>
<Tabs.TabLabel>Pear</Tabs.TabLabel>
<Tabs.TabDescription>A green fruit</Tabs.TabDescription>
</Tabs.Tab>
</Tabs.TabList>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Borderless
The type prop can be set to "borderless" to show borderless tabs.
As their name implies, borderless tabs have no frame or stroke surrounding them.
Use borderless tabs when the tabbed content can be easily told apart from its surroundings (or lack thereof).
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs } from '@itwin/itwinui-react';
export default () => {
return (
<Tabs.Wrapper type='borderless'>
<Tabs.TabList>
<Tabs.Tab value='apple' label='Apple' key='apple' />
<Tabs.Tab value='orange' label='Orange' key='orange' />
<Tabs.Tab value='pear' label='Pear' key='pear' />
</Tabs.TabList>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Pill
The type prop can be set to "pill" to show pill tabs.
Pill tabs are meant to be used with content that belong to a similar category. They act like a filter for toggling through different states of similar content.
The maximum recommended amount of pill tabs is 4.
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs } from '@itwin/itwinui-react';
export default () => {
return (
<Tabs.Wrapper type='pill'>
<Tabs.TabList>
<Tabs.Tab value='apple' label='Apple' key='apple' />
<Tabs.Tab value='orange' label='Orange' key='orange' />
<Tabs.Tab value='pear' label='Pear' key='pear' />
</Tabs.TabList>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Actions
The Tabs.Action subcomponent can be used to add action buttons to the end of tab list.
An apple is a round, edible fruit produced by an apple tree (Malus domestica). Apple trees are cultivated worldwide and are the most widely grown species in the genus Malus.
An orange is a fruit of various citrus species in the family Rutaceae (see list of plants known as orange); it primarily refers to Citrus x sinensis, which is also called sweet orange, to distinguish it from the related Citrus x aurantium, referred to as bitter orange.
Pears are fruits produced and consumed around the world, growing on a tree and harvested in late summer into mid-autumn.
import * as React from 'react';
import { Tabs, Button } from '@itwin/itwinui-react';
export default () => {
return (
<Tabs.Wrapper>
<Tabs.TabList>
<Tabs.Tab value='apple' label='Apple' key='apple' />
<Tabs.Tab value='orange' label='Orange' key='orange' />
<Tabs.Tab value='pear' label='Pear' key='pear' />
</Tabs.TabList>
<Tabs.Actions>
<Button size='small'>My action</Button>
</Tabs.Actions>
<Tabs.Panel value='apple' key='apple'>
An apple is a round, edible fruit produced by an apple tree (Malus
domestica). Apple trees are cultivated worldwide and are the most widely
grown species in the genus Malus.
</Tabs.Panel>
<Tabs.Panel value='orange' key='orange'>
An orange is a fruit of various citrus species in the family Rutaceae
(see list of plants known as orange); it primarily refers to Citrus x
sinensis, which is also called sweet orange, to distinguish it from the
related Citrus x aurantium, referred to as bitter orange.
</Tabs.Panel>
<Tabs.Panel value='pear' key='pear'>
Pears are fruits produced and consumed around the world, growing on a
tree and harvested in late summer into mid-autumn.
</Tabs.Panel>
</Tabs.Wrapper>
);
};
Props
Unfinished
| Prop | Description | Default |
|---|---|---|
| actions | Content displayed to the right/bottom of the horizontal/vertical tabs If type = 'pill', actions is not applicable.ReactNode[] | |
| labels | Elements shown for each tab.
Recommended to pass an array of Tab components.ReactNode[] | |
| onTabSelected | Handler for activating a tab. (index: number) => void | |
| activeIndex | Index of the active tab. number | |
| focusActivationMode | Control whether focusing tabs (using arrow keys) should automatically select them.
Use 'manual' if tab panel content is not preloaded. "auto" | "manual" | 'auto' |
| color | Color of the bar on the active tab. "blue" | "green" | 'blue' |
| tabsClassName | Custom CSS class name for tabs. string | |
| contentClassName | Custom CSS class name for tab panel. string | |
| wrapperClassName | Custom CSS class name for the tabs wrapper. string | |
| children | Content inside the tab panel. ReactNode | |
| overflowOptions | @deprecated Tabs will now overflow by default, so this prop does nothing. { useOverflow?: boolean; } | |
| defaultValue | never | |
| defaultChecked | never | |
| orientation | Orientation of the tabs. "horizontal" | "vertical" | 'horizontal' |
| type | Type of the tabs. If orientation = 'vertical', pill is not applicable."default" | "borderless" | "pill" | 'default' |
| as | "symbol" | "object" | "button" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "canvas" | ... 159 more ... | FunctionComponent<...> |