On this page

Sidebar Primitive

Sidebar is a Starwind Runtime primitive in the presence-disclosure-control contract family.

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

defaultOpen boolean true

Description: Sets whether Sidebar starts open.
Kind: control
Targets: provider
Full type: boolean

mobileOpen boolean -

Description: Controls the mobile open state for Sidebar.
Kind: control
Targets: provider
Full type: boolean

defaultMobileOpen boolean false

Description: Controls the default mobile open state for Sidebar.
Kind: control
Targets: provider
Full type: boolean

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

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

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

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
State control support: React supports controlled and default state with mobileOpen and defaultMobileOpen props. Runtime/HTML reads initial state from data-default-mobile-open and updates with setMobileOpen. 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-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

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