On this page

Tabs Primitive

Tabs is a Starwind Runtime primitive in the controlled-value-group contract family. Astro, React, Vue, and Svelte components use the same underlying interactions. Each framework has its own way to read and update state. See the examples and your installed package’s types for the available props and events. Plain HTML uses DOM events and Runtime methods.

Usage Guidelines

Animate panel changes with CSS. Apply transitions or keyframe animations to the panel. Use data-starting-style for its entrance and data-ending-style for its exit. Initial panels appear without an entrance animation. The animated Styled Tabs example shows a crossfade with reduced-motion support.
Keep visibility under Runtime control. An outgoing panel becomes inert immediately, then receives hidden when its own finite motion finishes. Its controls cannot receive input during the exit. Descendant motion and infinite animations do not delay hiding. Panel DOM and local state remain mounted; keepMounted preserves its existing behavior.
Keep keyboard entry aligned with selection. When code changes the selected tab while focus is outside the tab list, the selected enabled trigger becomes the next keyboard entry target. Browser focus stays where it is. While focus is inside the list, Tabs preserves the user’s keyboard position.

Anatomy

Use the Astro primitive adapter to render Tabs anatomy with the Runtime wiring included.

---
import { Tabs } from "@starwind-ui/astro/tabs";
---

<Tabs.Root defaultValue="account">
  <Tabs.List>
    <Tabs.Tab value="account">Account</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="account">Account settings</Tabs.Panel>
</Tabs.Root>

Use the React primitive adapter when Tabs state participates in React rendering.

import { Tabs } from "@starwind-ui/react/tabs";

export function Example() {
  return (
    <Tabs.Root defaultValue="account">
      <Tabs.List>
        <Tabs.Tab value="account">Account</Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel value="account">Account settings</Tabs.Panel>
    </Tabs.Root>
  );
}

Use the Vue components to build Tabs.

<script setup lang="ts">
import Tabs from "@starwind-ui/vue/tabs";
</script>

<template>
  <Tabs.Root defaultValue="account">
    <Tabs.List>
      <Tabs.Tab value="account">Account</Tabs.Tab>
    </Tabs.List>
    <Tabs.Panel value="account">Account settings</Tabs.Panel>
  </Tabs.Root>
</template>

Render the Tabs data-sw-* contract yourself, then initialize createTabs.

<div data-sw-tabs data-default-value="account">
  <div data-sw-tabs-list role="tablist">
    <button data-sw-tabs-tab role="tab" type="button" data-value="account">Account</button>
  </div>
  <div data-sw-tabs-panel role="tabpanel" hidden data-value="account">Account settings</div>
</div>

<script type="module">
  import { createTabs } from "@starwind-ui/runtime/tabs";

  const root = document.querySelector("[data-sw-tabs]");
  if (root) {
    createTabs(root);
  }
</script>

API Reference

Root

The main element that owns the Tabs Runtime instance.

Default element: div
Discovery hook: data-sw-tabs
Role: -

Props

Prop Type Default

value TabsValue -

Description

Controls the current Tabs value.

Kind

control

Targets

root

Full type

TabsValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

defaultValue TabsValue -

Description

Sets the initial Tabs value for uncontrolled usage.

Kind

control

Targets

Full type

TabsValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

orientation TabsOrientation "horizontal"

Description: Sets the Tabs orientation.
Kind: option
Targets: -
Full type: TabsOrientation

syncKey string -

Description: Configures the sync key option for the Root part.
Kind: option
Targets: -
Full type: string

onValueChange (value: TabsValue, details: TabsValueChangeDetails) => void -

Description

Runs when the Tabs value changes.

Kind

callback

Targets

Full type

(value: TabsValue, details: TabsValueChangeDetails) => void

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Events

Event Callback Value

valueChange onValueChange value: TabsValue

Description

Fires when the value changes for Tabs.

DOM event

starwind:value-change

Details type

TabsValueChangeDetails

Timing

before-state-commit

Cancelable

Yes

Cancellation sequence

