Sidebar

Collapsible labeled primary navigation shell with configurable chrome, search, groups, workspace switcher, and account menu.

Also known as: app sidebar, navigation sidebar, vertical nav, primary nav, side navigation, nav shell

Installation

Install with the CLI, or copy the component source into your project.

Add sidebar (npm)

1
npx --yes -p github:itsvigneshv/default-file-ui#main df-ui add sidebar

Enterprise shell

Expanded primary IA with workspace switcher, search, section groups, project swatches, and account menu.

Workspace

Collapsed rail

Icon-only density with tooltips. CollapseTrigger restores the labeled shell.

Workspace

Properties

Collapsible labeled primary navigation shell. Compose Header, Search, Content, Nav, Group, Item, Workspace, User, Separator, Shortcut, and CollapseTrigger. Prefer Tool Rail for icon mode switching and Dock Panel for persistent inspectors. Chrome is tokenized via --df-sidebar-* and semantic --sidebar*.

Sidebar

Root landmark. Controllable collapsed width. Pass chrome props or set the matching CSS variables on style. Parts must render inside this root.

Prop	Type	Default	Notes
collapsed	boolean	-	Controlled collapsed state.
defaultCollapsed	boolean	false	Initial collapsed state when uncontrolled.
onCollapsedChange	(collapsed: boolean) => void	-	Called when the collapsed state changes.
side	"left" \| "right"	"left"	Intended edge. Collapsed tooltips open away from the shell (right for left side, left for right side).
width	string	-	Expanded width. Prefer tokens such as var(--df-sidebar-width). Sets --df-sidebar-width.
collapsedWidth	string	-	Collapsed width. Prefer tokens such as var(--df-sidebar-width-collapsed). Sets --df-sidebar-width-collapsed.
radius	"none" \| "xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "full"	"2xl"	Corner radius of the shell. Maps to --df-sidebar-radius.
itemRadius	"none" \| "xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "full"	"lg"	Corner radius for items and triggers. Maps to --df-sidebar-item-radius.
cornerShape	"round" \| "smooth"	-	Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init).
background	string	-	Shell background. Prefer var(--sidebar). Sets --df-sidebar-bg.
borderColor	string	-	Shell border color. Prefer var(--sidebar-border). Sets --df-sidebar-border.
foreground	string	-	Default foreground. Prefer var(--sidebar-foreground). Sets --df-sidebar-fg.
shadow	string	-	Box shadow. Prefer var(--df-shadow-panel). Sets --df-sidebar-shadow.
label	string	"Primary"	Accessible name for the landmark and for collapse controls when aria-label is omitted.
aria-label	string	-	Overrides label on the aside landmark. Collapse controls still use label unless you set their aria-label.
children	ReactNode	-	Compose Header, Search, Content, Footer, CollapseTrigger, and related parts.
className	string	-	Additional classes on the aside root.
…aside attributes	HTMLAttributes	-	Native aside attributes on the root.

SidebarHeader

Top region for workspace switcher, search, and collapse.

Prop	Type	Default	Notes
children	ReactNode	-	Typically SidebarWorkspace, SidebarSearch, and CollapseTrigger.
className	string	-	Additional classes on the header.
…div attributes	HTMLAttributes	-	Native div attributes on the header.

SidebarContent

Scrollable middle region. Wraps children in ScrollArea.

Prop	Type	Default	Notes
children	ReactNode	-	Typically SidebarNav with groups and items.
viewportClassName	string	-	Classes on the ScrollArea viewport.
variant	"default" \| "edge"	-	ScrollArea thumb style.
thumbShape	"rounded" \| "flat"	-	ScrollArea thumb corner shape.
orientation	"vertical" \| "horizontal" \| "both"	"vertical"	ScrollArea axes.
side	"left" \| "right" \| "top" \| "bottom"	-	ScrollArea thumb edge.
visibility	"hover" \| "always"	-	ScrollArea thumb visibility.
space	"auto" \| "none"	-	ScrollArea track inset mode.
width	number	-	ScrollArea scrollbar thickness in pixels.
className	string	-	Additional classes on the content shell.
…div attributes	HTMLAttributes	-	Native div attributes on the content shell.

SidebarFooter

Bottom region for utility items and account menu.

Prop	Type	Default	Notes
children	ReactNode	-	Typically SidebarItem rows, Separator, and SidebarUser.
className	string	-	Additional classes on the footer.
…div attributes	HTMLAttributes	-	Native div attributes on the footer.

SidebarNav

Semantic nav stack for primary destinations and groups.

Prop	Type	Default	Notes
children	ReactNode	-	SidebarItem rows and SidebarGroup sections.
className	string	-	Additional classes on the nav.
…nav attributes	HTMLAttributes	-	Native nav attributes.

SidebarSearch

Expanded mode composes SearchInput. Collapsed mode shows an icon control with a tooltip. onClick runs for both modes so a command palette or focus handoff can share one handler.

