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
Maps without an API key
Segmented controls that slide
One EmptyState for every blank screen
A globe and 3D buildings in two props
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
Give one section its own style
Override Once UI styles without !important
A logo before you have one
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
Maps without an API key
Segmented controls that slide
One EmptyState for every blank screen
A globe and 3D buildings in two props
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
Give one section its own style
Override Once UI styles without !important
A logo before you have one
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

One EmptyState for every blank screen

How to use the EmptyState component: picking a size for a page, card or table, a Mascot or icon above the title, the right heading level, and how to write the title, line and action.
Updated 5 days ago
Segmented controls that slide
A globe and 3D buildings in two props
4 min · Pattern · EmptyState
From @once-ui-system/core 2.8.0, EmptyState is a component. One tag gives a page, card or table row the same empty screen: a visual, a title, one line, and the next step.

Why a component

Every list, table and dashboard starts empty. Until 2.8.0 you built that screen by hand from Column, Icon, Heading, Text and Button, as the Empty & error states pattern shows. That still works, but each hand-built version ends up with its own spacing and its own heading level. EmptyState is the same idea in one tag. DataTable's own empty and no-results states are built from it too, so your pages and your tables match.
import { EmptyState, Button } from "@once-ui-system/core";

<EmptyState
  icon="inbox"
  title="No invoices"
  description="Invoices show up here once a contract is accepted."
  action={<Button size="s" prefixIcon="plus" label="New contract" />}
/>

Pick the size by where it sits

The size prop is about the container, not about how important the message is.
Size
Where
sInside a table, list, select or chart
m (default)In a card or panel
lA whole page with nothing in it yet
s is what DataTable uses, so a custom list with size="s" looks like a table that has no rows.

A visual or an icon

Pass icon for a plain icon above the title. For a first-run page, pass something with more character in : a Mascot, a Cube Emote or your own illustration. When both are set, wins.
visual
visual
<EmptyState
  size="l"
  visual={<Mascot size="l" surface="flat" effects={false} />}
  title="No clients yet"
  description="Invite a client by email. They fill in their company details once."
  action={<Button size="s" prefixIcon="plus" label="New client" />}
/>
A Mascot reads best with surface="flat", and in 2.8.0 the flat surface also drops the white glint in the eyes. The visual is marked aria-hidden, so the title has to say everything on its own.

Get the heading level right

The title is an h2 by default. That is right for a page whose only heading above it is the page title. Inside a card that already has an h2, or in a table, drop it a level with titleAs:
<EmptyState
  size="s"
  icon="search"
  titleAs="h3"
  title="No results"
  description="Try a different search or filter."
  action={<Button size="s" variant="secondary" label="Clear filters" />}
/>

Writing it

  • The title says what is missing. "No clients yet", not "Nothing to see here".
  • One sentence of description. What fills this space, or what happens next.
  • One primary action. If the page header has the same button, hide it there while the page is empty, so the step shows once.
  • secondaryAction is quieter. A link to the docs or an import, as a secondary button.

What it is not

EmptyState is for "the request worked and there is nothing here". A failed request is an error state and should say what went wrong and offer a retry. Data still on its way is a loading state, covered in Loading states. Showing an empty screen while data loads tells people they have nothing, which is worse than a skeleton.

Check yourself

  • size matches the container: s in tables and lists, m in cards, l for a page
  • titleAs drops a level when a heading already sits above it
  • One action, and the same button is not repeated in the header
  • The title makes sense without the visual
More patterns live in this section.
Once UI HandbookPractical guides for building with Once UI. Start with an idea, learn the foundations, and ship your next app.