Icon Rail · paneui

Installation

pnpm dlx shadcn@latest add @paneui/icon-rail

Usage

import { IconRail, IconRailItem, IconRailSpacer } from "@/components/ui/icon-rail"

<IconRail aria-label="App">
  <IconRailItem label="Home" icon={<HomeIcon />} shortcut="⌘1" active />
  <IconRailItem label="Inbox" icon={<InboxIcon />} badge={3} />
  <IconRailSpacer />
  <IconRailItem label="Settings" icon={<SettingsIcon />} />
</IconRail>

Composition

IconRail
├── IconRailGroup
│   └── IconRailItem
├── IconRailSeparator
├── IconRailSpacer
└── IconRailAvatar

Examples

Badges

Horizontal

Icons

Use solid icons at 18px, as the icon usage rules ask. Each item's tooltip shows its label and shortcut, so make the label clear.

Tooltips

Wrap the app (or the rail) in TooltipProvider so moving along the rail opens tooltips instantly after the first one.

API Reference

IconRail

Also accepts every prop of nav.

orientation= "vertical": "vertical" | "horizontal"; A 48px column, or a 48px row (groups, separators and the spacer follow).
tooltipSide= "right" / "top": "right" | "left" | "top" | "bottom"; Side tooltips open on. Defaults to right for a vertical rail and top for a horizontal one; use left for a rail on the right edge.

Prop	Type	Default	Description
orientation	"vertical" \| "horizontal"	"vertical"	A 48px column, or a 48px row (groups, separators and the spacer follow).
tooltipSide	"right" \| "left" \| "top" \| "bottom"	"right" / "top"	Side tooltips open on. Defaults to `right` for a vertical rail and `top` for a horizontal one; use `left` for a rail on the right edge.

data-orientation: vertical or horizontal.

Data attribute	Description
data-orientation	`vertical` or `horizontal`.

IconRailItem

Also accepts every prop of button.

label*: string; Accessible name and tooltip text.
icon*: ReactNode; The glyph.
shortcut: string; Shown as a key chip in the tooltip.
active= false: boolean; Selected state; sets aria-current="page".
badge: number | boolean; Count or dot.
render: ReactElement; Render as another element, e.g. a Link.

Prop	Type	Default	Description
label*	string	—	Accessible name and tooltip text.
icon*	ReactNode	—	The glyph.
shortcut	string	—	Shown as a key chip in the tooltip.
active	boolean	false	Selected state; sets `aria-current="page"`.
badge	number \| boolean	—	Count or dot.
render	ReactElement	—	Render as another element, e.g. a `Link`.

data-active: Present when active.

Data attribute	Description
data-active	Present when active.

IconRailAvatar

Round button for accounts or agent providers at the bottom of the rail. Also accepts every prop of button.

label*: string; Accessible name and tooltip.
status= "offline": "online" | "busy" | "error" | "offline"; Ring colour. online is success, busy warning, error destructive and offline has none.
hint: string; Extra tooltip text, e.g. the connection state.

Prop	Type	Default	Description
label*	string	—	Accessible name and tooltip.
status	"online" \| "busy" \| "error" \| "offline"	"offline"	Ring colour. `online` is success, `busy` warning, `error` destructive and `offline` has none.
hint	string	—	Extra tooltip text, e.g. the connection state.

IconRailGroup

Also accepts every prop of div.

IconRailSeparator

Also accepts every prop of div.

IconRailSpacer

Pushes what follows to the bottom. Also accepts every prop of div.