Prop	Type	Default	Notes
shortcut	ReactNode	-	Trailing shortcut chip when expanded. Rendered with SidebarShortcut.
collapsedLabel	string	"Search"	Tooltip and aria-label when collapsed.
placeholder	string	"Search"	SearchInput placeholder when expanded.
size	"sm" \| "md" \| "lg"	"sm"	SearchInput size when expanded.
variant	"default" \| "pill"	"pill"	SearchInput variant when expanded.
clearable	boolean	false	Show the clear control when the field has a value.
onClick	MouseEventHandler	-	Click handler for the expanded input and the collapsed icon control.
…SearchInput props	SearchInputProps	-	value, defaultValue, onChange, disabled, and related field props. trailing is owned by shortcut.

SidebarGroup

Section with optional label and action. Header is omitted while the sidebar is collapsed.

Prop	Type	Default	Notes
label	ReactNode	-	Section heading via ListItemLabel nav variant.
action	ReactNode	-	Optional control beside the label, such as an add button.
children	ReactNode	-	SidebarItem rows.
className	string	-	Additional classes on the group.
…div attributes	HTMLAttributes	-	Native div attributes on the group.

SidebarItem

Composes ListItem with muted variant and sm size. Collapsed mode keeps the label for accessibility, hides it visually, and shows a tooltip.

Prop	Type	Default	Notes
icon	ReactNode	-	Leading glyph. Ignored when swatch is set.
swatch	string	-	Leading color swatch. Prefer a kit color token such as var(--df-teal-400).
shortcut	ReactNode	-	Trailing shortcut chip when expanded.
badge	ReactNode	-	Optional badge on the icon, such as a count.
badgeVariant	BadgeVariant	"destructive"	Badge tone.
active	boolean	false	Selected row state. Maps to ListItem selected.
disabled	boolean	false	Disables interaction.
asChild	boolean	false	Merge row props onto a single child element, usually a link.
trailing	ReactNode	-	Extra trailing content before the shortcut.
children	ReactNode	-	Row label. Also used for aria-label and collapsed tooltip text.
className	string	-	Additional classes on the ListItem host.
…div attributes	HTMLAttributes	-	Native attributes forwarded to ListItem.

SidebarShortcut

Trailing keyboard hint chrome. Used by SidebarSearch and SidebarItem; can also be composed manually.

Prop	Type	Default	Notes
children	ReactNode	-	Shortcut text such as Cmd+1.
className	string	-	Additional classes on the shortcut.
…span attributes	HTMLAttributes	-	Native span attributes.

SidebarSeparator

Divider between nav blocks. Composes Separator.

Prop	Type	Default	Notes
orientation	"horizontal" \| "vertical"	"horizontal"	Separator axis.
decorative	boolean	true	When true, omits separator semantics for assistive tech.
className	string	-	Additional classes on the separator.

SidebarWorkspace

Workspace switcher host. Wraps OptionList. Compose SidebarWorkspaceTrigger, SidebarWorkspaceContent, and OptionListItem rows.

Prop	Type	Default	Notes
value	string \| null	-	Controlled selected workspace value.
defaultValue	string \| null	-	Uncontrolled initial workspace value.
onValueChange	(value: string \| null) => void	-	Called when the selected workspace changes.
open	boolean	-	Controlled menu open state.
defaultOpen	boolean	false	Uncontrolled initial open state.
onOpenChange	(open: boolean) => void	-	Called when the menu opens or closes.
width	"hug" \| "fill" \| string	"hug"	OptionList width mode for the trigger and panel.
className	string	-	Additional classes on the workspace host.
children	ReactNode	-	Trigger, content, and option rows.
…OptionList props	OptionListProps	-	selectionMode, closeOnSelect, and related picker props.

SidebarWorkspaceTrigger

Opens the workspace menu. Collapsed mode shows the logo with a tooltip.

Prop	Type	Default	Notes
logo	ReactNode	-	Leading workspace mark.
title	ReactNode	-	Workspace name. Required. Used for aria-label and tooltip text.
description	ReactNode	-	Secondary plan or meta line when expanded.
chevron	ReactNode	-	Trailing chevron. Defaults to ChevronsUpDown.
className	string	-	Additional classes on the trigger button.

SidebarWorkspaceContent

Portaled OptionList panel. Place OptionListItem rows and related OptionList parts inside.

Prop	Type	Default	Notes
side	"top" \| "bottom" \| "left" \| "right"	away from Sidebar side	Preferred panel side. Defaults to right when the shell is left, and left when the shell is right.
align	"start" \| "center" \| "end" \| "auto"	"start"	Panel alignment along the trigger.
sideOffset	number	8	Gap from the trigger in pixels.
portal	boolean	true	Render the panel in a portal.
search	boolean	-	Show the built-in OptionList search field.
children	ReactNode	-	OptionListItem rows and related list parts.
…OptionListContent props	OptionListContentProps	-	alignOffset, dismissOnScroll, scrollable, footer, and related panel props.

SidebarUser