Check internal eligibility and intent.
Create one details object for the proposal.
Call the Runtime callback with the details object when the controller exposes one.
Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
Read details.isCanceled, including cancellation caused by preventDefault().
Apply the accepted state.
Notify Runtime subscribers and other accepted-only observers.

State

State Type Props

value TabsValue value / defaultValue

Description

Tracks the current Tabs value.

Initial attribute

data-default-value

Runtime getter

getValue

Runtime setter

setValue

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tabs - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-value - Reflects the value state on the Root part.

Metadata

Attribute Value Description

data-default-value - Reflects the default value prop on the Root part.

data-orientation - Reflects the orientation prop on the Root part.

data-sync-key - Reflects the sync key prop on the Root part.

List

The list of selectable Tabs items.

Default element: div
Discovery hook: data-sw-tabs-list
Role: tablist

Props

Prop Type Default

activateOnFocus boolean false

Description: Configures the activate on focus option for the List part.
Kind: option
Targets: list
Full type: boolean

loopFocus boolean true

Description: Lets keyboard focus wrap around the Tabs items.
Kind: option
Targets: list
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tabs-list - Marks the List part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-activate-on-focus - Reflects the activate on focus prop on the List part.

data-loop-focus - Reflects the loop focus prop on the List part.

data-orientation - Reflects the orientation prop on the List part.

Tab

A selectable tab inside Tabs.

Default element: button
Discovery hook: data-sw-tabs-tab
Role: tab

Props

Prop Type Default

disabled boolean false

Description: Disables the Tab part.
Kind: option
Targets: tab
Full type: boolean

value string -

Description

Controls the current Tabs value.

Kind

option

Targets

tab

Full type

string

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tabs-tab - Marks the Tab part so Starwind Runtime can find it.

State

Attribute Value Description

data-active - Reflects the active state on the Tab part.

data-orientation - Reflects the orientation state on the Tab part.

data-state - Reflects the current state on the Tab part.

Metadata

Attribute Value Description

data-disabled - Reflects the disabled prop on the Tab part.

data-value - Reflects the value prop on the Tab part.

Panel

The content panel controlled by Tabs.

Default element: div
Discovery hook: data-sw-tabs-panel
Role: tabpanel

Props

Prop Type Default

keepMounted boolean false

Description: Keeps the Panel part in the DOM when hidden.
Kind: rendering
Targets: panel
Full type: boolean

value string -

Description

Controls the current Tabs value.

Kind

option

Targets

panel

Full type

string

React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

value
defaultValue
onValueChange

Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

value
defaultValue
starwind:value-change
setValue

Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

data-default-value
starwind:value-change
setValue

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tabs-panel - Marks the Panel part so Starwind Runtime can find it.

State

Attribute Value Description

data-active - Reflects the active state on the Panel part.

data-orientation - Reflects the orientation state on the Panel part.

data-state - Reflects the current state on the Panel part.

Metadata

Attribute Value Description

data-keep-mounted - Reflects the keep mounted prop on the Panel part.

data-value - Reflects the value prop on the Panel part.

Indicator

Visual state indicator rendered by Tabs.

Default element: span
Discovery hook: data-sw-tabs-indicator
Role: presentation

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-tabs-indicator - Marks the Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-orientation - Reflects the orientation state on the Indicator part.

Runtime API

Factory: createTabs
Import: @starwind-ui/runtime/tabs
Root hook: root data-sw-tabs
Option props: defaultValue, orientation, syncKey, value

Option Lifecycles

Option	Lifecycle
syncKey	constructor-only

Runtime Setters

Method Target Description

setValue state: value Updates the current Tabs value from Runtime code.

Component Relationship

Tabs Direct primitive

Changelog

View version history v1.1.0 5 releases

v1.1.0

Vue Tabs keeps the selected tab when a selection change is canceled.
Tabs keeps its initial `syncKey` while mounted. Remount it to change that key.
Added CSS entrance and exit animations using `data-starting-style` and `data-ending-style`. Panels stay visible until their exit animation finishes, while inactive content stops accepting keyboard focus and clicks.
When your code selects a tab, pressing Tab to enter the tab list now focuses that tab. Focus stays in place while someone is already navigating the list.
Reduced repeated JavaScript when Astro Tabs is used with other Starwind components.

