}
data-slot="sidebar-menu"
gap={1}
xstyle={[styles.menu, xstyle]}
className={className}
{...props}
/>
)
}
function SidebarMenuItem({
render,
ref,
style,
xstyle,
className,
...props
}: useRender.ComponentProps<"li"> & Overrides) {
const [size, setSize] = useState("default")
const [hasAction, setHasAction] = useState(false)
const value = useMemo(() => ({ size, setSize, hasAction, setHasAction }), [size, hasAction])
const sx = stylex.props(styles.menuItem, sidebarMenuItem, xstyle)
return (
{useRender({
defaultTagName: "li",
render,
ref,
props: {
"data-slot": "sidebar-menu-item",
...sx,
...props,
className: clsx(sx.className, className),
style: { ...sx.style, ...style },
},
})}
)
}
type SidebarMenuButtonProps = useRender.ComponentProps<"button", { active: boolean }> & {
isActive?: boolean
variant?: SidebarMenuButtonVariant
size?: SidebarMenuButtonSize
tooltip?: string | ComponentProps
xstyle?: StyleXStyles
}
function SidebarMenuButton({
render,
isActive = false,
variant = "default",
size = "default",
tooltip,
xstyle,
className,
...props
}: SidebarMenuButtonProps) {
const { isMobile, state } = useSidebar()
const { iconMode } = use(SidebarPanelContext)
const item = use(SidebarMenuItemContext)
useLayoutEffect(() => {
item?.setSize(size)
}, [item, size])
const sx = stylex.props(
styles.menuButton,
states.rowFocusRing,
menuButtonVariants[variant] ?? menuButtonVariants.default,
menuButtonSizes[size] ?? menuButtonSizes.default,
isActive && styles.rowActive,
isActive && styles.rowActiveLabel,
item?.hasAction && !iconMode && styles.menuButtonWithAction,
iconMode && styles.menuButtonIcon,
iconMode && size === "lg" && styles.menuButtonIconLg,
xstyle,
)
const button = useRender({
defaultTagName: "button",
render: tooltip ? (
render(props, { active: isActive }) : render
}
/>
) : (
render
),
state: { active: isActive },
stateAttributesMapping: { active: (active) => (active ? { "data-active": "true" } : null) },
props: {
type: render ? undefined : "button",
"data-slot": "sidebar-menu-button",
"data-sidebar": "menu-button",
"data-variant": variant,
"data-size": size,
...sx,
...props,
className: clsx("carbon-icons", sx.className, className),
},
})
if (!tooltip) return button
const content = typeof tooltip === "string" ? { children: tooltip } : tooltip
return (
{button}
{state === "collapsed" && !isMobile && (
)}
)
}
type SidebarMenuActionProps = useRender.ComponentProps<"button"> & {
showOnHover?: boolean
xstyle?: StyleXStyles
}
function SidebarMenuAction({
xstyle,
className,
render,
showOnHover = false,
...props
}: SidebarMenuActionProps) {
const { iconMode } = use(SidebarPanelContext)
const item = use(SidebarMenuItemContext)
useLayoutEffect(() => {
if (!item) return
item.setHasAction(true)
return () => item.setHasAction(false)
}, [item])
const sx = stylex.props(
styles.menuAction,
states.rowFocusRing,
menuActionTop[item?.size ?? "default"],
showOnHover && styles.menuActionShowOnHover,
iconMode && styles.hidden,
xstyle,
)
return useRender({
defaultTagName: "button",
render,
props: {
type: render ? undefined : "button",
"data-slot": "sidebar-menu-action",
"data-sidebar": "menu-action",
...sx,
...props,
className: clsx("carbon-icons", sx.className, className),
},
})
}
function SidebarMenuBadge({
render,
ref,
style,
xstyle,
className,
...props
}: useRender.ComponentProps<"div"> & Overrides) {
const { iconMode } = use(SidebarPanelContext)
const item = use(SidebarMenuItemContext)
const sx = stylex.props(
styles.menuBadge,
menuActionTop[item?.size ?? "default"],
iconMode && styles.hidden,
xstyle,
)
return useRender({
defaultTagName: "div",
render,
ref,
props: {
"data-slot": "sidebar-menu-badge",
...sx,
...props,
className: clsx(sx.className, className),
style: { ...sx.style, ...style },
},
})
}
type SidebarMenuSkeletonProps = useRender.ComponentProps<"div"> & Overrides & { showIcon?: boolean }
function SidebarMenuSkeleton({
render,
ref,
style,
xstyle,
className,
showIcon = false,
...props
}: SidebarMenuSkeletonProps) {
const id = useId()
let hash = 0
for (const char of id) hash = (hash * 31 + char.charCodeAt(0)) % 41
const width = `${50 + hash}%`
const sx = stylex.props(styles.menuSkeleton, xstyle)
return useRender({
defaultTagName: "div",
render,
ref,
props: {
"data-slot": "sidebar-menu-skeleton",
...sx,
...props,
className: clsx(sx.className, className),
style: { ...sx.style, ...style },
children: (
<>
{showIcon && (
)}
),
},
})
}
function SidebarMenuSub({
render,
ref,
style,
xstyle,
className,
...props
}: useRender.ComponentProps<"ul"> & Overrides) {
const { iconMode } = use(SidebarPanelContext)
const sx = stylex.props(styles.menuSub, iconMode && styles.hidden, xstyle)
return useRender({
defaultTagName: "ul",
render,
ref,
props: {
"data-slot": "sidebar-menu-sub",
...sx,
...props,
className: clsx(sx.className, className),
style: { ...sx.style, ...style },
},
})
}
function SidebarMenuSubItem({
render,
ref,
style,
xstyle,
className,
...props
}: useRender.ComponentProps<"li"> & Overrides) {
const sx = stylex.props(styles.menuSubItem, xstyle)
return useRender({
defaultTagName: "li",
render,
ref,
props: {
"data-slot": "sidebar-menu-sub-item",
...sx,
...props,
className: clsx(sx.className, className),
style: { ...sx.style, ...style },
},
})
}
type SidebarMenuSubButtonProps = useRender.ComponentProps<"a", { active: boolean }> & {
size?: SidebarMenuSubButtonSize
isActive?: boolean
xstyle?: StyleXStyles
}
function SidebarMenuSubButton({
render,
size = "md",
isActive = false,
xstyle,
className,
...props
}: SidebarMenuSubButtonProps) {
const { iconMode } = use(SidebarPanelContext)
const sx = stylex.props(
styles.menuSubButton,
states.rowFocusRing,
menuSubButtonSizes[size] ?? menuSubButtonSizes.md,
isActive && styles.rowActive,
iconMode && styles.hidden,
xstyle,
)
return useRender({
defaultTagName: "a",
render,
state: { active: isActive },
stateAttributesMapping: { active: (active) => (active ? { "data-active": "true" } : null) },
props: {
"data-slot": "sidebar-menu-sub-button",
"data-size": size,
...sx,
...props,
className: clsx("carbon-icons", sx.className, className),
},
})
}
export {
Sidebar,
SidebarContent,
SidebarFooter,
SidebarGroup,
SidebarGroupAction,
SidebarGroupContent,
SidebarGroupLabel,
SidebarHeader,
SidebarInput,
SidebarInset,
SidebarMenu,
SidebarMenuAction,
SidebarMenuBadge,
SidebarMenuButton,
SidebarMenuItem,
SidebarMenuSkeleton,
SidebarMenuSub,
SidebarMenuSubButton,
SidebarMenuSubItem,
SidebarProvider,
SidebarRail,
SidebarSeparator,
SidebarTrigger,
sidebarStyles,
useSidebar,
type SidebarCollapsible,
type SidebarMenuButtonSize,
type SidebarMenuButtonVariant,
type SidebarMenuSubButtonSize,
type SidebarSide,
type SidebarVariant,
}
```
4. Update the import paths to match your project setup.
## Usage
```tsx title="app/layout.tsx"
import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar"
import { AppSidebar } from "@/components/app-sidebar"
export default function Layout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
```tsx title="components/app-sidebar.tsx"
import {
Sidebar,
SidebarContent,
SidebarFooter,
SidebarGroup,
SidebarHeader,
} from "@/components/ui/sidebar"
export function AppSidebar() {
return (
)
}
```
## Composition
```text
SidebarProvider
├── Sidebar
│ ├── SidebarHeader
│ ├── SidebarContent
│ │ ├── SidebarGroup
│ │ │ ├── SidebarGroupLabel
│ │ │ ├── SidebarGroupAction
│ │ │ ├── SidebarGroupContent
│ │ │ └── SidebarMenu
│ │ │ ├── SidebarMenuItem
│ │ │ │ ├── SidebarMenuButton
│ │ │ │ ├── SidebarMenuAction
│ │ │ │ └── SidebarMenuBadge
│ │ │ └── SidebarMenuItem
│ │ │ ├── SidebarMenuButton
│ │ │ └── SidebarMenuSub
│ │ │ ├── SidebarMenuSubItem
│ │ │ └── SidebarMenuSubItem
│ │ └── SidebarGroup
│ │ └── SidebarMenu
│ │ ├── SidebarMenuItem
│ │ └── SidebarMenuItem
│ ├── SidebarFooter
│ └── SidebarRail
├── SidebarInset
└── SidebarTrigger
```
Above `48rem` the `Sidebar` is a fixed column beside an in-flow spacer that
animates its width to push the page over. Below it, the same children render inside a
[Sheet](https://carbon.style/docs/components/sheet) on the same side.
The `variant` prop is on `SidebarProvider`, not on `Sidebar` as in shadcn. The
`inset` variant styles the wrapper and the `SidebarInset` beside the sidebar as
well, and neither can see a sibling's prop.
There is no RTL section. carbon does not support RTL yet, so the offcanvas
offset and the rail use LTR physical properties.
## Structure
- **SidebarProvider** handles collapsible state and provides sidebar context to
child components.
- **Sidebar** is the main collapsible sidebar panel.
- **SidebarHeader** is sticky at the top. Use it for branding, titles, or
workspace switchers.
- **SidebarFooter** is sticky at the bottom. Use it for user menus, settings,
or actions.
- **SidebarContent** is the scrollable region between the header and footer.
- **SidebarGroup** groups related navigation with optional label, action, and
content areas.
- **SidebarMenu** and **SidebarMenuItem** hold links, badges, actions, and
nested submenus.
- **SidebarRail** is a strip along the sidebar's edge that toggles it.
- **SidebarInset** wraps the main content when using the `inset` variant.
- **SidebarTrigger** toggles the sidebar open or collapsed.
## SidebarProvider
Wrap the layout in a `SidebarProvider`. It holds the open state for the desktop
panel and the mobile sheet, persists the desktop one in a `carbon-sidebar`
cookie, and binds ⌘B on Mac and Ctrl+B on Windows.
| Prop | Type | Default |
| -------------- | ------------------------------------ | ----------- |
| `defaultOpen` | `boolean` | `true` |
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `variant` | `"sidebar" \| "floating" \| "inset"` | `"sidebar"` |
### Width
The panel is `16rem` wide, `3rem` as an icon rail and `18rem` as a sheet. The
first two are custom properties on the wrapper. Set them with `style` on the
provider; they are plain custom properties, so every part inside reads them.
```tsx
const wide = { "--carbon-sidebar-width": "20rem", "--carbon-sidebar-width-icon": "4rem" }
```
### Keyboard shortcut
`SIDEBAR_KEYBOARD_SHORTCUT` in `sidebar.tsx` is the key that toggles the sidebar
with ⌘ or Ctrl held.
```tsx title="components/ui/sidebar.tsx"
const SIDEBAR_KEYBOARD_SHORTCUT = "b"
```
## Sidebar
`Sidebar` renders the collapsible panel.
| Prop | Type | Default |
| ------------- | --------------------------------- | ------------- |
| `side` | `"left" \| "right"` | `"left"` |
| `collapsible` | `"offcanvas" \| "icon" \| "none"` | `"offcanvas"` |
| `collapsible` | Description |
| ------------- | ------------------------------------------------------------ |
| `offcanvas` | A collapsible sidebar that slides in from the left or right. |
| `icon` | A sidebar that collapses to icons. |
| `none` | A non-collapsible sidebar. |
> **Note**
>
> With `variant="inset"` on the provider, wrap the main content in a
> `SidebarInset`. It draws the panel the page is raised in, out of the tray the
> sidebar sits on, and moves over when the sidebar collapses.
```tsx
{children}
```
## useSidebar
Use the `useSidebar` hook to control the sidebar.
```tsx
import { useSidebar } from "@/components/ui/sidebar"
export function AppSidebar() {
const { state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar } = useSidebar()
}
```
| Property | Type | Description |
| --------------- | --------------------------- | --------------------------------------------- |
| `state` | `"expanded" \| "collapsed"` | The current state of the sidebar. |
| `open` | `boolean` | Whether the sidebar is open. |
| `setOpen` | `(open: boolean) => void` | Sets the open state of the sidebar. |
| `openMobile` | `boolean` | Whether the sidebar is open on mobile. |
| `setOpenMobile` | `(open: boolean) => void` | Sets the open state of the sidebar on mobile. |
| `isMobile` | `boolean` | Whether the sidebar is on mobile. |
| `toggleSidebar` | `() => void` | Toggles the sidebar on desktop and mobile. |
## SidebarHeader
Use the `SidebarHeader` component to add a sticky header to the sidebar.
```tsx title="components/app-sidebar.tsx"
}>
Select Workspace
Acme Inc
```
A menu button that is an open menu's trigger keeps its hover fill while the
menu is open. The `aria-expanded` rule in `interop.css` does this.
## SidebarFooter
Use the `SidebarFooter` component to add a sticky footer to the sidebar.
```tsx
Username
```
## SidebarContent
`SidebarContent` wraps the content of the sidebar and scrolls. Put your
`SidebarGroup` components in it.
```tsx
```
## SidebarGroup
Use the `SidebarGroup` component to create a section within the sidebar.
A `SidebarGroup` has a `SidebarGroupLabel`, a `SidebarGroupContent` and an
optional `SidebarGroupAction`. Give the action an `aria-label`. It is an
icon-only button, so there is no text for a screen reader to announce.
```tsx
Application
```
To make a `SidebarGroup` collapsible, wrap it in a `Collapsible` and render the
label as the trigger. `collapsibleStyles.chevron` turns the chevron with the
panel.
```tsx
}>
Help
```
## SidebarMenu
Use `SidebarMenu` to build a menu within a `SidebarGroup`.
```tsx
{projects.map((project) => (
}>
{project.name}
))}
```
## SidebarMenuButton
`SidebarMenuButton` renders a menu button within a `SidebarMenuItem`.
It renders a button by default. Use the `render` prop to render a different
component, such as a `Link` or an `a` tag.
Use the `isActive` prop to mark a menu item as active.
```tsx
} isActive>
Home
```
Put a label that can outgrow the row in a `span` with `sidebarStyles.truncate`.
StyleX has no `[&>span:last-child]`, so the row cannot select the label. The
label takes the truncation style itself.
Pass `tooltip` to label the row while the sidebar is collapsed to icons. A string
is the label; an object is `TooltipContent`'s props. The tooltip renders only in
that state.
```tsx
Playground
```
## SidebarMenuAction
`SidebarMenuAction` renders a menu action within a `SidebarMenuItem`. Give it
an `aria-label`.
```tsx
}>
Home
```
Pass `showOnHover` to hide the action until the row is hovered or holds focus.
Below `48rem` it always shows; there is no pointer to hover with.
> **Note**
>
> The action registers with its `SidebarMenuItem` after mount, and the button
> then pads its end so a long label truncates before the icon. Prerendered HTML
> ships without that padding, so a label that reaches the action moves by `2rem`
> on hydration.
## SidebarMenuSub
`SidebarMenuSub` renders a submenu within a `SidebarMenu`.
```tsx
```
## SidebarMenuBadge
`SidebarMenuBadge` renders a badge within a `SidebarMenuItem`.
```tsx
24
```
## SidebarMenuSkeleton
`SidebarMenuSkeleton` renders a skeleton for a `SidebarMenu`. The text bar is between 50% and 90% wide, chosen from the
element's id so the server and the client agree.
```tsx
{Array.from({ length: 5 }).map((_, index) => (
))}
```
## SidebarTrigger
Use the `SidebarTrigger` component to render a button that toggles the sidebar.
It is a ghost `icon-sm` [Button](https://carbon.style/docs/components/button) and takes every prop
one does.
```tsx
import { useSidebar } from "@/components/ui/sidebar"
export function CustomTrigger() {
const { toggleSidebar } = useSidebar()
return
}
```
## SidebarRail
`SidebarRail` renders a rail within a `Sidebar` that toggles the sidebar. It is
out of the tab order, so keyboard users toggle the sidebar with the trigger.
```tsx
```
## Controlled sidebar
Use the `open` and `onOpenChange` props to control the sidebar.
```tsx
export function AppSidebar() {
const [open, setOpen] = useState(false)
return (
)
}
```
## Theming
The sidebar reads its own tokens, so it can differ from the page around it.
They are in `tokens.stylex.ts` beside the rest.
```ts title="theme/tokens.stylex.ts"
sidebar: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",
sidebarForeground: "light-dark(oklch(0.145 0 0), oklch(0.985 0 0))",
sidebarPrimary: "light-dark(oklch(0.205 0 0), oklch(0.922 0 0))",
sidebarPrimaryForeground: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",
sidebarAccent: "light-dark(oklch(0.95 0 0), oklch(0.269 0 0))",
sidebarAccentForeground: "light-dark(oklch(0.205 0 0), oklch(0.985 0 0))",
sidebarBorder: "light-dark(oklch(0.922 0 0), oklch(1 0 0 / 10%))",
```
## Styling
Every part takes `xstyle`. A part that changes with the sidebar's state reads
that state from context, so there is no `group-data-[collapsible=icon]` to key
on. Read `useSidebar` and pass a conditional style instead.
```tsx
const { state } = useSidebar()
```
## API reference
Pass `render` to replace a part's element or compose it with another component.
Every part renders a plain element, or Base UI's `useRender` where it takes
`render`. Each part also takes `xstyle` and `className`.
### SidebarProvider
| Prop | Type | Default |
| -------------- | ------------------------------------ | ----------- |
| `defaultOpen` | `boolean` | `true` |
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `variant` | `"sidebar" \| "floating" \| "inset"` | `"sidebar"` |
### Sidebar
| Prop | Type | Default |
| ------------- | --------------------------------- | ------------- |
| `side` | `"left" \| "right"` | `"left"` |
| `collapsible` | `"offcanvas" \| "icon" \| "none"` | `"offcanvas"` |
### SidebarMenuButton
| Prop | Type | Default |
| ---------- | ------------------------------------------------ | ----------- |
| `render` | `ReactElement \| (props, state) => ReactElement` | — |
| `isActive` | `boolean` | `false` |
| `variant` | `"default" \| "outline"` | `"default"` |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` |
| `tooltip` | `string \| TooltipContentProps` | — |
### SidebarMenuAction
| Prop | Type | Default |
| ------------- | ------------------------------------------------ | ------- |
| `render` | `ReactElement \| (props, state) => ReactElement` | — |
| `showOnHover` | `boolean` | `false` |
### SidebarMenuSubButton
| Prop | Type | Default |
| ---------- | ------------------------------------------------ | ------- |
| `render` | `ReactElement \| (props, state) => ReactElement` | — |
| `isActive` | `boolean` | `false` |
| `size` | `"sm" \| "md"` | `"md"` |
### SidebarMenuSkeleton
| Prop | Type | Default |
| ---------- | --------- | ------- |
| `showIcon` | `boolean` | `false` |
### sidebarStyles
The style maps behind the menu buttons, exported so the same row can be put on
another element.
| Key | Description |
| -------------------- | ----------------------------------------------- |
| `menuButton` | The row: box, hover fill, focus ring, icon size |
| `menuButtonVariants` | One style per `variant` |
| `menuButtonSizes` | One style per `size`, with the height and type |
| `menuSubButton` | The nested row, one step shorter |
| `truncate` | Ellipsis for the label `span` in a row |
### Data attributes
| Attribute | On | Effect |
| ------------------------------------------------------------ | ----------------------- | ------------------------------------------------------------- |
| `data-slot="sidebar-wrapper"` | the provider's `div` | |
| `data-variant` | wrapper, sidebar | Mirrors the provider's `variant` |
| `data-slot="sidebar"` | the sidebar root | Absent below `48rem`, where the sheet renders |
| `data-state` | the sidebar root | `"expanded"` or `"collapsed"` |
| `data-collapsible` | the sidebar root | The `collapsible` prop while collapsed, `""` while open |
| `data-side` | root, container | Mirrors `side` |
| `data-slot="sidebar-gap"` | the in-flow spacer | Animates its width with the panel |
| `data-slot="sidebar-container"` | the fixed panel | Where `xstyle` and `className` land |
| `data-slot="sidebar-inner"` | the panel's surface | Fill, and the floating variant's raised shadow |
| `data-sidebar="sidebar"`, `data-mobile` | the sheet popup | Written beside the sheet's own `data-slot` |
| `data-slot="sidebar-trigger"` | the trigger | |
| `data-slot="sidebar-rail"` | the rail | |
| `data-slot="sidebar-inset"` | the `main` | |
| `data-slot="sidebar-header"`, `-footer`, `-content` | each region | |
| `data-slot="sidebar-group"`, `-label`, `-action`, `-content` | each group part | |
| `data-slot="sidebar-menu"`, `-item`, `-sub`, `-sub-item` | each list part | |
| `data-slot="sidebar-menu-button"` | a row | Replaced by the trigger's slot when rendered through `render` |
| `data-sidebar="menu-button"` | a row | Where `interop.css` keys the open-menu fill |
| `data-variant`, `data-size`, `data-active` | a row, a nested row | Mirror the props; `data-active` is present only when true |
| `data-slot="sidebar-menu-action"` | an action | Replaced by the trigger's slot when rendered through `render` |
| `data-sidebar="menu-action"` | an action | Where `interop.css` keys the open-menu opacity |
| `data-slot="sidebar-menu-badge"` | a badge | |
| `data-slot="sidebar-menu-skeleton"`, `-icon`, `-text` | the skeleton parts | |
| `aria-haspopup`, `aria-expanded` | a row that opens a menu | Base UI writes them |