Fixed icon-over-label edge rail for switching tools or modes.
Install with the CLI, or copy the component source into your project.
Add nav-rail (npm)
1npx --yes -p github:itsvigneshv/default-file-ui#main df-ui add nav-rail
Fixed icon-over-label strip on the left edge with an active item and a group separator.
Same contract on the right edge for host layouts that prefer that side.
Horizontal rail on the top edge. width sets the rail height on top and bottom.
Horizontal rail on the bottom edge with a y-axis edge shadow.
Add or omit items, place separators anywhere, and use hidden or disabled for availability.
Compose, hide, and disable items.
Override width, background, border, icon color, active plate, edge shadow intensity, and corner radii with props.
Tool rail: fixed icon-over-label edge chrome for switching tools or modes. Compose items and separators in any order. Place on left, right, top, or bottom. Use edgeShadow with shadowIntensity (2xs to 4xl, subtle, default, strong, or 0 to 1) for a side-matched cast. Chrome is tokenized via --df-nav-rail-* and kit --df-shadow-intensity-* steps.
Edge strip for a flex workspace shell. Vertical sides stack items; horizontal sides row them. Pass appearance props or set the matching CSS variables on style.
| Prop | Type | Default | Notes |
|---|---|---|---|
| side | "left" | "right" | "top" | "bottom" | "left" | Which edge the rail sits on. Controls axis, item flow, separator orientation, and which side draws the inner border. |
| width | string | - | Cross-axis size of the rail. Prefer tokens such as var(--df-nav-rail-width) or calc(18 * var(--spacing-unit)). On left or right this is the rail width. On top or bottom this is the rail height. Sets --df-nav-rail-width. |
| radius | "none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "none" | Corner radius of the rail shell. Maps to --df-nav-rail-radius. |
| itemRadius | "none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "lg" | Corner radius of item icon plates. Maps to --df-nav-rail-item-radius. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| background | string | - | Rail background. Prefer tokens such as var(--background) or var(--card). Sets --df-nav-rail-bg. |
| borderColor | string | - | Inner-edge border color. Prefer tokens such as var(--border). Sets --df-nav-rail-border. |
| iconColor | string | - | Resting icon and label color for all items. Prefer tokens such as var(--muted-foreground). Sets --df-nav-rail-fg. |
| activeBackground | string | - | Active icon-plate fill. Prefer tokens such as var(--df-nav-rail-item-active-bg). Sets --df-nav-rail-item-active-bg on this instance. |
| activeForeground | string | - | Active icon and label color. Prefer tokens such as var(--df-nav-rail-item-active-fg). Sets --df-nav-rail-item-active-fg on this instance. |
| shadow | string | - | Box shadow. Prefer var(--df-nav-rail-shadow-edge-left), right, top, or bottom for an edge cast toward the workspace, or none. Overrides edgeShadow when set. Sets --df-nav-rail-shadow. |
| edgeShadow | boolean | false | When true and shadow is omitted, applies the side-matched edge shadow token. |
| shadowIntensity | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "subtle" | "default" | "strong" | number | - | Edge shadow strength from the kit cast scale (--df-shadow-intensity-*). Prefer 2xs to 4xl. subtle, default, and strong alias xs, lg, and 2xl. Pass 0 to 1 only for a custom strength. Sets --df-nav-rail-shadow-intensity. Theme default is --df-shadow-intensity-default. |
| children | ReactNode | - | Compose NavRailItem and NavRailSeparator in any order. Omit an item to remove it; place separators where you want groups. |
| className | string | - | Additional classes on the rail root. |
| style | CSSProperties | - | Inline styles. Override --df-nav-rail-width, --df-nav-rail-bg, --df-nav-rail-border, --df-nav-rail-fg, --df-nav-rail-item-active-bg, --df-nav-rail-item-active-fg, --df-nav-rail-shadow, --df-nav-rail-shadow-intensity, --df-nav-rail-radius, or --df-nav-rail-item-radius directly. |
| …nav attributes | HTMLAttributes | - | Native nav attributes on the rail root. |
Centered icon with a short label underneath. Pass any icon node. Set active for the current item. Use disabled or hidden for availability. Buttons expose aria-pressed; link hosts via asChild expose aria-current when active.
| Prop | Type | Default | Notes |
|---|---|---|---|
| icon | ReactNode | - | Glyph shown above the label. Replace per item as needed. |
| active | boolean | false | Marks the current item and styles the icon plate. |
| disabled | boolean | false | Disables interaction and dims the item. Works for button and asChild link hosts. |
| hidden | boolean | false | When true, the item is not rendered. |
| iconColor | string | - | Resting icon and label color for this item. Prefer tokens. Sets --df-nav-rail-item-fg. |
| activeBackground | string | - | Active icon-plate fill for this item. Prefer tokens. Sets --df-nav-rail-item-active-bg. |
| activeForeground | string | - | Active icon and label color for this item. Prefer tokens. Sets --df-nav-rail-item-active-fg. |
| asChild | boolean | false | Merge item props onto a single child element. The child becomes the interactive root; icon and label render inside it. |
| children | ReactNode | - | Short label when asChild is false. When asChild is true, a single element whose children are the label text. |
| className | string | - | Additional classes on the item root. |
| style | CSSProperties | - | Inline styles. Override --df-nav-rail-item-fg, --df-nav-rail-item-active-bg, or --df-nav-rail-item-active-fg directly. |
| …button attributes | ButtonHTMLAttributes | - | Native button attributes when asChild is false. With asChild, compatible props merge onto the child. |
Hairline divider between item groups. Place anywhere in the rail children.
| Prop | Type | Default | Notes |
|---|---|---|---|
| color | string | - | Separator color. Prefer tokens such as var(--border). Sets --df-nav-rail-separator. |
| hidden | boolean | false | When true, the separator is not rendered. |
| className | string | - | Additional classes on the separator. |
| style | CSSProperties | - | Inline styles. Override --df-nav-rail-separator directly. |
| …div attributes | HTMLAttributes | - | Native div attributes on the separator. |
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-nav-rail-width | CSS length | calc(16 * var(--spacing-unit)) | Cross-axis size. Width on left or right; height on top or bottom. |
| --df-nav-rail-bg | CSS color | var(--background) | Rail background. |
| --df-nav-rail-border | CSS color | var(--border) | Inner-edge border color. |
| --df-nav-rail-fg | CSS color | var(--muted-foreground) | Resting icon and label color. |
| --df-nav-rail-fg-hover | CSS color | var(--foreground) | Hover icon and label color. |
| --df-nav-rail-item-hover-bg | CSS color | var(--muted) | Hover icon-plate fill. |
| --df-nav-rail-item-active-bg | CSS color | - | Active icon-plate fill. |
| --df-nav-rail-item-active-fg | CSS color | - | Active icon and label color. |
| --df-nav-rail-separator | CSS color | var(--border) | Separator fill. |
| --df-shadow-intensity-2xs | CSS percentage | 5% | Kit cast strength scale: 2xs. |
| --df-shadow-intensity-xs | CSS percentage | 6% | Kit cast strength scale: xs. |
| --df-shadow-intensity-sm | CSS percentage | 8% | Kit cast strength scale: sm. |
| --df-shadow-intensity-md | CSS percentage | 10% | Kit cast strength scale: md. |
| --df-shadow-intensity-lg | CSS percentage | 12% | Kit cast strength scale: lg. |
| --df-shadow-intensity-xl | CSS percentage | 16% | Kit cast strength scale: xl. |
| --df-shadow-intensity-2xl | CSS percentage | 20% | Kit cast strength scale: 2xl. |
| --df-shadow-intensity-3xl | CSS percentage | 28% | Kit cast strength scale: 3xl. |
| --df-shadow-intensity-4xl | CSS percentage | 35% | Kit cast strength scale: 4xl. |
| --df-shadow-intensity-subtle | CSS percentage | var(--df-shadow-intensity-xs) | Alias of --df-shadow-intensity-xs. |
| --df-shadow-intensity-default | CSS percentage | var(--df-shadow-intensity-lg) | Alias of --df-shadow-intensity-lg. |
| --df-shadow-intensity-strong | CSS percentage | var(--df-shadow-intensity-2xl) | Alias of --df-shadow-intensity-2xl. |
| --df-nav-rail-shadow | CSS box-shadow | none | Rail box shadow. |
| --df-nav-rail-shadow-intensity | CSS percentage | var(--df-shadow-intensity-default) | Opacity used by edge shadow tokens. Defaults to --df-shadow-intensity-default. Set via shadowIntensity. |
| --df-nav-rail-shadow-edge-left | CSS box-shadow | - | Edge shadow for side left. Strength follows --df-nav-rail-shadow-intensity. |
| --df-nav-rail-shadow-edge-right | CSS box-shadow | - | Edge shadow for side right. Strength follows --df-nav-rail-shadow-intensity. |
| --df-nav-rail-shadow-edge-top | CSS box-shadow | - | Edge shadow for side top. Strength follows --df-nav-rail-shadow-intensity. |
| --df-nav-rail-shadow-edge-bottom | CSS box-shadow | - | Edge shadow for side bottom. Strength follows --df-nav-rail-shadow-intensity. |
| --df-nav-rail-radius | CSS length | 0 | Rail shell corner radius. |
| --df-nav-rail-item-radius | CSS length | var(--radius-lg) | Item icon-plate corner radius. |
| --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. |
| --df-demo-stage-height | CSS length | calc(112 * var(--spacing-unit)) | Shared height for docs workspace stage frames. |