Sidebar

RefineUI

Product

󰕋Overview󰵫Components󰄸Tokens

Account

󰁱Settings

󰉗Pelagornis

󱑎

OverviewMain

SidebarTrigger is the button that opens and closes the sidebar. Put it anywhere inside SidebarProvider — this page places it at the start of the content. Closing removes the sidebar. Hover the edge to peek it, or press the trigger to open it again.

Contract

Overview

Machine-readable contract from Component Spec.

component: sidebarexport: Sidebarversion: 1attributes: data-refineui=sidebar

Anatomy

Part	data-refineui
root	sidebar
brand	sidebar-brand
content	sidebar-content
footer	sidebar-footer
group	sidebar-group
group_label	sidebar-group-label
header	sidebar-header
link	sidebar-link
nav	sidebar-nav
peek	sidebar-peek
peek_edge	sidebar-peek-edge
peek_inset	sidebar-peek-inset
peek_panel	sidebar-peek-panel
peek_pin	sidebar-peek-pin
peek_surface	sidebar-peek-surface
provider	sidebar-provider
trigger	button

States

Scope	Category	Values
component	pseudo	focus-visible
component	environment	forced-colors, dir

Focus

Section	Property	Value
visual	required	true
visual	selector	:focus-visible

Layout

Property	Value
direction	logical
rtl	true

Installation

npmyarnpnpmbun

npm install @refineui/react @refineui/tokens

Usage

import {
  Sidebar,
  SidebarHeader,
  SidebarBrand,
  SidebarContent,
  SidebarNav,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarLink,
  SidebarFooter
} from "@refineui/react";

<Sidebar>
  <SidebarHeader>
    <SidebarBrand>
      <Logo />
      My App
    </SidebarBrand>
  </SidebarHeader>
  <SidebarContent>
    <SidebarNav>
      <SidebarGroup>
        <SidebarGroupLabel>Main</SidebarGroupLabel>
        <SidebarLink href="/" active>Dashboard</SidebarLink>
        <SidebarLink href="/projects">Projects</SidebarLink>
        <SidebarLink href="/tasks">Tasks</SidebarLink>
      </SidebarGroup>
      <SidebarGroup>
        <SidebarGroupLabel>Settings</SidebarGroupLabel>
        <SidebarLink href="/settings">Preferences</SidebarLink>
        <SidebarLink href="/profile">Profile</SidebarLink>
      </SidebarGroup>
    </SidebarNav>
  </SidebarContent>
  <SidebarFooter>
    <p>© 2024</p>
  </SidebarFooter>
</Sidebar>

API Reference

Sidebar

Root sidebar container (<aside> element).

SidebarHeader

Header section.

SidebarBrand

Brand/logo area.

SidebarContent

Main content area. Scrolls through a built-in ScrollArea — overlay scrollbar on hover, and links and group labels take the edge blur. Do not wrap it in another ScrollArea; content in SidebarFooter stays outside the scroll.

SidebarNav

Navigation container (<nav> element).

SidebarGroup

Groups related links.

SidebarGroupLabel

Label for a group.

SidebarLink

Prop	Default	Type	Description
active	false	boolean	Marks the current page (`aria-current="page"`).

SidebarFooter

Footer section.

SidebarProvider

Owns whether the sidebar is expanded. Wrap both the docked Sidebar and the trigger so the trigger can sit outside the sidebar.

Prop	Default	Type	Description
open	—	boolean	Expanded state. Omit to let the provider own it.
defaultOpen	true	boolean	Initial expanded state when `open` is omitted.
onOpenChange	—	(open: boolean) => void	Called when the trigger toggles.
id	—	string	Id of the docked sidebar. The trigger sets `aria-controls` to this id.

SidebarTrigger

Button that toggles the provider. Where you render it is the position. Default variant is secondary.

<SidebarProvider id="app-sidebar" open={open} onOpenChange={setOpen}>
  <SidebarTrigger layout="icon" size="sm" aria-label={open ? "Close sidebar" : "Open sidebar"}>
    <PanelIcon />
  </SidebarTrigger>
  <Sidebar id="app-sidebar">{/* nav */}</Sidebar>
</SidebarProvider>

Sidebar peek (collapsed hover)

Composable flyout when the docked sidebar is collapsed — edge hover reveals a floating panel over the main area (content does not reflow).

<SidebarPeek enabled={collapsed} widthPercent={28} mode="contained" onPin={expand}>
  <SidebarPeekEdge />
  <SidebarPeekPanel>
    <SidebarPeekPin>{/* pin control */}</SidebarPeekPin>
    <Sidebar>...</Sidebar>
  </SidebarPeekPanel>
  <SidebarPeekInset>{/* main + toggle */}</SidebarPeekInset>
</SidebarPeek>

Use mode="viewport" with --refineui-sidebar-peek-viewport-offset when the peek layer should align below a fixed app header.