On this page

Sidebar Primitive

Sidebar is a Starwind Runtime primitive in the presence-disclosure-control contract family. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

Anatomy

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

---
import { Sidebar } from "@starwind-ui/astro/sidebar";
---

<Sidebar.Provider>
  <Sidebar.Sidebar>
    <Sidebar.MenuButton>Dashboard</Sidebar.MenuButton>
  </Sidebar.Sidebar>
  <Sidebar.Trigger>Toggle sidebar</Sidebar.Trigger>
  <Sidebar.Rail />
</Sidebar.Provider>

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

import { Sidebar } from "@starwind-ui/react/sidebar";

export function Example() {
  return (
    <Sidebar.Provider>
      <Sidebar.Sidebar>
        <Sidebar.MenuButton>Dashboard</Sidebar.MenuButton>
      </Sidebar.Sidebar>
      <Sidebar.Trigger>Toggle sidebar</Sidebar.Trigger>
      <Sidebar.Rail />
    </Sidebar.Provider>
  );
}

Render the Sidebar data-sw-* contract yourself, then initialize createSidebarController.

<div data-sw-sidebar-provider>
  <div data-sw-sidebar>
    <button data-sw-sidebar-menu-button>Dashboard</button>
  </div>
  <button data-sw-sidebar-trigger type="button">Toggle sidebar</button>
  <button data-sw-sidebar-rail type="button" tabindex="-1"></button>
</div>

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

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

API Reference

Provider

Provides shared Sidebar state to nested parts.

Default element: div
Discovery hook: data-sw-sidebar-provider
Role: -

Props

Prop Type Default

open boolean -

Description

Controls whether Sidebar is open.

Kind

control

Targets

provider

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

open
defaultOpen
starwind:sidebar-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

data-default-open
starwind:sidebar-change
setOpen

defaultOpen boolean true

Description

Sets whether Sidebar starts open.

Kind

control

Targets

provider

Full type

boolean

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

open
defaultOpen
starwind:sidebar-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

data-default-open
starwind:sidebar-change
setOpen

mobileOpen boolean -

Description

Controls the mobile open state for Sidebar.

Kind

control

Targets

provider

Full type

boolean

React

Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.

mobileOpen
defaultMobileOpen
onMobileOpenChange

Astro

Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

mobileOpen
defaultMobileOpen
starwind:sidebar-mobile-change
setMobileOpen

Runtime / HTML

Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

data-default-mobile-open
starwind:sidebar-mobile-change
setMobileOpen

defaultMobileOpen boolean false

Description

Controls the default mobile open state for Sidebar.

Kind

control

Targets

provider

Full type

boolean

React

Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.

mobileOpen
defaultMobileOpen
onMobileOpenChange

Astro

Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

mobileOpen
defaultMobileOpen
starwind:sidebar-mobile-change
setMobileOpen

Runtime / HTML

Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

data-default-mobile-open
starwind:sidebar-mobile-change
setMobileOpen

keyboardShortcut string "b"

Description: Configures the keyboard shortcut option for the Provider part.
Kind: option
Targets: provider
Full type: string

mobileQuery string "(max-width: 767.98px)"

Description: Configures the mobile query option for the Provider part.
Kind: option
Targets: provider
Full type: string

persistOpen boolean false

Description: Configures the persist open option for the Provider part.
Kind: option
Targets: provider
Full type: boolean

persistenceKey string "starwind-sidebar-open"

Description: Configures the persistence key option for the Provider part.
Kind: option
Targets: provider
Full type: string

persistenceStorage SidebarPersistenceStorage "localStorage"

Description: Configures the persistence storage option for the Provider part.
Kind: option
Targets: provider
Full type: SidebarPersistenceStorage

persistenceMaxAge number 604800

Description: Configures the persistence max age option for the Provider part.
Kind: option
Targets: provider
Full type: number

onOpenChange (open: boolean, details: SidebarOpenChangeDetails) => void -

Description

Runs when Sidebar opens or closes.

Kind

callback

Targets

provider

Full type

(open: boolean, details: SidebarOpenChangeDetails) => void

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

open
defaultOpen
starwind:sidebar-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

data-default-open
starwind:sidebar-change
setOpen

onMobileOpenChange (open: boolean, details: SidebarMobileOpenChangeDetails) => void -

Description

Runs when on mobile open change changes for Sidebar.

Kind

callback

Targets

provider

Full type

(open: boolean, details: SidebarMobileOpenChangeDetails) => void

React

Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.

mobileOpen
defaultMobileOpen
onMobileOpenChange

Astro

Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

mobileOpen
defaultMobileOpen
starwind:sidebar-mobile-change
setMobileOpen

Runtime / HTML

Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

data-default-mobile-open
starwind:sidebar-mobile-change
setMobileOpen

Events

Event Callback Value

openChange onOpenChange open: boolean

Description: Fires when Sidebar opens or closes.
DOM event: starwind:sidebar-change
Details type: SidebarOpenChangeDetails
Timing: -
Cancelable: No

mobileOpenChange onMobileOpenChange open: boolean

