On this page

Tabs Primitive

Tabs is a Starwind Runtime primitive in the controlled-value-group contract family.

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>
  );
}

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

defaultValue TabsValue -

Description: Sets the initial Tabs value for uncontrolled usage.
Kind: control
Targets: -
Full type: TabsValue

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

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

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
State control support: React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.

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

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

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

Runtime Setters

Method Target Description

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

Component Relationship

Tabs Direct primitive

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 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 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 and provide context so child parts can render initial orientation/value state. /docs/components/tabs/ Direct primitive direct-primitive Styled component Tabs

Tabs Primitive

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

Runtime Setters

Related Styled Components