# Sidebar

A collapsible side panel for navigation and secondary content.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import { Sidebar } from "coss-svelte";
</script>

<Sidebar
	class="h-64 w-56 rounded-lg border border-border"
	items={["Dashboard", "Projects", "Settings"]}
/>

```

## Anatomy

- `Sidebar`
- `SidebarContent`
- `SidebarFooter`
- `SidebarGroup`
- `SidebarGroupAction`
- `SidebarGroupContent`
- `SidebarGroupLabel`
- `SidebarHeader`
- `SidebarInput`
- `SidebarInset`
- `SidebarMenu`
- `SidebarMenuAction`
- `SidebarMenuBadge`
- `SidebarMenuButton`
- `SidebarMenuItem`
- `SidebarMenuSkeleton`
- `SidebarMenuSub`
- `SidebarMenuSubButton`
- `SidebarMenuSubItem`
- `SidebarProvider`
- `SidebarRail`
- `SidebarSeparator`
- `SidebarTrigger`

## API Reference

### Sidebar

A collapsible side panel for navigation and secondary content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `SidebarItem[]` | `[]` | Items rendered by the component's built-in fallback composition. |
| `label` | `string` | `"Sidebar"` | Accessible label or fallback visible label for the control. |
| `side` | `"right" \| "left"` | `"left"` | Side from which the surface appears. |
| `variant` | `"sidebar" \| "floating" \| "inset"` | `"sidebar"` | Visual variant for the component. |
| `collapsible` | `"none" \| "icon" \| "offcanvas"` | `"offcanvas"` | Controls how the sidebar collapses. |
| `state` | `"expanded" \| "collapsed"` | `"expanded"` | Visual state used by the sidebar fallback layout. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <aside> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarContent

Wraps the primary content for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarFooter

Groups footer content and actions for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarGroup

Groups related items inside the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarGroupAction

Renders the primary action for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"submit" \| "reset" \| "button" \| null` | `"button"` | Behavior, selection, or HTML type passed to the underlying control. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarGroupContent

Wraps the primary content for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarGroupLabel

Labels a group of related items.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarHeader

Groups heading content for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarInput

Renders the input field for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <input> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarInset

Wraps page content adjacent to the sidebar.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <main> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenu

Groups sidebar menu items.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <ul> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuAction

Renders the primary action for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"submit" \| "reset" \| "button" \| null` | `"button"` | Behavior, selection, or HTML type passed to the underlying control. |
| `showOnHover` | `boolean` | `false` | Only reveals the menu action when the parent item is hovered or focused. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuBadge

Renders a badge inside a sidebar menu item.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuButton

Renders a button-shaped control for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | `undefined` | Renders the component as a link target when provided. |
| `type` | `"submit" \| "reset" \| "button" \| null` | `"button"` | Behavior, selection, or HTML type passed to the underlying control. |
| `isActive` | `boolean` | `false` | Marks the item as the current or selected navigation target. |
| `size` | `ButtonSize` | `"default"` | Size variant for the component. |
| `variant` | `ButtonVariant` | `"default"` | Visual variant for the component. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <a> / <button> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuItem

Renders one selectable or repeated item.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <li> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuSkeleton

Renders a loading placeholder for sidebar menu content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showIcon` | `boolean` | `false` | Shows the icon placeholder in the sidebar skeleton row. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuSub

Groups nested sidebar menu content.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <ul> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuSubButton

Renders a button-shaped control for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | `"#"` | Renders the component as a link target when provided. |
| `isActive` | `boolean` | `false` | Marks the item as the current or selected navigation target. |
| `size` | `"md" \| "sm" \| "lg"` | `"md"` | Size variant for the component. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <a> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarMenuSubItem

Renders one selectable or repeated item.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <li> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarProvider

Provides shared state and context to child components.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `true` | Initial open state for the sidebar provider. |
| `bind:open` | `boolean` | `defaultOpen` | Open state for the popup or disclosure. Bind with `bind:open`. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarRail

Renders the sidebar resize or collapse rail.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"submit" \| "reset" \| "button" \| null` | `"button"` | Behavior, selection, or HTML type passed to the underlying control. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarSeparator

Visually separates related content.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### SidebarTrigger

Renders the control that opens, closes, or selects related content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"submit" \| "reset" \| "button" \| null` | `"button"` | Behavior, selection, or HTML type passed to the underlying control. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <button> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Experimental |
| Foundation | compound |
| Category | Layout & Navigation |
| Particles | 0 |

## Status

Experimental in 0.1.0: the compound sidebar and controlled collapsed state are available; responsive drawer behavior and persisted layout state are not yet complete.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/sidebar.json` for the complete local file and dependency closure.
- Treat Sidebar as experimental and preserve the limitations described in Status.