Tabs
Shows one panel from a set of layered sections.
Starting the preview. GPUI compiles to WebAssembly, so the first load takes a few seconds. This browser has neither WebGPU nor WebGL 2, so the live preview cannot run. The code on this page still works. The preview did not start.
fn tabs_preview(&self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
let value = window.use_keyed_state("tabs", cx, |_, _| SharedString::from("account"));
let selected = value.read(cx).clone();
div()
.w_full()
.max_w(px(320.))
.flex()
.flex_col()
.gap(px(16.))
.child(
Tabs::new("settings-tabs")
.aria_label("Settings")
.selected(selected.clone())
.item(Tab::new("account", "account", "Account"))
.item(Tab::new("password", "password", "Password"))
.item(Tab::new("billing", "billing", "Billing").disabled(true))
.on_change(move |next, _, cx| {
value.update(cx, |value, cx| {
*value = next.clone();
cx.notify();
})
}),
)
.child(tabs_content("settings-panel", selected.clone(), cx).child(
if selected.as_ref() == "account" {
"Manage your account details."
} else {
"Change your account password."
},
))
}
Installation
After the one-time setup, run the command from your app root. The CLI
writes the modules and keeps src/ui/mod.rs in step.
gpuicn add tabs
If you prefer to copy the files by hand, declare them yourself:
// src/ui/mod.rs
pub mod theme;
pub mod tabs;
// src/main.rs
mod ui;
Usage
Put this in a view module and return example(window, cx) from its render method.
use crate::ui::tabs::*;
use gpui_kit::{App, IntoElement, ParentElement, Window};
fn example(window: &mut Window, cx: &mut App) -> impl IntoElement {
let selected = window.use_keyed_state("settings", cx, |_, _| {
gpui_kit::SharedString::from("account")
});
let value = selected.read(cx).clone();
gpui_kit::div()
.child(
Tabs::new("settings")
.selected(value.clone())
.item(Tab::new("account", "account", "Account"))
.item(Tab::new("password", "password", "Password"))
.on_change(move |value, _, cx| {
selected.update(cx, |selected, cx| {
*selected = value.clone();
cx.notify();
})
}),
)
.child(
tabs_content("settings.panel", value.clone(), cx).child(if value == "account" {
"Account settings"
} else {
"Password settings"
}),
)
}
Examples
Line
The line variant underlines the selected tab instead of filling it.
Starting the preview. GPUI compiles to WebAssembly, so the first load takes a few seconds. This browser has neither WebGPU nor WebGL 2, so the live preview cannot run. The code on this page still works. The preview did not start.
fn line(
_view: &Showcase,
window: &mut Window,
cx: &mut Context<Showcase>,
) -> impl IntoElement {
let value = window.use_keyed_state("line.value", cx, |_, _| SharedString::from("overview"));
let selected = value.read(cx).clone();
div()
.w_full()
.max_w(px(360.))
.flex()
.flex_col()
.gap(px(16.))
.child(
Tabs::new("line.tabs")
.variant(TabsVariant::Line)
.aria_label("Project")
.selected(selected.clone())
.item(Tab::new("line.overview", "overview", "Overview"))
.item(Tab::new("line.activity", "activity", "Activity"))
.item(Tab::new("line.settings", "settings", "Settings"))
.on_change(move |next, _, cx| {
value.update(cx, |value, cx| {
*value = next.clone();
cx.notify();
})
}),
)
.child(
tabs_content("line.panel", selected.clone(), cx)
.child(format!("The {selected} panel.")),
)
}
Disabled tab
A disabled tab stays in the row but is skipped by the pointer and the arrow keys.
Starting the preview. GPUI compiles to WebAssembly, so the first load takes a few seconds. This browser has neither WebGPU nor WebGL 2, so the live preview cannot run. The code on this page still works. The preview did not start.
fn disabled_tab(
_view: &Showcase,
window: &mut Window,
cx: &mut Context<Showcase>,
) -> impl IntoElement {
let value = window.use_keyed_state("off.value", cx, |_, _| SharedString::from("free"));
let selected = value.read(cx).clone();
Tabs::new("off.tabs")
.aria_label("Plan")
.selected(selected)
.item(Tab::new("off.free", "free", "Free"))
.item(Tab::new("off.team", "team", "Team"))
.item(Tab::new("off.enterprise", "enterprise", "Enterprise").disabled(true))
.on_change(move |next, _, cx| {
value.update(cx, |value, cx| {
*value = next.clone();
cx.notify();
})
})
}
API reference
pub fn new(
id: impl Into<ElementId>,
value: impl Into<SharedString>,
label: impl Into<SharedString>,
) -> Self
Creates a `Tab` with a stable caller-owned ID.
pub fn disabled(mut self, disabled: bool) -> Self
Disables interaction and applies the disabled appearance.
pub fn trailing(mut self, element: impl IntoElement) -> Self
Draws `element` after the label, such as a count badge or an unread dot. Describe what it says in the tab's accessible label too.
pub fn aria_label(mut self, label: impl Into<SharedString>) -> Self
Replaces the accessible label, for a tab whose trailing element says more than its visible label ("Design, 2 mentions").
pub fn on_secondary_click(
mut self,
handler: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
) -> Self
Runs `handler` on a secondary (right) click, to open the tab's context menu.
pub fn new(id: impl Into<ElementId>) -> Self
Creates a `Tabs` with a stable caller-owned ID.
pub fn selected(mut self, value: impl Into<SharedString>) -> Self
Sets the caller-owned selected tab value.
pub fn variant(mut self, variant: TabsVariant) -> Self
Selects the Nova surface style.
pub fn aria_label(mut self, label: impl Into<SharedString>) -> Self
Sets the accessible name of the control.
pub fn size(mut self, size: TabsSize) -> Self
Sets the label size.
pub fn text_colors(mut self, selected: impl Into<Rgba>, other: impl Into<Rgba>) -> Self
Draws the selected tab's label (and the line under it) in `selected` and the other labels in `other`, for tabs on a surface with its own colors, such as a sidebar.
pub fn end(mut self, element: impl IntoElement) -> Self
Draws `element` at the end of the row, after the tabs: a "More" menu for tabs that do not fit, or an add button.
pub fn item(mut self, item: Tab) -> Self
Appends an option to the group.
pub fn on_change(
mut self,
handler: impl Fn(&SharedString, &mut Window, &mut App) + 'static,
) -> Self
Reports a requested value change; retain the next value in the owning view.
pub fn tabs_content(
id: impl Into<ElementId>,
label: impl Into<SharedString>,
cx: &App,
) -> Stateful<Div>
Mount the selected content explicitly in the caller's render function.
Installed source, 311 lines
//! Nova tabs with controlled selection and automatic keyboard activation.
use super::theme::{
RovingFocus, UiTheme, apply_style,
locale::DirectionalStyled as _,
primitives::{disabled, focus, text},
};
use gpui_kit::{
AnyElement, App, Div, ElementId, InteractiveElement as _, IntoElement, MouseButton,
MouseDownEvent, ParentElement as _, RenderOnce, Rgba, Role, SharedString, Stateful,
StatefulInteractiveElement as _, StyleRefinement, Styled, Window, div,
prelude::FluentBuilder as _,
};
use std::rc::Rc;
#[derive(Clone, Copy, Default, PartialEq, Eq)]
/// The visual presentation of the tab list.
pub enum TabsVariant {
#[default]
/// The default Nova presentation.
Default,
/// Underline the selected tab.
Line,
}
#[derive(Clone, Copy, Default, PartialEq, Eq)]
/// How large the tabs are.
pub enum TabsSize {
#[default]
/// 14 px labels.
Default,
/// 13 px labels in a slightly shorter row, for sidebars and toolbars.
Sm,
}
type SecondaryHandler = Rc<dyn Fn(&MouseDownEvent, &mut Window, &mut App)>;
/// One tab with a stable ID, selection value and visible label.
pub struct Tab {
id: ElementId,
value: SharedString,
label: SharedString,
disabled: bool,
aria: Option<SharedString>,
trailing: Option<AnyElement>,
on_secondary: Option<SecondaryHandler>,
}
impl Tab {
/// Creates a `Tab` with a stable caller-owned ID.
pub fn new(
id: impl Into<ElementId>,
value: impl Into<SharedString>,
label: impl Into<SharedString>,
) -> Self {
Self {
id: id.into(),
value: value.into(),
label: label.into(),
disabled: false,
aria: None,
trailing: None,
on_secondary: None,
}
}
/// Disables interaction and applies the disabled appearance.
pub fn disabled(mut self, disabled: bool) -> Self {
self.disabled = disabled;
self
}
/// Draws `element` after the label, such as a count badge or an unread
/// dot. Describe what it says in the tab's accessible label too.
pub fn trailing(mut self, element: impl IntoElement) -> Self {
self.trailing = Some(element.into_any_element());
self
}
/// Replaces the accessible label, for a tab whose trailing element says
/// more than its visible label ("Design, 2 mentions").
pub fn aria_label(mut self, label: impl Into<SharedString>) -> Self {
self.aria = Some(label.into());
self
}
/// Runs `handler` on a secondary (right) click, to open the tab's
/// context menu.
pub fn on_secondary_click(
mut self,
handler: impl Fn(&MouseDownEvent, &mut Window, &mut App) + 'static,
) -> Self {
self.on_secondary = Some(Rc::new(handler));
self
}
}
type ChangeHandler = Rc<dyn Fn(&SharedString, &mut Window, &mut App)>;
#[derive(IntoElement)]
/// A controlled tab list with automatic keyboard selection.
pub struct Tabs {
id: ElementId,
selected: Option<SharedString>,
variant: TabsVariant,
label: Option<SharedString>,
size: TabsSize,
colors: Option<(Rgba, Rgba)>,
items: Vec<Tab>,
end: Option<AnyElement>,
on_change: Option<ChangeHandler>,
style: StyleRefinement,
}
impl Tabs {
/// Creates a `Tabs` with a stable caller-owned ID.
pub fn new(id: impl Into<ElementId>) -> Self {
Self {
id: id.into(),
selected: None,
variant: Default::default(),
label: None,
size: Default::default(),
colors: None,
items: Vec::new(),
end: None,
on_change: None,
style: Default::default(),
}
}
/// Sets the caller-owned selected tab value.
pub fn selected(mut self, value: impl Into<SharedString>) -> Self {
self.selected = Some(value.into());
self
}
/// Selects the Nova surface style.
pub fn variant(mut self, variant: TabsVariant) -> Self {
self.variant = variant;
self
}
/// Sets the accessible name of the control.
pub fn aria_label(mut self, label: impl Into<SharedString>) -> Self {
self.label = Some(label.into());
self
}
/// Sets the label size.
pub fn size(mut self, size: TabsSize) -> Self {
self.size = size;
self
}
/// Draws the selected tab's label (and the line under it) in
/// `selected` and the other labels in `other`, for tabs on a surface
/// with its own colors, such as a sidebar.
pub fn text_colors(mut self, selected: impl Into<Rgba>, other: impl Into<Rgba>) -> Self {
self.colors = Some((selected.into(), other.into()));
self
}
/// Draws `element` at the end of the row, after the tabs: a "More"
/// menu for tabs that do not fit, or an add button.
pub fn end(mut self, element: impl IntoElement) -> Self {
self.end = Some(element.into_any_element());
self
}
/// Appends an option to the group.
pub fn item(mut self, item: Tab) -> Self {
self.items.push(item);
self
}
/// Reports a requested value change; retain the next value in the owning view.
pub fn on_change(
mut self,
handler: impl Fn(&SharedString, &mut Window, &mut App) + 'static,
) -> Self {
self.on_change = Some(Rc::new(handler));
self
}
}
impl Styled for Tabs {
fn style(&mut self) -> &mut StyleRefinement {
&mut self.style
}
}
impl RenderOnce for Tabs {
fn render(self, window: &mut Window, cx: &mut App) -> impl IntoElement {
let theme = UiTheme::read(cx).clone();
let colors = theme.colors;
let selected = self
.items
.iter()
.position(|i| Some(&i.value) == self.selected.as_ref());
let focus = RovingFocus::new(
self.id.clone(),
&self
.items
.iter()
.map(|i| (i.id.clone(), i.disabled))
.collect::<Vec<_>>(),
selected,
window,
cx,
);
let values: Vec<_> = self.items.iter().map(|i| i.value.clone()).collect();
let count = self.items.len();
let (selected_color, other_color) = self
.colors
.unwrap_or((colors.foreground, colors.muted_foreground));
let (height, size) = match self.size {
TabsSize::Default => (6.5, 14.),
TabsSize::Sm => (6., 13.),
};
let children = self
.items
.into_iter()
.enumerate()
.map(|(index, item)| {
let active = Some(index) == selected;
let change = self.on_change.clone();
let handle = focus.handles[index].as_ref();
gpui_kit::base::Tab::new(item.id)
.accessibility_label(item.aria.unwrap_or_else(|| item.label.clone()))
.flex()
.items_center()
.gap(theme.space(1.5))
.child(item.label)
.children(item.trailing)
.selected(active)
.disabled(item.disabled)
.set_position(index + 1, count)
.when_some(handle, |tab, h| tab.track_focus(h))
.h(theme.space(height))
.px(theme.space(1.5))
.py(theme.space(0.5))
.map(|tab| text::control(tab, &theme, theme.text(size)))
.text_color(if active { selected_color } else { other_color })
.when(self.variant == TabsVariant::Default, |tab| {
tab.rounded(theme.radius.sm)
.border_1()
.border_color(colors.background.opacity(0.))
.when(active, |tab| {
tab.bg(colors.background).shadow(theme.shadows.sm.to_vec())
})
})
.when(self.variant == TabsVariant::Line, |tab| {
tab.border_b_2().border_color(if active {
selected_color
} else {
colors.background.opacity(0.)
})
})
.map(|tab| disabled::interactive(tab, item.disabled))
.focus_visible({
let theme = theme.clone();
move |s| focus::ring(s, &theme)
})
.when_some(change, |tab, handler| {
tab.on_click(move |_, window, cx| handler(&item.value, window, cx))
})
.when_some(item.on_secondary, |tab, handler| {
tab.on_mouse_down(MouseButton::Right, move |event, window, cx| {
// GPUI focuses the tab on this press after the
// handler runs, which would take focus from the
// context menu the handler just opened.
window.prevent_default();
handler(event, window, cx)
})
})
})
.collect::<Vec<_>>();
let on_change = self.on_change;
// Not `gpui_kit::base::Tabs`: since GPUI Kit 0.10 its tabs take over
// focus and move it with the arrows without selecting (manual
// activation). These tabs select as focus moves, like shadcn's, so
// the list keeps its own roving focus and only borrows the role.
let root = div()
.id(self.id)
.role(Role::TabList)
.aria_orientation(gpui_kit::Orientation::Horizontal)
.flex_row_in(theme.direction)
.items_center()
.when_some(self.label, |root, label| root.aria_label(label))
.when(self.variant == TabsVariant::Default, |root| {
root.h(theme.space(8.))
.rounded(theme.radius.lg)
.p(theme.space(0.75))
.bg(colors.muted)
})
.when(self.variant == TabsVariant::Line, |root| {
root.gap(theme.space(1.))
.border_b_1()
.border_color(colors.border)
})
.on_key_down(move |event, window, cx| {
if let Some(index) = focus.key(event, Some(gpui_kit::Axis::Horizontal), window, cx)
&& let Some(change) = &on_change
{
change(&values[index], window, cx);
}
})
.children(children)
.children(self.end);
apply_style(root, &self.style)
}
}
/// Mount the selected content explicitly in the caller's render function.
pub fn tabs_content(
id: impl Into<ElementId>,
label: impl Into<SharedString>,
cx: &App,
) -> Stateful<Div> {
let theme = UiTheme::read(cx);
div()
.id(id)
.role(Role::TabPanel)
.aria_label(label)
.tab_index(0)
.flex_1()
.map(|panel| text::sm(panel, theme))
.text_color(theme.colors.foreground)
}
Platform notes
Visual reference: shadcn/ui 4.19.0, Neutral Nova. Implementation:
crates/ui/registry/tabs/tabs.rs, using GPUI Kit 0.6.4.
The application passes the selected value and renders its matching panel. The tab list keeps one Tab stop; arrows and Home/End select enabled tabs. Kit tab primitives supply roles and control interaction. Nova supports filled and line variants.
The Rust source and Usage example define the supported API. Browser DOM/CSS behavior, exact exit animations and cross-platform screen-reader parity are not implied by the native component. See migration qualification for the checks completed on this revision.