# Sidebar
A collapsible sidebar layout with a header, body and footer.
```twig
```
## Installation
```shell
php bin/console ux:install sidebar --kit shadcn
```
## Usage
Wrap your layout in a `Sidebar:Provider`, place the `Sidebar` itself next to a `Sidebar:Inset` holding the page content, and add a `Sidebar:Trigger` wherever you want to toggle it.
```twig
```
### Using the sidebar as a page layout
`Sidebar:Inset` wraps the page content, so you will typically want it in your base layout. Blocks defined inside a component tag belong to that component (and `content` is already the name of its default block), so a child template cannot override them through `{% extends %}`. Wrap the sidebar in a small layout component instead: capture its `content` block in a variable, render it inside `Sidebar:Inset`, and let your pages fill it:
```twig
{# templates/components/AppLayout.html.twig #}
{% set page_content %}{% block content %}{% endblock %}{% endset %}
{# ... #}
{{ page_content|raw }}
```
```twig
{# templates/dashboard.html.twig #}
{% extends 'base.html.twig' %}
{% block body %}
Dashboard
{% endblock %}
```
## Examples
### Menu badges and actions
Use `Sidebar:MenuBadge` for counters and `Sidebar:MenuAction` for a secondary action on a menu item; render menu items as links with `as="a"` on `Sidebar:MenuButton`.
```twig
```
### Off-canvas collapsing
Use `collapsible="offcanvas"` to fully hide the sidebar when collapsed. The `Sidebar:Trigger` automatically targets the surrounding `Sidebar:Provider`.
```twig
```
## API Reference
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `side` | `'left'\|'right'` | `'left'` | On which side of the page the sidebar sits. |
| `variant` | `'sidebar'\|'floating'\|'inset'` | `'sidebar'` | The visual variant. |
| `collapsible` | `'icon'\|'offcanvas'\|'none'` | `'icon'` | How the desktop sidebar collapses. |
| `label` | `string` | `'Sidebar'` | Accessible name for the sidebar landmark. |
| Block | Description |
|:------|:------------|
| `content` | Typically a `Sidebar:Header`, `Sidebar:Content`, `Sidebar:Footer` and an optional `Sidebar:Rail`. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The scrollable sidebar body, typically one or more `Sidebar:Group`. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The sidebar footer content. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The group content, typically a `Sidebar:GroupLabel` and a `Sidebar:GroupContent`. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The action's icon or label. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The group body, typically a `Sidebar:Menu`. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The group label text. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The sidebar header content. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The page content placed next to the sidebar (typically a header with a `Sidebar:Trigger`, then the page body). |
### ``
| Block | Description |
|:------|:------------|
| `content` | One or more `Sidebar:MenuItem`. |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `showOnHover` | `boolean` | `false` | Show only when the parent `Sidebar:MenuItem` is hovered or focused. |
| Block | Description |
|:------|:------------|
| `content` | The action's icon or label. |
### ``
| Block | Description |
|:------|:------------|
| `content` | The badge content (typically a count or short label). |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `as` | `'button'\|'a'` | `'button'` | The HTML tag to render; use `a` when the menu item is a link. |
| `active` | `boolean` | `false` | Whether this button represents the active route. |
| `size` | `'default'\|'sm'\|'lg'` | `'default'` | The visual size. |
| `variant` | `'default'\|'outline'` | `'default'` | The visual style variant. |
| `tooltip` | `string` | `null` | Optional title shown when the sidebar is collapsed to icons. |
| Block | Description |
|:------|:------------|
| `content` | The label and/or icon. |
### ``
| Block | Description |
|:------|:------------|
| `content` | A `Sidebar:MenuButton` and optionally a `Sidebar:MenuAction`, `Sidebar:MenuBadge` or `Sidebar:MenuSub`. |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `showIcon` | `boolean` | `false` | Whether to render a placeholder icon next to the label. |
### ``
| Block | Description |
|:------|:------------|
| `content` | One or more `Sidebar:MenuSubItem`. |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `as` | `'a'\|'button'` | `'a'` | The HTML tag to render. |
| `active` | `boolean` | `false` | Whether this sub menu button represents the active route. |
| `size` | `'sm'\|'md'` | `'md'` | The visual size. |
| Block | Description |
|:------|:------------|
| `content` | The label and/or icon. |
### ``
| Block | Description |
|:------|:------------|
| `content` | A `Sidebar:MenuSubButton`. |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `id` | `string` | `null` | Unique id used to wire `Sidebar:Trigger` and `Sidebar:Rail` to the right provider. Auto-generated when omitted. |
| `defaultOpen` | `boolean` | `true` | Initial open state when no cookie is present. |
| `cookieName` | `string` | `'sidebar:state'` | Cookie used to persist the sidebar state across reloads (empty disables persistence). |
| `cookieMaxAge` | `int` | `604800` | Cookie max-age, in seconds. |
| `mobileBreakpoint` | `int` | `768` | Pixel width below which the sidebar behaves as an off-canvas sheet. |
| `keyboardShortcut` | `string` | `'b'` | Single key combined with Ctrl/Cmd that toggles the sidebar; empty disables the shortcut. |
| Block | Description |
|:------|:------------|
| `content` | Typically a `Sidebar` and a `Sidebar:Inset` (with one or more `Sidebar:Trigger` inside). |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `label` | `string` | `'Toggle Sidebar'` | Accessible label announced for the rail toggle. |
| Block | Description |
|:------|:------------|
| `content` | Optional custom content for the rail; empty by default. |
### ``
| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `for` | `string` | `null` | Id of the `Sidebar:Provider` to control. Defaults to the id of the surrounding provider. |
| `label` | `string` | `'Toggle Sidebar'` | Accessible label announced for the trigger. |
| Block | Description |
|:------|:------------|
| `content` | The trigger's icon (typically a `lucide:panel-left`). |
### `data-controller="sidebar"`
| Value | Type | Default | Description |
|:------|:-----|:--------|:------------|
| `data-sidebar-default-open-value` | `Boolean` | `true` | Initial open state when no cookie is present. |
| `data-sidebar-cookie-name-value` | `String` | `'sidebar:state'` | Cookie used to persist the sidebar state across reloads (empty disables persistence). |
| `data-sidebar-cookie-max-age-value` | `Number` | `60 * 60 * 24 * 7` | Cookie max-age, in seconds. |
| `data-sidebar-mobile-breakpoint-value` | `Number` | `768` | Pixel width below which the sidebar behaves as an off-canvas sheet. |
| `data-sidebar-keyboard-shortcut-value` | `String` | `'b'` | Single key combined with Ctrl/Cmd that toggles the sidebar (empty disables the shortcut). |
| Action | Description |
|:-------|:------------|
| `toggle` | Toggle the sidebar between expanded and collapsed (or open/close the mobile sheet). |
| `open` | Expand the sidebar (or open the mobile sheet). |
| `close` | Collapse the sidebar (or close the mobile sheet). |
| `handleKeydown` | Toggle the sidebar on the keyboard shortcut. |