<c-tabs>
A tab set that switches between panels of related content: a row of `c-tab` headers above the `c-tab-item` panels, one panel shown at a time.
Usage
Give each c-tab a value and the panel it shows the same value. The panels go in a c-tab-items slotted into c-tabs with slot="items". Bind the active value with value (or v-model); change fires with the new value when the user picks another tab.
<c-tabs value="summary">
<c-tab value="summary">Summary</c-tab>
<c-tab value="members">Members</c-tab>
<c-tab-items slot="items">
<c-tab-item value="summary">…</c-tab-item>
<c-tab-item value="members">…</c-tab-item>
</c-tab-items>
</c-tabs>
When to use
- Views of one subject that the user does not need side by side — a project's summary, members and settings.
- For a sequence the user moves through in order, show where they are with
c-steps. - For a choice that is a form value, use
c-button-group, not tabs.
Value
value is the active tab's value. Set it to one of the tabs: with no match, no tab is active, no panel is shown and the tab row has no Tab stop. Values are compared with ===, and an attribute is always a string, so a tab written value="2" does not match a number 2 bound to c-tabs — use strings throughout, or bind numbers on the tabs and panels too.
change carries the new value when the user activates a different tab: a click, or Enter or Space on a focused tab. Activating the active tab fires nothing, and setting value from code fires nothing either.
<c-tabs :value="tab" @change="tab = $event.detail">…</c-tabs>
Keyboard
Only the active tab is in the Tab order (the first enabled tab while no tab matches value). The Left and Right arrow keys — Up and Down in the vertical layout — move focus to the previous or next enabled tab, stopping at the first and the last; Home and End go to the first and the last. A tab out of view scrolls into the row. Moving focus does not switch panels: Enter or Space activates the focused tab.
Disabled tabs
Set disabled on a c-tab to show it greyed out and keep it from being selected by pointer or keyboard; the arrow keys skip it, and it is announced as disabled. Its panel stays in c-tab-items but cannot be reached through the tab.
Layout
justifyplaces the tabs along the row:stretch(the default) grows them to fill it;start,centerandendkeep each tab at its own width.borderlessremoves the line along the tab row.verticalstacks the tabs in a column beside the panels, marks the active tab with a bar on the column's edge, and slides the panels vertically. When thec-tabselement itself is narrower thanmobile-breakpoint(640px by default — the element's width, not the viewport's), the column moves above the panels.mobile-breakpointdoes nothing for horizontal tabs, andjustifydoes nothing for vertical ones.
Overflowing tab row
The horizontal tab row is one line and never wraps. When the tabs are wider than the row, arrow buttons appear at both ends; each press scrolls by half the row's width, and on a touch screen the row also pans with a sideways drag (a vertical swipe that starts on the row scrolls the page). A tab that becomes active, or that the arrow keys move to, is scrolled into view. There is no scrollbar. Vertical tabs do not scroll this way.
Panels
Every panel stays in the DOM; only the active one's content is shown. Content in an inactive panel keeps its state across switches, so a half-filled form is still filled in when the user comes back to it.
Motion
The underline glides to the active tab and the panels slide into place. disable-animation switches both off, and they stop under the reduced-motion preference too.
Tab buttons
To show the tab list as a segmented control instead of the underlined row, put one c-tab-buttons with c-button children where the c-tab elements would go; each button's value names its panel as a tab's would. c-tabs still owns value, change and the panels, while the strip brings its own keyboard handling and sliding indicator (see c-tab-buttons). For a segmented control that holds a form value outside tabs, use c-button-group.
Accessibility
c-tabs applies the tab pattern's roles: the row of tabs is the tablist (aria-orientation="vertical" in the vertical layout; the scroll arrows and the panels sit outside it), each c-tab a tab carrying aria-selected, and each c-tab-item a tabpanel; with c-tab-buttons its buttons are the tabs. A tab and its panel point at each other through aria-controls and aria-labelledby; an id you set on a tab or a panel is kept, and the others are generated. An aria-label on c-tabs names the tablist; when a page holds more than one tab set, give each one so they can be told apart.
Customization
The tab row is ::part(container) (the tabs plus the overflow arrows), with ::part(tabs) the viewport the tabs scroll inside; ::part(content) wraps the panels. Each child has a root part: c-tab::part(root) is the box centring a tab's label, c-tab-items::part(root) the track the panels slide on, and c-tab-item::part(root) a panel's padded content box.
c-tab-item::part(root) {
padding: 16px 0;
}
Tab labels and the underline use the primary role, a hovered tab the primary-subtle-hover fill, and the row's line the border role; override the tokens to re-theme.
<c-tab-buttons>
Tab buttons present a c-tabs tab list as a segmented control instead of
the underlined tab row. Author it only inside <c-tabs>, with plain
<c-button> children whose values match the c-tab-item panels; c-tabs
owns the active value and pushes it down.
This component carries no form semantics — no label, required, or
mandatory — and the selection cannot be toggled off: a tab strip always
has an active tab. The sliding indicator that glides to the active tab is
this component's own affordance. For a standalone segmented control that
holds a form value, use c-button-group (which this component wraps
internally); there, active buttons paint their own fill and nothing slides.
A tab strip is always one row. When it is wider than its box it scrolls
sideways — by touch, by a mouse drag, by the wheel, or with the edge arrows
that appear while it overflows — and the tab c-tabs makes active is
scrolled into view. The scrollbar is hidden; the half-visible tab at the
edge and the arrows are the cue. The underlined tab row of c-tabs follows
the same one-row rule, but scrolls only by touch and with its arrows.
Accessibility
The strip is the tab set's tablist and each button a tab, its selected
state announced as aria-selected (the buttons are not toggle buttons here);
the edge arrows sit outside the tablist. An aria-label on the c-tabs
around it names the tablist. The arrow keys move focus between the buttons,
and Enter or Space activates the focused one.
Examples
<template>
<div>
<c-tabs v-model="tab">
<c-tab value="summary">Summary</c-tab>
<c-tab value="members">
Members
<c-badge>2</c-badge>
</c-tab>
<c-tab value="settings">Settings</c-tab>
<c-tab-items slot="items">
<c-tab-item value="summary">
<p>Overview of the project and its recent activity.</p>
</c-tab-item>
<c-tab-item value="members">
<p>People with access to this project.</p>
</c-tab-item>
<c-tab-item value="settings">
<p>Project name, description and visibility.</p>
</c-tab-item>
</c-tab-items>
</c-tabs>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const tab = ref<'members' | 'settings' | 'summary'>('summary');
</script>
<template>
<div>
<c-tabs value="profile" vertical>
<c-tab value="profile">Profile</c-tab>
<c-tab value="security">Security</c-tab>
<c-tab value="tokens">API tokens</c-tab>
<c-tab-items slot="items">
<c-tab-item value="profile">
<p>Your name, email and avatar.</p>
</c-tab-item>
<c-tab-item value="security">
<p>Password and two-factor authentication.</p>
</c-tab-item>
<c-tab-item value="tokens">
<p>Personal access tokens for the API.</p>
</c-tab-item>
</c-tab-items>
</c-tabs>
</div>
</template>
<template>
<div>
<c-tabs value="summary">
<c-tab value="summary">Summary</c-tab>
<c-tab value="members">Members</c-tab>
<c-tab value="settings" disabled>Settings</c-tab>
<c-tab-items slot="items">
<c-tab-item value="summary">
<p>Overview of the project and its recent activity.</p>
</c-tab-item>
<c-tab-item value="members">
<p>People with access to this project.</p>
</c-tab-item>
<c-tab-item value="settings">
<p>Project name, description and visibility.</p>
</c-tab-item>
</c-tab-items>
</c-tabs>
</div>
</template>
<template>
<div>
<c-tabs value="summary">
<c-tab value="summary">Summary</c-tab>
<c-tab value="members">Members</c-tab>
<c-tab value="settings">Settings</c-tab>
<c-tab-items slot="items">
<c-tab-item value="summary">
<p>Overview of the project and its recent activity.</p>
</c-tab-item>
<c-tab-item value="members">
<p>People with access to this project.</p>
</c-tab-item>
<c-tab-item value="settings">
<p>Project name, description and visibility.</p>
</c-tab-item>
</c-tab-items>
</c-tabs>
</div>
</template>
<template>
<c-tabs v-model="tab">
<c-tab-buttons>
<c-button value="overview">Overview</c-button>
<c-button value="members">Members</c-button>
<c-button value="settings">Settings</c-button>
</c-tab-buttons>
<c-tab-items slot="items">
<c-tab-item value="overview">
<p>Overview of the project and its recent activity.</p>
</c-tab-item>
<c-tab-item value="members">
<p>People with access to this project.</p>
</c-tab-item>
<c-tab-item value="settings">
<p>Project name, description and visibility.</p>
</c-tab-item>
</c-tab-items>
</c-tabs>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const tab = ref<'members' | 'overview' | 'settings'>('overview');
</script>
API reference
<c-tabs>
A tab set that switches between panels of related content: a row of `c-tab` headers above the `c-tab-item` panels, one panel shown at a time.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
borderless | borderless | boolean | false | Remove the line along the tab row. |
disableAnimation | disable-animation | boolean | false | Switch off the underline's glide and the panels' slide; both also stop under the reduced-motion preference. |
justify | justify | CTabsJustify | 'stretch' | Placement of the tabs along the row: `stretch` grows them to fill it; `start`, `center` and `end` keep each tab at its own width. No effect on `vertical` tabs. |
mobileBreakpoint | mobile-breakpoint | number | 640 | Width in pixels of the `c-tabs` element (not the viewport) below which `vertical` tabs move above the panels. No effect on horizontal tabs. |
value | value | number | string | 0 | Value of the active tab: the `c-tab` and the `c-tab-item` with the same `value` are shown. With no match, no tab is active and no panel is shown. |
vertical | vertical | boolean | false | Stack the tabs in a column beside the panels, which slide vertically; below `mobile-breakpoint` the column moves above the panels. |
Events
| Event | Detail | Description |
|---|---|---|
change | number | string | Fired when the user activates another tab (click, or Enter/Space on a focused tab), carrying the newly selected tab value. |
input | void | Native bubbling input event dispatched for plain `v-model` support; carries no detail. |
update:value | number | string | Fired alongside `change` with the same detail — the `v-model` contract. |
Slots
| Slot | Description |
|---|---|
default | The `c-tab` headers, or one `c-tab-buttons` |
items | The `c-tab-items` holding the panels |
CSS parts
Style from outside with c-tabs::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
container | The tab row: the tabs plus the overflow arrows |
tabs | The viewport the tab list scrolls inside; it clips with room for a tab's focus ring and a slotted corner badge |
content | The wrapper around the panels |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CTabsJustify
Justification of the tab headers along the tab row. `stretch` grows the tabs to fill the full row width.
export type CTabsJustify = 'center' | 'end' | 'start' | 'stretch';<c-tab>
One tab in the row of a `c-tabs`: its label goes in the default slot (a `c-badge` there sits on the tab's corner), and its `value` names the `c-tab-item` panel it shows. `c-tabs` decides which tab is active; `disabled` keeps a tab from being selected.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Grey the tab out and keep it from being selected by pointer or keyboard; the arrow keys skip it. |
value | value | number | string | — | Value of the tab, matching the `value` of the `c-tab-item` panel it shows; `c-tabs` holds it as its `value` while this tab is active. |
Slots
| Slot | Description |
|---|---|
default | The tab's label; a `c-badge` here sits on the tab's corner |
CSS parts
Style from outside with c-tab::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The box centring the tab's label |
<c-tab-items>
The panel container of a `c-tabs`: slot it in with `slot="items"` and put the `c-tab-item` panels inside it. It shows the panel whose `value` matches the tabs' value and slides between panels; it has no props of its own, as `c-tabs` drives it.
Slots
| Slot | Description |
|---|---|
default | The `c-tab-item` panels |
CSS parts
Style from outside with c-tab-items::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The track the panels slide on |
<c-tab-item>
One tab panel inside `c-tab-items`, shown while its `value` equals the `value` of `c-tabs` — give it the same `value` as its `c-tab`. Inactive panels stay in the DOM, hidden, so their content keeps its state across tab switches.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
value | value | number | string | 0 | Value of the panel, the same as its `c-tab`'s; the panel shows while the `value` of `c-tabs` equals it. |
Slots
| Slot | Description |
|---|---|
default | The panel's content |
CSS parts
Style from outside with c-tab-item::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The panel's padded content box |
<c-tab-buttons>
Tab buttons present a `c-tabs` tab list as a segmented control instead of the underlined tab row. Author it only inside `<c-tabs>`, with plain `<c-button>` children whose `value`s match the `c-tab-item` panels; `c-tabs` owns the active value and pushes it down.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Disable the whole tab strip — every slotted c-button is disabled and the selection can no longer be changed. |
size | size | CTabButtonsSize | 'default' | Size of the buttons: `default`, or the more compact `small`. |
Slots
| Slot | Description |
|---|---|
default | Default slot for the c-button elements |
CSS parts
Style from outside with c-tab-buttons::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The segmented-control box framing the buttons |
indicator | The sliding fill highlighting the active tab |
scroll-back | The edge arrow that scrolls an overflowing strip back |
scroll-forward | The edge arrow that scrolls an overflowing strip forward |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CTabButtonsSize
Size of the tab strip. `small` renders a more compact control; the size is also propagated to every slotted `<c-button>`. Omitting the attribute renders the default size.
export type CTabButtonsSize = 'default' | 'small';