Panel rail
ProA bar of panel toggles at the frame's end edge, for AppLayout's panelRail: each item opens its panel beside the page, and pressing the open one closes it. It is a toolbar, not navigation: one tab stop, Up and Down between items, Home and End to the ends, and each item a button with aria-expanded (never the current page).
Items are icon-only, each at least 44 px square: the label is the item's name and shows in a tooltip on hover and focus, on the side towards the page (it moves to the other side in right to left). labels="below" puts the words under each icon instead, in a wider rail, for touch screens, where a tooltip never shows. An open item is tinted, with a bar in the marks colour on the edge facing the panel and, in forced colours, a Highlight outline, so it is never colour alone.
A count sits on the icon's top-end corner only when the app gives one above 0: filled in the marks colour when it is urgent, quiet otherwise, and always read in the name ("Comments, 3 waiting"). An item that is locked stays in the rail, marked aria-disabled and with a lock on its icon; it opens nothing, and its tooltip and description say why.
Inside an AppLayout with panels it reads them, and the open panel, from useAppLayout(). Below the layout's panelRailAt it draws as one "Panels" button in the banner, which opens a menu of the panels with the open one checked; the button's name counts what waits in the panels that can be opened, and each item keeps its own count. Outside an AppLayout (an editor's own layout), give it items, openId, onOpen, onClose and controls. The rail is 3rem wide (5rem with labels="below"); a brand may set --cd-panel-rail-width.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/panel-rail
Brings in: app-layout, bidi, button, dropdown-menu, locale, motion, tokens, tooltip, utils · npm: @base-ui/react@^1.9.0, lucide-react@^1.67.0
Usage
"use client"
import * as React from "react"
import { BookOpen, History, Home, MessageSquare, MessagesSquare, Search } from "lucide-react"
import { AppLayout, type AppLayoutPanel } from "@/components/candor/app-layout"
import { PanelRail } from "@/components/candor/panel-rail"
import { NavRail } from "@/components/candor/nav-rail"
const panels: AppLayoutPanel[] = [
{ id: "binder", label: "Binder", Icon: BookOpen, content: <p className="p-3 text-sm">The project's files.</p> },
// An urgent count is filled and read in the name: "Comments, 3 waiting".
{ id: "comments", label: "Comments", Icon: MessageSquare, count: 3, urgent: true, content: <p className="p-3 text-sm">Three comments wait on you.</p> },
{ id: "search", label: "Search", Icon: Search, content: <p className="p-3 text-sm">Search the project.</p> },
// A panel that can't be opened now stays on the rail, and says why.
{ id: "history", label: "History", Icon: History, locked: "Only the project's owners see its history.", content: <p className="p-3 text-sm">Changes</p> },
]
export default function Example() {
// One frame at a time: a page has one main. The phone's frame is narrower than panelRailAt, so the rail is one button.
const [size, setSize] = React.useState<"wide" | "phone">("wide")
const [labels, setLabels] = React.useState<"tooltip" | "below">("tooltip")
const [panelId, setPanelId] = React.useState<string | null>("comments")
const width = size === "wide" ? 640 : 360
return (
<div className="flex flex-col gap-3">
<div className="flex flex-wrap gap-4 text-xs text-muted-foreground">
<label className="flex items-center gap-2">
Frame
<select
value={size}
onChange={(e) => {
// On a phone an open panel is a sheet over the frame: start the phone with none open.
setPanelId(null)
setSize(e.target.value as "wide" | "phone")
}}
className="max-w-full min-w-0 rounded-md border bg-background px-2 py-1 text-foreground"
>
<option value="wide">Wide: the rail at the end edge</option>
<option value="phone">Phone: one Panels button in the banner</option>
</select>
</label>
<label className="flex items-center gap-2">
Labels
<select value={labels} onChange={(e) => setLabels(e.target.value as "tooltip" | "below")} className="max-w-full min-w-0 rounded-md border bg-background px-2 py-1 text-foreground">
<option value="tooltip">Icons, each label in a tooltip</option>
<option value="below">Words under the icons</option>
</select>
</label>
</div>
<div className="h-[420px] max-w-full overflow-hidden rounded-lg border" style={{ width }}>
<AppLayout
key={size}
frame="app"
// Sized for this preview box; in a full-screen app the defaults suit.
defaultWidth={width}
sidebarAt={560}
panelAt={560}
minPanel={200}
defaultPanel={220}
minPage={200}
brand={<span className="flex size-8 items-center justify-center rounded-lg bg-primary text-sm font-bold text-primary-foreground">K</span>}
sidebar={
<NavRail
places={[
{ id: "home", label: "Home", Icon: Home },
{ id: "chat", label: "Chat", Icon: MessagesSquare },
]}
activeId="chat"
/>
}
top={<p className="flex h-12 items-center px-3 text-sm font-medium">Atlas</p>}
panels={panels}
panelId={panelId}
onPanelIdChange={setPanelId}
// The rail reads the panels and the open one from the layout.
panelRail={<PanelRail labels={labels} />}
>
<div className="p-4 text-sm">
<h2 className="font-semibold">Chat</h2>
<p className="mt-2 text-muted-foreground">The rail opens a panel beside the chat; press the open item to close it.</p>
</div>
</AppLayout>
</div>
</div>
)
}<PanelRail>
| Prop | Type | Default | Description |
|---|---|---|---|
| items | readonly PanelRailItem[] | undefined | — | The panels, in order. Left out inside an AppLayout with `panels`, which gives them. |
| openId | string | null | undefined | — | The id of the open panel, or null for none. With `items`; inside an AppLayout, its open panel. |
| onOpen | ((id: string) => void) | undefined | — | Called with an item's id when the person opens its panel, or switches to it from another. With `items`; inside an AppLayout, its `openPanel`. |
| onClose | (() => void) | undefined | — | Called when the person presses the open item to close its panel. With `items`; inside an AppLayout, its `closePanel`. |
| controls | string | undefined | — | The id of the element the open panel is drawn in, for the open item's `aria-controls`. With `items`; inside an AppLayout, its region. |
| labels | "tooltip" | "below" | undefined | "tooltip" | Where the labels show: "tooltip" (the default), icon-only with each label in a tooltip, or "below", under each icon. |
| label | string | undefined | — | The toolbar's accessible name, and the menu button's on a narrow frame. Defaults to "Panels". |
| className | string | undefined | — | Classes for the rail, merged with Candor's. |
Strings
The fixed words, in English by default. Change any of them under panelRail in <LocaleProvider strings={{ … }}>; the table is exported as panelRailStrings.
| Key | English |
|---|---|
| panels | Panels |
| waiting | { one: "{label}, {count} waiting", other: "{label}, {count} waiting" } |
| counted | { one: "{label}, {count}", other: "{label}, {count}" } |
Motion
| Moment | Family | What it does |
|---|---|---|
| tint | tint | An item's background and text colour change when the pointer is over it and when its panel opens or closes, and a ring fades in on keyboard focus. An item whose panel is open when the rail first appears is drawn open at once. |
Set with --cd-motion-panel-rail-<moment>-* in your brand file; the families are in the design reference.
Types
- PanelRailItem
- Declared in `app-layout` and re-exported here. One of the layout's panels as a PanelRail draws it: AppLayout's `panels` without their content. `panel-rail` exports it too, so it can be imported from either.
{ /** The panel's id: AppLayout's `panelId`, and what `openPanel` takes. */ id: string; /** The panel's name: its heading, its region's name, and the rail item's name and tooltip. */ label: string; /** The panel's icon, on the rail and in the panel's head. */ Icon: LucideIcon; /** A count on the rail item, drawn and named only when given and above 0. */ count?: number | undefined; /** The count means "needs you": drawn filled, not quiet, and named "waiting". */ urgent?: boolean | undefined; /** * Why the panel can't be opened now. Its rail item stays, `aria-disabled`, and says why; `openPanel` ignores it. Asked * for through `panelId` or `defaultPanelId`, or locked while open, it isn't drawn, and `onPanelIdChange(null)` says so. */ locked?: string | null | undefined; }