Skip to content

Commit bbe18e3

Browse files
AkshatJawneAkshatJawne
authored
docs: ui.tabs (#943)
Closes #861
1 parent e3c5540 commit bbe18e3

File tree

3 files changed

+386
-1
lines changed

3 files changed

+386
-1
lines changed

‎plugins/ui/docs/components/tabs.md‎

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
# Tabs
2+
3+
Tabs organize related content into sections within panels, allowing users to navigate between them.
4+
5+
## Example
6+
7+
```python
8+
from deephaven import ui, empty_table
9+
10+
my_tabs_basic = ui.tabs(
11+
ui.tab("Hello World!", title="Tab 1"),
12+
ui.tab(
13+
ui.flex(
14+
"Hello World with table!",
15+
empty_table(10).update("I=i"),
16+
),
17+
title="Tab 2",
18+
),
19+
)
20+
```
21+
22+
## UI Recommendations
23+
24+
1. Use tabs to organize sections of equal importance. Avoid using tabs for content with varying levels of importance.
25+
2. Use a vertical tabs layout when displaying shortcuts to sections of content on a single page.
26+
3. Avoid nesting tabs more than two levels deep, as it can become overly complicated.
27+
28+
29+
## Content
30+
31+
Tabs can be created using `ui.tab`, or using `ui.tab_list` and `ui.tab_panels`, but not the two options combined.
32+
33+
If you want a default tab layout with minimal customization for tab appearance, tabs should be created by passing in `ui.tab` to `ui.tabs`.
34+
35+
Note that the `ui.tab` component can only be used within `ui.tabs`.
36+
37+
```python
38+
from deephaven import ui
39+
40+
41+
my_tabs_tab_content_example = ui.tabs(
42+
ui.tab("Arma virumque cano, Troiae qui primus ab oris.", title="Founding of Rome"),
43+
ui.tab("Senatus Populusque Romanus.", title="Monarchy and Republic"),
44+
ui.tab("Alea jacta est.", title="Empire"),
45+
)
46+
```
47+
48+
For more control over the layout, types, and styling of the tabs, create them with `ui.tab_list` and `ui.tab_panels` with `ui.tabs`.
49+
50+
The `ui.tab_list` specifies the titles of the tabs, while the `ui.tab_panels` specify the content within each of the tab panels.
51+
52+
When specifying tabs using `ui.tab_list` and `ui.tab_panels`, keys must be provided that match each of the respective tabs.
53+
54+
```python
55+
from deephaven import ui
56+
57+
58+
my_tabs_list_panels_content_example = ui.tabs(
59+
ui.tab_list(ui.item("Tab 1", key="Key 1"), ui.item("Tab 2", key="Key 2")),
60+
ui.tab_panels(
61+
ui.item(
62+
ui.calendar(
63+
aria_label="Calendar (uncontrolled)",
64+
default_value="2020-02-03",
65+
),
66+
key="Key 1",
67+
),
68+
ui.item(
69+
ui.radio_group(
70+
ui.radio("Yes", value="Yes"),
71+
ui.radio("No", value="No"),
72+
label="Is vanilla the best flavor of ice cream?",
73+
),
74+
key="Key 2",
75+
),
76+
flex_grow=1,
77+
position="relative",
78+
),
79+
flex_grow=1,
80+
margin_bottom="size-400",
81+
)
82+
```
83+
84+
Note that both the `ui.tab_list` and `ui.tab_panels` components can also only be used within `ui.tabs`.
85+
86+
87+
## Selection
88+
89+
With tabs, the `default_selected_key` or `selected_key` props can be set to have a selected tab.
90+
91+
```python
92+
from deephaven import ui
93+
94+
95+
@ui.component
96+
def ui_tabs_selected_key_examples():
97+
selected_tab, set_selected_tab = ui.use_state("Tab 1")
98+
return [
99+
"Pick a tab (uncontrolled)",
100+
ui.tabs(
101+
ui.tab(
102+
"There is no prior chat history with John Doe.",
103+
title="John Doe",
104+
key="Tab 1",
105+
),
106+
ui.tab(
107+
"There is no prior chat history with Jane Doe.",
108+
title="Jane Doe",
109+
key="Tab 2",
110+
),
111+
ui.tab(
112+
"There is no prior chat history with Joe Bloggs.",
113+
title="Joe Bloggs",
114+
key="Tab 3",
115+
),
116+
default_selected_key="Tab 2",
117+
),
118+
f"Pick a tab (controlled), selected tab: {selected_tab}",
119+
ui.tabs(
120+
ui.tab(
121+
"There is no prior chat history with John Doe.",
122+
title="John Doe",
123+
key="Tab 1",
124+
),
125+
ui.tab(
126+
"There is no prior chat history with Jane Doe.",
127+
title="Jane Doe",
128+
key="Tab 2",
129+
),
130+
ui.tab(
131+
"There is no prior chat history with Joe Bloggs.",
132+
title="Joe Bloggs",
133+
key="Tab 3",
134+
),
135+
selected_key=selected_tab,
136+
on_selection_change=set_selected_tab,
137+
),
138+
]
139+
140+
141+
my_tabs_selected_key_examples = ui_tabs_selected_key_examples()
142+
```
143+
144+
145+
## Events
146+
147+
The `on_change` property is triggered whenever the currently selected tab changes.
148+
149+
150+
```python
151+
from deephaven import ui
152+
153+
154+
@ui.component
155+
def ui_tabs_on_change_example():
156+
selected_tab, set_selected_tab = ui.use_state("Tab 1")
157+
158+
def get_background_color(tab):
159+
if tab == "Tab 1":
160+
return "celery-500"
161+
elif tab == "Tab 2":
162+
return "fuchsia-500"
163+
elif tab == "Tab 3":
164+
return "blue-500"
165+
else:
166+
return "gray-200"
167+
168+
return [
169+
ui.view(
170+
ui.tabs(
171+
ui.tab(
172+
"There is no prior chat history with John Doe.",
173+
title="John Doe",
174+
key="Tab 1",
175+
),
176+
ui.tab(
177+
"There is no prior chat history with Jane Doe.",
178+
title="Jane Doe",
179+
key="Tab 2",
180+
),
181+
ui.tab(
182+
"There is no prior chat history with Joe Bloggs.",
183+
title="Joe Bloggs",
184+
key="Tab 3",
185+
),
186+
selected_key=selected_tab,
187+
on_selection_change=set_selected_tab,
188+
),
189+
background_color=get_background_color(selected_tab),
190+
flex="auto",
191+
width="100%",
192+
),
193+
ui.text(f"You have selected: {selected_tab}"),
194+
]
195+
196+
197+
my_tabs_on_change_example = ui_tabs_on_change_example()
198+
```
199+
200+
201+
## Keyboard activation
202+
203+
By default, pressing the arrow keys while currently focused on a tab will automatically switch selection to the adjacent tab in that key's direction.
204+
205+
To prevent this automatic selection change, the `keyboard_activation` prop can be set to "manual".
206+
207+
```python
208+
from deephaven import ui
209+
210+
211+
my_tabs_keyboard_activation_example = ui.tabs(
212+
ui.tab("Arma virumque cano, Troiae qui primus ab oris.", title="Founding of Rome"),
213+
ui.tab("Senatus Populusque Romanus.", title="Monarchy and Republic"),
214+
ui.tab("Alea jacta est.", title="Empire"),
215+
keyboard_activation="manual",
216+
)
217+
```
218+
219+
220+
## Density
221+
222+
By default, the density of the tab list is "compact". To change this, the `density` prop can be set to "regular".
223+
224+
```python
225+
from deephaven import ui
226+
227+
228+
@ui.component
229+
def ui_tabs_density_examples():
230+
return [
231+
ui.tabs(
232+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
233+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
234+
ui.tab(
235+
"There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"
236+
),
237+
density="regular",
238+
),
239+
]
240+
241+
242+
my_tabs_density_examples = ui_tabs_density_examples()
243+
```
244+
245+
246+
## Quiet State
247+
248+
The `is_quiet` prop makes tabs "quiet" by removing the line separating the tab titles and panel contents. This can be useful when the tabs should not distract users from surrounding content.
249+
250+
```python
251+
from deephaven import ui
252+
253+
254+
my_tabs_is_quiet_example = ui.tabs(
255+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
256+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
257+
ui.tab("There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"),
258+
is_quiet=True,
259+
)
260+
```
261+
262+
263+
## Disabled state
264+
265+
The `is_disabled` prop disables the tabs component to prevent user interaction. This is useful when tabs should be visible but not available for selection.
266+
267+
```python
268+
from deephaven import ui
269+
270+
271+
my_tabs_is_disabled_example = ui.tabs(
272+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
273+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
274+
ui.tab("There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"),
275+
is_disabled=True,
276+
)
277+
```
278+
279+
## Orientation
280+
281+
By default, tabs are horizontally oriented. To change the tabs' orientation, set the `orientation` prop to "vertical".
282+
283+
```python
284+
from deephaven import ui
285+
286+
287+
@ui.component
288+
def ui_tabs_orientation_examples():
289+
return [
290+
ui.tabs(
291+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
292+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
293+
ui.tab(
294+
"There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"
295+
),
296+
orientation="vertical",
297+
),
298+
ui.tabs(
299+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
300+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
301+
ui.tab(
302+
"There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"
303+
),
304+
),
305+
]
306+
307+
308+
my_tabs_orientation_examples = ui_tabs_orientation_examples()
309+
```
310+
311+
312+
## Overflow behaviour
313+
314+
If there isn't enough horizontal space to render all tabs on a single line, the component will automatically collapse all tabs into a Picker.
315+
316+
Note that this only occurs when tabs are horizontally oriented; when tabs are vertically oriented, the list continues to extend downwards.
317+
318+
```python
319+
from deephaven import ui
320+
321+
322+
@ui.component
323+
def ui_tabs_overflow_example():
324+
return [
325+
ui.view(
326+
ui.tabs(
327+
ui.tab(
328+
"There is no prior chat history with John Doe.", title="John Doe"
329+
),
330+
ui.tab(
331+
"There is no prior chat history with Jane Doe.", title="Jane Doe"
332+
),
333+
ui.tab(
334+
"There is no prior chat history with Joe Bloggs.",
335+
title="Joe Bloggs",
336+
),
337+
),
338+
width="80px",
339+
)
340+
]
341+
342+
343+
my_tabs_overflow_example = ui_tabs_overflow_example()
344+
```
345+
346+
347+
## Emphasized
348+
349+
The `is_emphasized` prop makes the line underneath the selected tab the user's accent color, adding a visual prominence to the selection.
350+
351+
```python
352+
from deephaven import ui
353+
354+
355+
my_tabs_is_emphasized_example = ui.tabs(
356+
ui.tab("There is no prior chat history with John Doe.", title="John Doe"),
357+
ui.tab("There is no prior chat history with Jane Doe.", title="Jane Doe"),
358+
ui.tab("There is no prior chat history with Joe Bloggs.", title="Joe Bloggs"),
359+
is_emphasized=True,
360+
)
361+
```
362+
363+
364+
## API Reference
365+
366+
```{eval-rst}
367+
.. dhautofunction:: deephaven.ui.tabs
368+
```

‎plugins/ui/docs/sidebar.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,10 @@
117117
"label": "Table",
118118
"path": "components/table.md"
119119
},
120+
{
121+
"label": "tabs",
122+
"path": "components/tabs.md"
123+
},
120124
{
121125
"label": "text",
122126
"path": "components/text.md"

0 commit comments

Comments
 (0)