Once UI Handbook
Vibe coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Getting started
What is Once UI?
Install & config
Page skeleton
Your first page
Upgrade from 1.8 to 2.0
Once UI without Next.js
Build and launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Common patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Forms that wire themselves
An icon rail that opens on hover
Design tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Border radius & nested corners
Bring your own icons
Agent resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
Block updates
Block updates changelog
TrademarkTrademark
Ctrl k
Search…
Sign up
Once UI Handbook
Vibe coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
Getting started
What is Once UI?
Install & config
Page skeleton
Your first page
Upgrade from 1.8 to 2.0
Once UI without Next.js
Build and launch
How to launch a portfolio site that actually gets you hired
How to build a documentation site with MDX and Next.js
How to ship a landing page and dashboard with authentication in Next.js
How to launch a social app with Next.js and Supabase
Common patterns
Hero section
Static panel
Form layout
Highlighted card
Responsive stacking
Decoration layers
Dialog & modal
Toast & feedback
Tables & lists
Loading states
App shell navigation
Dashboard & charts
Chat & messaging
Auth & verification
Settings & split panels
Data filters & toolbar
Command palette
Pricing & plans
Accordion & FAQ
Media & uploads
Empty & error states
SEO, Open Graph, and structured data
Documentation code blocks with live preview
Carousels, galleries, and before/after comparisons
Date pickers and scheduling
Context menus and dropdown actions
Tags, chips, and multi-value inputs
Roadmap & kanban
Form inputs & controls
Progress, status & badges
Scrolling & feeds
Profile, avatars & identity
Social proof & logo clouds
Masonry & media grids
Table pagination, search & bulk selection
Banners & announcements
Footer layouts
Onboarding & first run
Waitlist & coming soon
Forms that wire themselves
An icon rail that opens on hover
Design tips
Color & surfaces
Harness overview
Row, Column & Grid
Spacing & rhythm
Icons & buttons
Reveal & motion
Theme tokens, FOUC-free init, and runtime style controls
Tooltips and hover cards
Border radius & nested corners
Bring your own icons
Agent resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
Block updates
Block updates changelog
TrademarkTrademark
Once UIDocumentationBlog
© Once UI. All rights reserved.
Built with Aveiro
Common Patterns

An icon rail that opens on hover

Use Nav's collapsed, expandOnHover and expandedWidth props to build an editor-style icon rail that opens over the page instead of showing a tooltip per icon.
Updated 1 hour ago
Forms that wire themselves
4 min · Pattern · Navigation
Since 2.6, Nav can collapse to one column of icons and open over the page on hover, so an editor sidebar doesn't need a tooltip on every icon.

Why icon rails usually feel cheap

Editors and dense apps keep only the icons in the sidebar to give the canvas room. The usual fix for "what does this icon do" is a tooltip per icon. It works, but you read one label at a time, and next to native apps it feels second-rate. @once-ui-system/core 2.6 makes the rail a Nav feature instead. You don't compose it by hand, and you don't add tooltips.

Collapse the Nav

Set collapsed and the Nav narrows to a single icon column. Labels, badges and section headings fade out, and any NavGroup closes (it reopens when the rail expands). Every row still answers to its label for a screen reader, so nothing is lost for keyboard and assistive tech users. The collapsed width follows the density: 64px for normal and spacious, 36px for compact, plus the padding you give the Nav.

Open it over the page

Add expandOnHover and the rail opens, labels and all, when a mouse rests on it or keyboard focus moves into it. Escape or moving focus away closes it. Touch never opens it, and reduced motion drops the animation. The important part is that it keeps its collapsed width in the layout. It widens over the content beside it rather than pushing it, so your panel never jumps. expandedWidth sets how wide it opens, in rem or a spacing token, and defaults to 16.
<Row fill>
  <Nav aria-label="Editor" collapsed expandOnHover expandedWidth={12} padding="8" borderRight>
    <NavItem icon="pages" label="Pages" />
    <NavItem icon="grid" label="Layouts" selected />
    <NavItem icon="sparkle" label="Components" />
    <NavItem icon="settings" label="Settings" />
  </Nav>
  <Column fill>{panel}</Column>
</Row>
If you want a button that toggles the rail instead of hover, leave out expandOnHover. Then collapsed is a static icon rail and you flip it from your own state.

Two things that trip people up

  • Clipping. The open rail sits above whatever follows it. If an ancestor clips overflow, for example a sidebar Column with overflowY="auto", the open rail gets cut off at that edge. Keep the Nav outside it.
  • Missing icons. A collapsed row is just its icon. Give every NavItem an icon, or that row shows as an empty pill.

Write this / not this

Do
Avoid
`<Nav collapsed expandOnHover>`A narrow `Column` of `IconButton`s
A `label` on every `NavItem`A `Tooltip` wrapped around each icon
The `Nav` outside scrolling containersA rail inside `overflowY="auto"`

Reference

The Nav page in the Once UI docs has a live example of the rail and the full prop list.