v1.0.1

Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
Measured the active tab indicator in local layout coordinates so scrolling and transforms preserve its alignment.

v1.0.0

Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.1

Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.

v0.1.0

Introduced tab selection, roving focus, panel presence, orientation, and synchronized groups.

Layer Metadata

Tabs Primitive uses createTabs. Styled components: Tabs.

primitive Tabs Primitive Tabs Primitive uses createTabs. Styled components: Tabs. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters tabs Tabs Controlled Value Group Grouped controls coordinated by a shared selected value. /docs/primitives/tabs/ createTabs @starwind-ui/runtime/tabs /docs/runtime/#create-tabs root defaultValue orientation syncKey value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Tabs data-sw-* contract yourself, then initialize createTabs. html Use the Astro primitive adapter to render Tabs anatomy with the Runtime wiring included. Use the React primitive adapter when Tabs state participates in React rendering. tsx Use the Vue components to build Tabs. div data-sw-tabs TabsValue Controls the current Tabs value. Sets the initial Tabs value for uncontrolled usage. TabsOrientation Sets the Tabs orientation. string Configures the sync key option for the Root part. onValueChange (value: TabsValue, details: TabsValueChangeDetails) => void TabsValueChangeDetails Runs when the Tabs value changes. runtime Marks the Root part so Starwind Runtime can find it. data-default-value prop Reflects the default value prop on the Root part. data-orientation Reflects the orientation prop on the Root part. data-sync-key Reflects the sync key prop on the Root part. data-value state Reflects the value state on the Root part. getValue setValue valueChange starwind:value-change list data-sw-tabs-list tablist activateOnFocus boolean Configures the activate on focus option for the List part. loopFocus Lets keyboard focus wrap around the Tabs items. Marks the List part so Starwind Runtime can find it. data-activate-on-focus Reflects the activate on focus prop on the List part. data-loop-focus Reflects the loop focus prop on the List part. Reflects the orientation prop on the List part. tab button data-sw-tabs-tab disabled Disables the Tab part. Marks the Tab part so Starwind Runtime can find it. data-active Reflects the active state on the Tab part. data-disabled Reflects the disabled prop on the Tab part. Reflects the orientation state on the Tab part. data-state Reflects the current state on the Tab part. Reflects the value prop on the Tab part. panel data-sw-tabs-panel tabpanel keepMounted Keeps the Panel part in the DOM when hidden. Marks the Panel part so Starwind Runtime can find it. Reflects the active state on the Panel part. data-keep-mounted Reflects the keep mounted prop on the Panel part. Reflects the orientation state on the Panel part. Reflects the current state on the Panel part. Reflects the value prop on the Panel part. indicator span data-sw-tabs-indicator presentation Marks the Indicator part so Starwind Runtime can find it. Reflects the orientation state on the Indicator part. Root List aria-orientation Tab aria-selected type Panel hidden inert Indicator @starwind-ui/astro @starwind-ui/astro/tabs Render initial tab anatomy and self-initialize; runtime refresh owns linked ids, roving focus, nested tabs, and indicator measurement. Runtime treats an empty string as a valid TabsValue and reserves literal "null" as the nullable serialization marker. @starwind-ui/react @starwind-ui/react/tabs Bridge controlled value through setValue with sync propagation. Snapshot panel hidden and tab tabindex from initial context so rerenders preserve Runtime presence and keyboard position. @starwind-ui/vue @starwind-ui/vue/tabs @starwind-ui/svelte @starwind-ui/svelte/tabs /docs/components/tabs/ Direct primitive direct-primitive Styled component Tabs

Tabs Primitive

Usage Guidelines

Anatomy

API Reference

Root

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

List

Props

Data Attributes

Runtime hooks

Metadata

Tab

Props

Data Attributes

Runtime hooks

State

Metadata

Panel

Props

Data Attributes

Runtime hooks

State

Metadata

Indicator

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components

Changelog

v1.1.0

v1.0.1

v1.0.0

v0.1.1

v0.1.0