163 lines
6.3 KiB
Markdown
163 lines
6.3 KiB
Markdown
|
---
|
||
|
|
title: Tabs
|
||
|
|
description: Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support.
|
||
|
|
---
|
||
|
|
|
||
|
|
<Header title="Tabs" section="UI components">
|
||
|
|
Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support.
|
||
|
|
</Header>
|
||
|
|
|
||
|
|
<ExampleTabs
|
||
|
|
prefix="demo"
|
||
|
|
panels={{ {
|
||
|
|
'Result': 'ui.Tabs.DemoResult',
|
||
|
|
'HTML': 'ui.Tabs.DemoHTML',
|
||
|
|
'CSS': 'ui.Tabs.DemoCSS',
|
||
|
|
} }}
|
||
|
|
/>
|
||
|
|
|
||
|
|
Tabs are built using the `TabGroup`, `TabList`, `Tab`, and `TabPanel` components. Clicking on any tab or selecting it with the keyboard will activate the corresponding panel.
|
||
|
|
|
||
|
|
|
||
|
|
## Styling states
|
||
|
|
|
||
|
|
| CSS selector | Description
|
||
|
|
| --------------- | --------------
|
||
|
|
| `.ui-hidden` | Added to all `TabPanel` except the one that is active.
|
||
|
|
| `.ui-selected` | Added to the selected `Tab`.
|
||
|
|
| `.ui-disabled` | Added to disabled `Tab`s.
|
||
|
|
|
||
|
|
|
||
|
|
## Disabling a tab
|
||
|
|
|
||
|
|
To disable a tab, use the disabled attribute on the `Tab` component. Disabled tabs cannot be selected with the mouse, and are also skipped when navigating the tab list using the keyboard.
|
||
|
|
|
||
|
|
<Callout type="warning">
|
||
|
|
Disabling tabs might be confusing for users. Instead, I reccomend you either remove it or explain why there is no content for that tab when is selected.
|
||
|
|
</Callout>
|
||
|
|
|
||
|
|
|
||
|
|
## Manually activating tabs
|
||
|
|
|
||
|
|
By default, tabs are automatically selected as the user navigates through them using the arrow kbds.
|
||
|
|
|
||
|
|
If you'd rather not change the current tab until the user presses <kbd>Enter</kbd> or <kbd>Space</kbd>, use the `manual` attribute on the `TabGroup` component.
|
||
|
|
|
||
|
|
Remember to add styles to the `:focus` state of the tab so is clear to the user that the tab is focused.
|
||
|
|
|
||
|
|
<ExampleTabs
|
||
|
|
prefix="manual"
|
||
|
|
panels={{{
|
||
|
|
'HTML': 'ui.Tabs.ManualHTML',
|
||
|
|
'Result': 'ui.Tabs.ManualResult',
|
||
|
|
} }}
|
||
|
|
/>
|
||
|
|
|
||
|
|
The manual prop has no impact on mouse interactions — tabs will still be selected as soon as they are clicked.
|
||
|
|
|
||
|
|
|
||
|
|
## Vertical tabs
|
||
|
|
|
||
|
|
If you've styled your `TabList` to appear vertically, use the `vertical` attribute to enable navigating with the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds instead of <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd>, and to update the `aria-orientation` attribute for assistive technologies.
|
||
|
|
|
||
|
|
<ExampleTabs
|
||
|
|
prefix="vertical"
|
||
|
|
panels={{ {
|
||
|
|
'HTML': 'ui.Tabs.VerticalHTML',
|
||
|
|
'Result': 'ui.Tabs.VerticalResult',
|
||
|
|
} }}
|
||
|
|
/>
|
||
|
|
|
||
|
|
|
||
|
|
## Controlling the tabs with a `<select>`
|
||
|
|
|
||
|
|
Sometimes, you want to display a `<select>` element in addition to tabs. To do so, use the `TabSelect` and `TabOption` components.
|
||
|
|
A `TabSelect` component is a wrapper for a `<select>` element, and it accepts `TabOption` components as children.
|
||
|
|
|
||
|
|
Note that a `TabSelect` **is not a replacement for a `TabList`**. For accessibility the `TabList` must be remain in your code, even if it's visually hidden.
|
||
|
|
|
||
|
|
<ExampleTabs
|
||
|
|
prefix="select"
|
||
|
|
:panels="{
|
||
|
|
'HTML': 'ui.Tabs.SelectHTML',
|
||
|
|
'Result': 'ui.Tabs.SelectResult',
|
||
|
|
}"
|
||
|
|
/>
|
||
|
|
|
||
|
|
|
||
|
|
## Component arguments
|
||
|
|
|
||
|
|
### TabGroup
|
||
|
|
|
||
|
|
| Argument | Type | Default | Description
|
||
|
|
| ----------- | -------- | ---------- | --------------
|
||
|
|
| tag | `str` | `"div"` | HTML tag used for rendering the wrapper.
|
||
|
|
|
||
|
|
### TabList
|
||
|
|
|
||
|
|
| Argument | Type | Default | Description
|
||
|
|
| ----------- | -------- | ---------- | --------------
|
||
|
|
| vertical | `bool` | `false` | Use the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds to move between tabs instead of the defaults <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd> arrow kbds.
|
||
|
|
| manual | `bool` | `false` | If `true`, selecting a tab with the keyboard won't activate it, you must press <kbd>Enter</kbd> os <kbd>Space</kbd> kbds to do it.
|
||
|
|
| tag | `str` | `"nav"` | HTML tag used for rendering the wrapper.
|
||
|
|
|
||
|
|
|
||
|
|
### Tab
|
||
|
|
|
||
|
|
| Argument | Type | Default | Description
|
||
|
|
| ----------- | -------- | ---------- | --------------
|
||
|
|
| target | `str` | | Required. HTML id of the panel associated with this tab.
|
||
|
|
| selected | `bool` | `false` | Initially selected tab. Only one tab in the `TabList` can be selected at the time.
|
||
|
|
| disabled | `bool` | `false` | If the tab can be selected.
|
||
|
|
| tag | `str` | `"button"` | HTML tag used for rendering the tab.
|
||
|
|
|
||
|
|
### TabPanel
|
||
|
|
|
||
|
|
| Argument | Type | Default | Description
|
||
|
|
| ----------- | -------- | ---------- | --------------
|
||
|
|
| hidden | `bool` | `false` | Initially hidden panel.
|
||
|
|
| tag | `bool` | `"div"` | HTML tag used for rendering the panel.
|
||
|
|
|
||
|
|
|
||
|
|
### TabSelect
|
||
|
|
|
||
|
|
No arguments.
|
||
|
|
|
||
|
|
|
||
|
|
### TabOption
|
||
|
|
|
||
|
|
| Argument | Type | Default | Description
|
||
|
|
| ----------- | -------- | ---------- | --------------
|
||
|
|
| target | `str` | | Required. HTML id of the panel associated with this tab.
|
||
|
|
| disabled | `bool` | `false` | Display the option but not allow to select it.
|
||
|
|
|
||
|
|
|
||
|
|
## Events
|
||
|
|
|
||
|
|
A tab emits a `jxui:tab:selected` event every time is selected. The event contains the `target` property with the tag node.
|
||
|
|
|
||
|
|
```js
|
||
|
|
document.addEventListener("jxui:tab:selected", (event) => {
|
||
|
|
console.log(`'${event.target.textContent}' tab selected`);
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Accessibility notes
|
||
|
|
|
||
|
|
### Mouse interaction
|
||
|
|
|
||
|
|
Clicking a `Tab` will select that tab and display the corresponding `TabPanel`.
|
||
|
|
|
||
|
|
### Keyboard interaction
|
||
|
|
|
||
|
|
All interactions apply when a `Tab` component is focused.
|
||
|
|
|
||
|
|
| Command | Description
|
||
|
|
| ------------------------------------------------------------------------------------- | -----------
|
||
|
|
| <kbd title="arrow left">←</kbd> / <kbd title="arrow right">→</kbd> arrow kbds | Selects the previous/next non-disabled tab, cycling from last to first and vice versa.
|
||
|
|
| <kbd title="arrow up">↑</kbd> / <kbd title="arrow down">↓</kbd> arrow kbds when `vertical` is set | Selects the previous/next non-disabled tab, cycling from last to first and vice versa.
|
||
|
|
| <kbd>Enter</kbd> or <kbd>Space</kbd> when `manual` is set | Activates the selected tab
|
||
|
|
| <kbd>Home</kbd> or <kbd>PageUp</kbd> | Activates the **first** tab
|
||
|
|
| <kbd>End</kbd> or <kbd>PageDown</kbd> | Activates the **last** tab
|