AppSidebar
The sidebar every signed-in and reference surface shares: a brand slot, the page list in sections, and a foot slot, usually the account row. It has no router and no session, so the caller passes the current href, the account and every string.
Two sidebars
The app form has md rows, the current row raised, on the shell colour. The reference form has sm rows and the current row tinted, on the page colour. An item with no href stays muted and is not a link.
TSX
const app = [
{ items: [
{ label: "Home", href: "/app", icon: <SearchIcon size="md" /> },
{ label: "Profile", href: "/app/profile", icon: <FileIcon size="md" />, match: "prefix" },
{ label: "Listing", href: "/app/listing", icon: <GlobeIcon size="md" />, trailing: "Not open" },
] },
{ items: [{ label: "Settings", href: "/app/settings", icon: <LockIcon size="md" /> }] },
];
const reference = [
{ items: [{ label: "Get started", href: "/ds" }] },
{ title: "Foundations", items: [{ label: "Color", href: "/ds/color" }, { label: "Typography" }] },
{ title: "Components", items: [{ label: "Button", href: "/ds/button" }, { label: "Chip" }] },
];
<AppSidebar label="Your account" sections={app} currentHref="/app"
size="md" current="raised" width={240} brand={...} foot={<SidebarAccountRow ... />} />
<AppSidebar label="Design system" sections={reference} currentHref="/ds/color"
closedText="not written yet" width={272} brand={...} />Sizes and current marks
Size sets the row, and current sets how the current row and hover are drawn. Pick them together: tint on the page colour, raised on the shell colour.
TSX
<AppSidebar label="Example" sections={pair} currentHref="/home" size="sm" current="tint" />
<AppSidebar label="Example" sections={pair} currentHref="/home" size="sm" current="raised" />
<AppSidebar label="Example" sections={pair} currentHref="/home" size="md" current="tint" />
<AppSidebar label="Example" sections={pair} currentHref="/home" size="md" current="raised" />The account row
The foot slot's usual content. Sign out is a form button, never a link. With no account yet it shows a neutral person and the setup label.
Avery Foobar
Stand-in account
Setting up
TSX
<SidebarAccountRow
account={{ name: "Avery Foobar", initials: "AF", secondary: "Stand-in account" }}
signOutAction="/auth/sign-out"
signOutLabel="Sign out"
neutralLabel="Setting up"
/>
<SidebarAccountRow account={null} signOutAction="/auth/sign-out"
signOutLabel="Sign out" neutralLabel="Setting up" />During setup
While setup is not finished the whole sidebar is inert: dimmed to half and out of the Tab order, with a neutral person in the foot.
TSX
<AppSidebar label="Your account" sections={app} currentHref="/app"
size="md" current="raised" width={240} inert
foot={<SidebarAccountRow account={null} ... />} />On a phone
SidebarSheet is the sidebar on a phone, opened from the menu button. It holds the same AppSidebar, so a page passes the same sections and strings. The docs site opens its own page list in a native dialog instead.
Code
TSX
<AppSidebar
label="Your account"
sections={app}
currentHref="/app"
size="md"
current="raised"
width={240}
brand={<span className="px-3 font-semibold">Fair Case</span>}
foot={
<SidebarAccountRow
account={{ name: "Avery Foobar", initials: "AF", secondary: "Stand-in account" }}
signOutAction="/auth/sign-out"
signOutLabel="Sign out"
neutralLabel="Setting up"
/>
}
/>Trimmed from app-sidebar.stories.tsx (the App story and its account() helper). The docs site's own sidebar is this component with size sm and current raised (docs-sidebar.tsx). On a phone the same sidebar goes inside SidebarSheet.
Variants
| Prop | Value | How it looks |
|---|---|---|
| size | sm | Row min height 32px, 6px top and bottom padding, text-sm (14px). For reference lists. |
| size | md | Row min height 44px, or 40px from lg (1024px), 10px top and bottom padding, 15px text on a 20px line. For app navigation. |
| current | tint | Hover and the current row take the tint fill (#EEF6FF light, #122A43 dark). For a sidebar on the page colour. |
| current | raised | Hover takes the shell-hover fill (#FAFDFF light, #122A43 dark). The current row takes the surface colour (#FAFDFF light, #092139 dark) with a 1px inset rule ring (#B2D5FF light, #23446A dark). For a sidebar on the shell colour (#EEF6FF light, #00172E dark), beside the inset surface. |
| state | link | Text colour, no fill until hover. An anchor with an href. |
| state | here | Weight 600 in the text colour, with the current mark above. aria-current is page. |
| state | closed | A span, not a link: muted text (#4A5D72 light, #9FB3C8 dark), never faded, so it keeps its contrast. |
| row | all sizes | 12px gap between icon, label and trailing text, 12px side padding, rounded-12, full width, text left. Colour eases over 300ms. |
| section title | titled | text-label (12px on 18px), weight 500, muted, capitals, 0.06em tracking. 12px side padding, 20px above and 6px below. Rows in a section are 2px apart. |
| section title | untitled, after the first | A 1px rule (#B2D5FF light, #23446A dark) with 6px above and below, in place of a heading. |
| trailing | status text | 12px on a 16px line, weight 400, muted, pushed to the row's end, such as Not open. A status, not a count. |
| account avatar | signed in | 32px circle, accent-hover fill (#143D8D light, #B2D5FF dark), initials at 13px on a 16px line, weight 600, in the page colour. |
| account avatar | no account | 32px circle in the tint fill with a 1px inset rule ring, muted, holding the 16px person glyph. |
| account row | foot | A 1px rule along its top, 8px side padding, 12px above, 10px between avatar, text and button. The name is 14px weight 600; the second line is 12px muted. Both truncate. |
| sign-out button | SignOutIcon | 44px circle, or 32px from lg. Muted glyph that takes the text colour and the tint fill on hover. The glyph is SignOutIcon from @repo/ui/icons at size sm. |
| list | scrolls on its own | The page list scrolls inside the sidebar in a ScrollArea: each edge fades over 24px while more lies beyond it, with 24px of padding under the last row so it scrolls clear. |
States
| State | How it looks |
|---|---|
| rest | A link in the text colour, no fill. A closed item is muted and not a link. |
| hover | link rows only. tint: the tint fill. raised: the shell-hover fill. Eases over 300ms. |
| current | aria-current is page on the item whose href is currentHref. Weight 600, with the tint fill (tint) or the surface colour and rule ring (raised). |
| closed | An item with no href: muted, no hover. Screen readers hear the label, then closedText in brackets. |
| inert | The whole sidebar at opacity 50%, out of the Tab order and the accessibility tree. |
| focus | The global 2px focus ring with a 2px gap. |
| sheet | SidebarSheet shows the same sidebar on a phone, opened from the menu button. |
| pressed | not written |
Props
Import from @repo/ui/app-sidebar.
| Prop | Type | Default | What it does |
|---|---|---|---|
| label | string | default required | The nav landmark's name, such as "Design system" or "Your account". |
| sections | readonly SidebarSection[] | default required | The page list. A section is { title?, items }. An item is { label, href?, icon?, trailing?, match? }. An item with no href is listed but is not a link. |
| currentHref | string | undefined | The current page's href. The item with that href gets aria-current="page". An item with match "prefix" is also current on the routes under it. | |
| closedText | string | undefined | Read after an item with no href, for screen readers, as (text). | |
| brand | ReactNode | The top slot, usually the lockup. | |
| search | ReactNode | Under the brand, above the list: a search field or button. | |
| foot | ReactNode | Pinned under the list, which scrolls on its own: an account row, or a theme switch and a link out. | |
| inert | boolean | undefined | Greyed out (opacity 50%) and unreachable through the inert attribute, such as during setup. | |
| width | number | undefined | Width in px from lg (1024px) up, set as --sidebar-width. Below lg the sidebar has no width of its own. | |
| size | "sm" | "md" | default "sm" | Row size. sm for reference lists, md for app navigation. |
| current | "tint" | "raised" | default "tint" | How the current row is marked. tint is for a sidebar on the page colour, raised for a sidebar on the shell colour. |
| onNavigate | (() => void) | undefined | Called when a link is clicked, such as to close a phone's menu. | |
| link | ComponentType<SidebarLinkProps> | undefined | The element that draws each link: a plain anchor by default. A router's link goes here so navigation stays client-side. | |
| className | string | undefined | Extra classes on the root. | |
| state | "link" | "here" | "closed" | default "link" | On sidebarItemVariants only, set by the sidebar for each row: a link, the current page, or an item with no href. |
| sidebarItemVariants | cva function | Exported so another element can wear a row's classes (the docs site's script swaps the current row with them). | |
| isCurrent | (item, currentHref?) => boolean | Whether an item is the page at currentHref, by the same rule the sidebar uses. | |
| account | SidebarAccount | null | default required | On SidebarAccountRow. { name, initials, secondary? }. null while setup is not finished: a neutral person and the neutralLabel. |
| signOutAction | string | default required | On SidebarAccountRow. The form's POST target. Signing out is a form, never a link, so a prefetch or a crawler cannot end a session. |
| signOutLabel | string | default required | On SidebarAccountRow. The sign-out button's accessible name and its title. |
| neutralLabel | string | default required | On SidebarAccountRow. Shown in place of a name while there is no account. |
| SidebarSheet | component | The sidebar on a phone, opened from the menu button. From @repo/ui/sidebar-sheet. |
Use it well
Render it on the server. It has no router and no session, so pass the current href and every string.
Give an item no href for a page that is not open yet. It stays listed, is not a link, and says so to screen readers through closedText.
Sign out is a POST form, never a link, so a prefetch or a crawler cannot end a session.
Pick size and current together: sm and tint for reference lists on the page colour, md and raised for an app on the shell colour.
Pass a router's link as link so navigation stays client-side.
Hide SidebarSheet's menu button from lg up, where the sidebar itself shows.