Description: Fires when the mobile panel opens or closes for Sidebar.
DOM event: starwind:sidebar-mobile-change
Details type: SidebarMobileOpenChangeDetails
Timing: -
Cancelable: No

State

State Type Props

open boolean open / defaultOpen

Description

Tracks whether Sidebar is open.

Initial attribute

data-default-open

Runtime getter

getOpen

Runtime setter

setOpen

React

Use open for controlled state and defaultOpen for default state, and onOpenChange for state changes.

open
defaultOpen
onOpenChange

Astro

Use open or defaultOpen for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

open
defaultOpen
starwind:sidebar-change
setOpen

Runtime / HTML

Use data-default-open for initial state, listen for starwind:sidebar-change, and call setOpen for later updates.

data-default-open
starwind:sidebar-change
setOpen

mobileOpen boolean mobileOpen / defaultMobileOpen

Description

Tracks whether the mobile Sidebar panel is open.

Initial attribute

data-default-mobile-open

Runtime getter

getMobileOpen

Runtime setter

setMobileOpen

React

Use mobileOpen for controlled state and defaultMobileOpen for default state, and onMobileOpenChange for state changes.

mobileOpen
defaultMobileOpen
onMobileOpenChange

Astro

Use mobileOpen or defaultMobileOpen for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

mobileOpen
defaultMobileOpen
starwind:sidebar-mobile-change
setMobileOpen

Runtime / HTML

Use data-default-mobile-open for initial state, listen for starwind:sidebar-mobile-change, and call setMobileOpen for later updates.

data-default-mobile-open
starwind:sidebar-mobile-change
setMobileOpen

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-sidebar-provider - Marks the Provider part so Starwind Runtime can find it.

State

Attribute Value Description

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

data-mobile-open - Reflects the mobile open state on the Provider part.

Metadata

Attribute Value Description

data-default-open - Reflects the default open prop on the Provider part.

data-default-mobile-open - Reflects the default mobile open prop on the Provider part.

data-keyboard-shortcut - Reflects the keyboard shortcut prop on the Provider part.

data-mobile-query - Reflects the mobile query prop on the Provider part.

data-persist-open - Reflects the persist open prop on the Provider part.

data-persistence-key - Reflects the persistence key prop on the Provider part.

data-persistence-storage - Reflects the persistence storage prop on the Provider part.

data-persistence-max-age - Reflects the persistence max age prop on the Provider part.

The visible sidebar panel for Sidebar.

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

Props

Prop Type Default

side "left" | "right" "left"

Description: Sets the preferred side for Sidebar content.
Kind: attribute
Targets: sidebar
Full type: "left" | "right"

variant "sidebar" | "floating" | "inset" "sidebar"

Description: Selects the visual variant for the Sidebar part.
Kind: attribute
Targets: sidebar
Full type: "sidebar" | "floating" | "inset"

collapsible "offcanvas" | "icon" "offcanvas"

Description: Allows all Sidebar items to be collapsed.
Kind: attribute
Targets: sidebar
Full type: "offcanvas" | "icon"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-sidebar - Marks the Sidebar part so Starwind Runtime can find it.

State

Attribute Value Description

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

data-collapsible - Reflects the collapsible state on the Sidebar part.

Metadata

Attribute Value Description

data-collapsible-mode - Reflects the collapsible mode prop on the Sidebar part.

data-variant - Reflects the variant prop on the Sidebar part.

data-side - Reflects the side prop on the Sidebar part.

Trigger

The control that opens, closes, or targets the Sidebar content.

Default element: button
Discovery hook: data-sw-sidebar-trigger
Role: -

Props

Prop Type Default

asChild boolean false

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger, menuButton
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-sidebar-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

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

Rail

A compact control for resizing or toggling Sidebar.

Default element: button
Discovery hook: data-sw-sidebar-rail
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-sidebar-rail - Marks the Rail part so Starwind Runtime can find it.

State

Attribute Value Description

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

A menu-style button rendered inside Sidebar.

Default element: button
Discovery hook: data-sw-sidebar-menu-button
Role: -

Props

Prop Type Default

asChild boolean false

Description: Merges behavior onto your child element instead of rendering the default Menu Button element.
Kind: rendering
Targets: trigger, menuButton
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-sidebar-menu-button - Marks the Menu Button part so Starwind Runtime can find it.

State

Attribute Value Description

data-sidebar-state - Reflects the sidebar state on the Menu Button part.

Runtime API

Factory: createSidebarController
Import: @starwind-ui/runtime/sidebar
Root hook: provider data-sw-sidebar-provider
Option props: defaultMobileOpen, defaultOpen, keyboardShortcut, mobileOpen, mobileQuery, onMobileOpenChange, onOpenChange, open, persistOpen, persistenceKey, persistenceMaxAge, persistenceStorage

Option Lifecycles

Option	Lifecycle
defaultMobileOpen	constructor-only
defaultOpen	constructor-only
keyboardShortcut	constructor-only
mobileOpen	setter-backed
mobileQuery	constructor-only
onMobileOpenChange	constructor-only
onOpenChange	constructor-only
open	setter-backed
persistOpen	constructor-only
persistenceKey	constructor-only
persistenceMaxAge	constructor-only
persistenceStorage	constructor-only

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Sidebar from Runtime code.

