1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
---
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
|
