@wordpress/components
Version:
UI components for WordPress.
156 lines (101 loc) • 4.47 kB
Markdown
# TabPanel
TabPanel is a React component to render an ARIA-compliant TabPanel.
TabPanels organize content across different screens, data sets, and interactions. It has two sections: a list of tabs, and the view to show when tabs are chosen.
## Design guidelines
### Usage
TabPanels organize and allow navigation between groups of content that are related and at the same level of hierarchy.
#### Tabs in a set
As a set, all tabs are unified by a shared topic. For clarity, each tab should contain content that is distinct from all the other tabs in a set.
### Anatomy
1. Container
2. Active text label
3. Active tab indicator
4. Inactive text label
5. Tab item
#### Labels
Tab labels appear in a single row, in the same typeface and size. Use text labels that clearly and succinctly describe the content of a tab, and make sure that a set of tabs contains a cohesive group of items that share a common characteristic.
Tab labels can wrap to a second line, but do not add a second row of tabs.
#### Active tab indicators
To differentiate an active tab from an inactive tab, apply an underline and color change to the active tab’s text and icon.
### Behavior
Users can navigate between tabs by tapping the tab key on the keyboard.
### Placement
Place tabs above content. Tabs control the UI region displayed below them.
## Development guidelines
### Usage
```jsx
import { TabPanel } from '@wordpress/components';
const onSelect = ( tabName ) => {
console.log( 'Selecting tab', tabName );
};
const MyTabPanel = () => (
<TabPanel
className="my-tab-panel"
activeClass="active-tab"
onSelect={ onSelect }
tabs={ [
{
name: 'tab1',
title: 'Tab 1',
className: 'tab-one',
},
{
name: 'tab2',
title: 'Tab 2',
className: 'tab-two',
},
] }
>
{ ( tab ) => <p>{ tab.title }</p> }
</TabPanel>
);
```
### Props
The component accepts the following props:
#### className
The class to give to the outer container for the TabPanel
- Type: `String`
- Required: No
- Default: ''
#### orientation
The orientation of the tablist (`vertical` or `horizontal`)
- Type: `String`
- Required: No
- Default: `horizontal`
#### onSelect
The function called when a tab has been selected. It is passed the `tabName` as an argument.
- Type: `Function`
- Required: No
- Default: `noop`
#### tabs
An array of objects containing the following properties:
- `name`: `(string)` Defines the key for the tab.
- `title`:`(string)` Defines the translated text for the tab.
- `className`:`(string)` Optional. Defines the class to put on the tab.
- `icon`:`(ReactNode)` Optional. When set, displays the icon in place of the tab title. The title is then rendered as an aria-label and tooltip.
- `disabled`:`(boolean)` Optional. Determines if the tab should be disabled or selectable.
> > **Note:** Other fields may be added to the object and accessed from the child function if desired.
- Type: `Array`
- Required: Yes
#### activeClass
The class to add to the active tab
- Type: `String`
- Required: No
- Default: `is-active`
#### initialTabName
The name of the tab to be selected upon mounting of component. If this prop is not set, the first tab will be selected by default.
- Type: `String`
- Required: No
- Default: none
#### selectOnMove
When `true`, the tab will be selected when receiving focus (automatic tab activation). When `false`, the tab will be selected only when clicked (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info.
- Type: `boolean`
- Required: No
- Default: `true`
#### children
A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the tabs prop.
- Type: (`Object`) => `Element`
- Required: Yes