setMobileOpen state: mobileOpen Opens or closes the mobile Sidebar panel from Runtime code.

Component Relationship

Sidebar Direct primitive

Changelog

View version history v1.0.0 3 releases

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 provider-owned expanded, collapsed, and mobile state with coordinated controls and panels.

Layer Metadata

Sidebar Primitive uses createSidebarController. Styled components: Sidebar.

primitive Sidebar Primitive Sidebar Primitive uses createSidebarController. Styled components: Sidebar. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters sidebar Sidebar Presence Disclosure Control Disclosure primitives that manage open state and mounted content. /docs/primitives/sidebar/ createSidebarController @starwind-ui/runtime/sidebar /docs/runtime/#create-sidebar-controller provider defaultMobileOpen defaultOpen keyboardShortcut mobileOpen mobileQuery onMobileOpenChange onOpenChange open persistOpen persistenceKey persistenceMaxAge persistenceStorage raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Sidebar data-sw-* contract yourself, then initialize createSidebarController. html Use the Astro primitive adapter to render Sidebar anatomy with the Runtime wiring included. Use the React primitive adapter when Sidebar state participates in React rendering. tsx div data-sw-sidebar-provider boolean Controls whether Sidebar is open. Sets whether Sidebar starts open. Controls the mobile open state for Sidebar. Controls the default mobile open state for Sidebar. string Configures the keyboard shortcut option for the Provider part. Configures the mobile query option for the Provider part. Configures the persist open option for the Provider part. Configures the persistence key option for the Provider part. SidebarPersistenceStorage Configures the persistence storage option for the Provider part. number Configures the persistence max age option for the Provider part. (open: boolean, details: SidebarOpenChangeDetails) => void SidebarOpenChangeDetails Runs when Sidebar opens or closes. (open: boolean, details: SidebarMobileOpenChangeDetails) => void SidebarMobileOpenChangeDetails Runs when on mobile open change changes for Sidebar. runtime Marks the Provider part so Starwind Runtime can find it. data-default-open prop Reflects the default open prop on the Provider part. data-default-mobile-open Reflects the default mobile open prop on the Provider part. data-state state Reflects the current state on the Provider part. data-mobile-open Reflects the mobile open state on the Provider part. data-keyboard-shortcut Reflects the keyboard shortcut prop on the Provider part. data-mobile-query Reflects the mobile query prop on the Provider part. data-persist-open Reflects the persist open prop on the Provider part. data-persistence-key Reflects the persistence key prop on the Provider part. data-persistence-storage Reflects the persistence storage prop on the Provider part. data-persistence-max-age Reflects the persistence max age prop on the Provider part. getOpen setOpen getMobileOpen setMobileOpen openChange starwind:sidebar-change mobileOpenChange starwind:sidebar-mobile-change data-sw-sidebar side "left" | "right" Sets the preferred side for Sidebar content. variant "sidebar" | "floating" | "inset" Selects the visual variant for the Sidebar part. collapsible "offcanvas" | "icon" Allows all Sidebar items to be collapsed. Marks the Sidebar part so Starwind Runtime can find it. Reflects the current state on the Sidebar part. data-collapsible Reflects the collapsible state on the Sidebar part. data-collapsible-mode Reflects the collapsible mode prop on the Sidebar part. data-variant Reflects the variant prop on the Sidebar part. data-side Reflects the side prop on the Sidebar part. trigger button data-sw-sidebar-trigger asChild Merges behavior onto your child element instead of rendering the default Trigger element. Marks the Trigger part so Starwind Runtime can find it. Reflects the current state on the Trigger part. rail data-sw-sidebar-rail Marks the Rail part so Starwind Runtime can find it. Reflects the current state on the Rail part. menuButton data-sw-sidebar-menu-button Merges behavior onto your child element instead of rendering the default Menu Button element. Marks the Menu Button part so Starwind Runtime can find it. data-sidebar-state Reflects the sidebar state on the Menu Button part. Provider Trigger type aria-expanded Rail tabindex Menu Button @starwind-ui/astro @starwind-ui/astro/sidebar Render uncontrolled provider markup and let the runtime own desktop/mobile state and persistence. @starwind-ui/react @starwind-ui/react/sidebar Bridge controlled desktop and mobile state through setOpen/setMobileOpen while retaining uncontrolled defaults. /docs/components/sidebar/ Direct primitive direct-primitive Styled component Sidebar

Sidebar Primitive

Anatomy

API Reference

Provider

Props

Events

State

Data Attributes

Runtime hooks

State

Metadata

Sidebar

Props

Data Attributes

Runtime hooks

State

Metadata

Trigger

Props

Data Attributes

Runtime hooks

State

Rail

Data Attributes

Runtime hooks

State

Menu Button

Props

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Runtime Setters

Related Styled Components

Changelog

v1.0.0

v0.1.1

v0.1.0