Account menu host. Wraps Popover. Compose SidebarUserTrigger and SidebarUserContent.

Prop	Type	Default	Notes
open	boolean	-	Controlled popover open state.
defaultOpen	boolean	false	Uncontrolled initial open state.
onOpenChange	(open: boolean) => void	-	Called when the popover opens or closes.
className	string	-	Additional classes on the user host.
children	ReactNode	-	Trigger and content.

SidebarUserTrigger

Opens the account menu. Collapsed mode shows the avatar with a tooltip.

Prop	Type	Default	Notes
name	ReactNode	-	Display name. Required. Used for aria-label, tooltip, and Avatar name when string.
email	ReactNode	-	Secondary email line when expanded.
src	string	-	Avatar image URL for the default Avatar.
alt	string	-	Avatar image alt text.
avatar	ReactNode	-	Custom avatar node. Replaces the default Avatar.
chevron	ReactNode	-	Trailing chevron. Defaults to ChevronsUpDown.
className	string	-	Additional classes on the trigger button.

SidebarUserContent

Portaled Popover panel. Compose PopoverHeader, PopoverBody, PopoverFooter, ListItem rows, and related content.

Prop	Type	Default	Notes
side	"top" \| "bottom" \| "left" \| "right"	away from Sidebar side	Preferred panel side. Defaults to right when the shell is left, and left when the shell is right.
align	"start" \| "center" \| "end"	"end"	Panel alignment along the trigger.
sideOffset	number	8	Gap from the trigger in pixels.
children	ReactNode	-	Account menu content.
…PopoverContent props	PopoverContentProps	-	variant, size, radius, portal, and related panel props.

SidebarCollapseTrigger

Toggles collapsed state on the surrounding Sidebar. Renders as a ghost icon-sm Button.

Prop	Type	Default	Notes
icon	ReactNode	-	Optional icon. Defaults to PanelLeft when children are omitted.
children	ReactNode	-	Replaces icon when provided.
aria-label	string	-	Accessible name. Defaults to Expand {label} or Collapse {label}.
title	string	-	Native title. Defaults to the same string as aria-label.
…Button props	Button props	-	Additional button attributes. size and variant default to icon-sm and ghost.

Tokens

Theme defaults live on :root. Override these globally or on a local host.

Token	Type	Default	Notes
--df-sidebar-width	CSS length	calc(68 * var(--spacing-unit))	Expanded shell width.
--df-sidebar-width-collapsed	CSS length	calc(16 * var(--spacing-unit))	Collapsed shell width.
--df-sidebar-bg	CSS color	var(--sidebar)	Shell background.
--df-sidebar-fg	CSS color	var(--sidebar-foreground)	Shell foreground.
--df-sidebar-border	CSS color	var(--sidebar-border)	Shell border.
--df-sidebar-accent	CSS color	var(--sidebar-accent)	Hover and selected fill.
--df-sidebar-accent-fg	CSS color	var(--sidebar-accent-foreground)	Hover and selected foreground.
--df-sidebar-primary	CSS color	var(--sidebar-primary)	Primary accent.
--df-sidebar-primary-fg	CSS color	var(--sidebar-primary-foreground)	Primary accent foreground.
--df-sidebar-ring	CSS color	var(--sidebar-ring)	Focus ring.
--df-sidebar-shadow	CSS box-shadow	var(--df-shadow-panel)	Shell elevation.
--df-sidebar-radius	CSS length	var(--radius-2xl)	Shell radius.
--df-sidebar-item-radius	CSS length	var(--radius-lg)	Item and trigger radius.
--df-sidebar-padding	CSS length	calc(3 * var(--spacing-unit))	Shell padding.
--df-sidebar-gap	CSS length	calc(2 * var(--spacing-unit))	Gap between major regions.
--df-sidebar-section-gap	CSS length	calc(4 * var(--spacing-unit))	Gap between nav sections.
--df-sidebar-item-gap	CSS length	calc(0.5 * var(--spacing-unit))	Gap between rows in a group.
--df-sidebar-swatch-size	CSS length	calc(2.5 * var(--spacing-unit))	Project swatch size.
--df-sidebar-swatch-radius	CSS length	var(--radius-sm)	Project swatch radius.
--df-sidebar-shortcut-fg	CSS color	var(--muted-foreground)	Shortcut chip color.
--df-sidebar-group-label-fg	CSS color	var(--muted-foreground)	Group action and label quiet color.
--df-corner-shape	CSS corner-shape	var(--df-corner-shape-round)	Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round.

Installation

Enterprise shell

Collapsed rail

Properties

Sidebar

SidebarHeader

SidebarContent

SidebarFooter

SidebarNav

SidebarSearch

SidebarGroup

SidebarItem

SidebarShortcut

SidebarSeparator

SidebarWorkspace

SidebarWorkspaceTrigger

SidebarWorkspaceContent

SidebarUser

SidebarUserTrigger

SidebarUserContent

SidebarCollapseTrigger

Tokens

Related