CSC Design System v4.0.0
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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

  • justify places the tabs along the row: stretch (the default) grows them to fill it; start, center and end keep each tab at its own width.
  • borderless removes the line along the tab row.
  • vertical stacks 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 the c-tabs element itself is narrower than mobile-breakpoint (640px by default — the element's width, not the viewport's), the column moves above the panels. mobile-breakpoint does nothing for horizontal tabs, and justify does 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

Basic
Vue React Angular TypeScript
<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>
Vertical
Vue React Angular TypeScript
<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>
Basic · c-tab
Vue React Angular TypeScript
<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>
Basic · c-tab-items
Vue React Angular TypeScript
<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>
Basic · c-tab-buttons
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
borderlessborderlessbooleanfalse Remove the line along the tab row.
disableAnimationdisable-animationbooleanfalse Switch off the underline's glide and the panels' slide; both also stop under the reduced-motion preference.
justifyjustifyCTabsJustify'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.
mobileBreakpointmobile-breakpointnumber640 Width in pixels of the `c-tabs` element (not the viewport) below which `vertical` tabs move above the panels. No effect on horizontal tabs.
valuevaluenumber | string0 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.
verticalverticalbooleanfalse Stack the tabs in a column beside the panels, which slide vertically; below `mobile-breakpoint` the column moves above the panels.

Events

EventDetailDescription
changenumber | stringFired when the user activates another tab (click, or Enter/Space on a focused tab), carrying the newly selected tab value.
inputvoidNative bubbling input event dispatched for plain `v-model` support; carries no detail.
update:valuenumber | stringFired alongside `change` with the same detail — the `v-model` contract.

Slots

SlotDescription
defaultThe `c-tab` headers, or one `c-tab-buttons`
itemsThe `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.

PartDescription
containerThe tab row: the tabs plus the overflow arrows
tabsThe viewport the tab list scrolls inside; it clips with room for a tab's focus ring and a slotted corner badge
contentThe 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

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalse Grey the tab out and keep it from being selected by pointer or keyboard; the arrow keys skip it.
valuevaluenumber | 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

SlotDescription
defaultThe 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.

PartDescription
rootThe 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

SlotDescription
defaultThe `c-tab-item` panels

CSS parts

Style from outside with c-tab-items::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe 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

PropertyAttributeTypeDefaultDescription
valuevaluenumber | string0 Value of the panel, the same as its `c-tab`'s; the panel shows while the `value` of `c-tabs` equals it.

Slots

SlotDescription
defaultThe panel's content

CSS parts

Style from outside with c-tab-item::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe 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

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalse Disable the whole tab strip — every slotted c-button is disabled and the selection can no longer be changed.
sizesizeCTabButtonsSize'default' Size of the buttons: `default`, or the more compact `small`.

Slots

SlotDescription
defaultDefault 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.

PartDescription
rootThe segmented-control box framing the buttons
indicatorThe sliding fill highlighting the active tab
scroll-backThe edge arrow that scrolls an overflowing strip back
scroll-forwardThe 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';