Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
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
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
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
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
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles
TrademarkTrademark
Ctrl k
Search...
Sign up
Once UI Handbook
Beginner Guides
What is Once UI?
Install & config
Page skeleton
Your first page
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
Vibe Coding
Introduction to vibe coding
Set up your local dev environment
Essential tools for vibe coding
Build your first Once UI app
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
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
Block updates
Block updates changelog
Agent Resources
Column, not Flex
Semantics over CSS
Typography scale
Common gotchas
Block anchors
Validate generated code
Pro block registry
Match task bundles

Form layout

Stack fields, group sections, and place actions in Once UI forms.
Updated 19d ago
Static panel
Highlighted card
TrademarkTrademark
Once UIDocumentationBlog
© Once UI. All rights reserved.
Built with Aveiro
5 min · Pattern
Forms in Once UI are stacked Columns with consistent gaps — label, field, helper text, grouped into sections.

Basic field

A single form field is a vertical stack: Gap "8" keeps label, input, and helper tight. Use "16" between separate fields.

Form section

Group related fields under a section title:

Actions row

Place submit/cancel below the fields: Primary action first. Stack on mobile with breakpoint props.

Inside a static panel

Wrap settings forms in the surface recipe:

Write this / not this

✅ Once UI way
❌ Common mistake
`Column gap="8"` per fieldLabel and input in a `Row`
`fillWidth` on inputsFixed pixel widths
`label-default-s` for labels`body-default-m` for field labels
`gap="16"` between fieldsInconsistent margins

Accessible defaults

  • Always set id on inputs and match with label htmlFor when using separate Text labels
  • Use built-in label prop on form controls when the component supports it
  • Group related fields in a Column, not a flat list

Check yourself

  • Each field is a Column gap="8"
  • Fields separated by gap="16"
  • Section title uses display-strong-xs
  • Inputs have fillWidth

Related

→ Static panel → Form controls reference: docs.once-ui.com
<Column gap="8" fillWidth>
  <Text variant="label-default-s" onBackground="neutral-weak">
    Email address
  </Text>
  <Input
    id="email"
    placeholder="you@example.com"
    fillWidth
  />
  <Text variant="body-default-xs" onBackground="neutral-weak">
    We'll never share your email.
  </Text>
</Column>
<Column gap="24" fillWidth>
  <Column gap="8">
    <Heading variant="display-strong-xs">Account details</Heading>
    <Text variant="body-default-s" onBackground="neutral-weak">
      Update your profile information.
    </Text>
  </Column>

  <Column gap="16" fillWidth>
    <Column gap="8" fillWidth>
      <Text variant="label-default-s" onBackground="neutral-weak">Name</Text>
      <Input id="name" fillWidth />
    </Column>
    <Column gap="8" fillWidth>
      <Text variant="label-default-s" onBackground="neutral-weak">Email</Text>
      <Input id="email" type="email" fillWidth />
    </Column>
  </Column>
</Column>
<Row gap="16" s={{ direction: "column" }}>
  <Button type="submit">Save changes</Button>
  <Button variant="secondary">Cancel</Button>
</Row>
<Column
  background="surface"
  border="neutral-alpha-weak"
  radius="l"
  padding="24"
  gap="24"
  fillWidth
>
  {/* form sections */}
</Column>