Empty State
Empty State explains why a view has no content yet and offers the next step. Use it for empty pages, lists and search results.
Beta until design reviews the code-only compact size and the 400px text width. The default size follows the empty Spaces page in Figma (2864:77703).
Preview
Change the controls to try every supported combination.
Organize your learning into spaces
Group related lessons by subject, course, or goal so you can come back to them anytime.
<EmptyState
icon={<RiStackLine />}
title="Organize your learning into spaces"
description="Group related lessons by subject, course, or goal so you can come back to them anytime."
actions={
<Button intent="primary" appearance="ghost" corners="rounded" size="lg" leadingIcon={<RiAddFill />} onClick={createSpace}>
Create Space
</Button>
}
/>Installation
Availability
@nuton/ui and @nuton/tokens are private workspace packages and aren't published yet (D4, D12). Inside the Nuton monorepo, add them as workspace dependencies.
pnpm add @nuton/ui @nuton/tokens @remixicon/reactnpm install @nuton/ui @nuton/tokens @remixicon/reactyarn add @nuton/ui @nuton/tokens @remixicon/reactimport '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'Usage
import { Button, EmptyState } from '@nuton/ui'
import { RiAddFill, RiStackLine } from '@remixicon/react'
<EmptyState
icon={<RiStackLine />}
title="Organize your learning into spaces"
description="Group related lessons by subject, course, or goal so you can come back to them anytime."
actions={
<Button intent="primary" appearance="ghost" corners="rounded" size="lg" leadingIcon={<RiAddFill />} onClick={createSpace}>
Create Space
</Button>
}
/>- Say what will appear here and how to get it. Lead with the benefit, not “Nothing here”.
- Offer one main action. Add a second only if it's a real alternative, such as “Browse templates”.
- The title is an
h2by default (h3when compact). SettitleAsto fit the page outline,h1when the empty state is the whole page (a 404), orpwhen the container already has a heading. - The icon is decorative and hidden from screen readers. Use a plain 24px Remix icon (Figma) or a KeyIcon.
- Use
size="compact"inside cards, lists, panels and menus.
Variants and sizes
Sizes
No spaces yet
Group related lessons so you can find them later.
No spaces yet
Group related lessons so you can find them later.
<EmptyState icon={<RiStackLine />} title="No spaces yet" description="…" actions={…} />
<EmptyState size="compact" icon={<RiStackLine />} title="No spaces yet" description="…" actions={…} />Icon options
Plain icon (Figma)
Key icon
<EmptyState icon={<RiStackLine />} title="Plain icon (Figma)" />
<EmptyState icon={<KeyIcon icon={<RiStackLine />} size={40} />} title="Key icon" />| Part | Default (Figma) | Compact (code-only) |
|---|---|---|
| Padding | 40 top and bottom, 0 sides | 24 top and bottom, 16 sides |
| Gap (icon · text · actions) | 12 | 8 |
| Icon | 24px, Icon/Strong-950 | 20px, Icon/Sub-600 |
| Title | Label/Medium, Text/Strong-950 | Label/Small, Text/Strong-950 |
| Description | Paragraph/Small, Text/Sub-600, gap 4 | Paragraph/X Small, Text/Sub-600, gap 4 |
| Text width | Up to 400px (code-only), centred | |
| Action | Button primary · ghost · rounded · lg (52px) | Button sm or LinkButton |
States and interactions
Empty State has no states of its own. Its actions keep their own states (see Button and Link button).
Composition examples
No search results
A compact empty state with a way out. A visually hidden status message announces the result.
Inside a card
API reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
titlerequired | ReactNode | — | What is empty, or what the person can do here. |
description | ReactNode | — | One or two sentences on why it is empty or what to do next. |
icon | ReactNode | — | Decorative visual: a Remix icon (sized to 24 or 20) or a KeyIcon. Hidden from assistive technology. |
illustration | ReactNode | — | A larger decorative illustration above the title, such as NuriPeek (pages) or NuriMedallion (cards and panels). Replaces icon when both are given. Hidden from assistive technology. |
actions | ReactNode | — | Buttons or LinkButtons. They wrap and centre, gap 8. |
size | 'default' | 'compact' | 'default' | Default for pages and panels (Figma); compact for cards and lists (code-only). |
titleAs | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'h2' (compact: 'h3') | Element for the title, to fit the page outline. |
…div props | HTMLAttributes<HTMLDivElement> | — | className, id, role and other attributes. The ref points at the outer div. |
Accessibility
Keyboard
Only the actions take focus, in reading order. Don't move focus to an empty state unless the person just removed the last item; then move it to the main action.
Screen readers
The title is a heading by default, so people can find it; the icon is hidden. When an empty state appears after a search or filter, announce it with a status message.
Focus
Actions use their own focus styles (Button, LinkButton).
Contrast and colour
Title 17.93:1, description 6.69:1, default icon 17.93:1 and compact icon 6.69:1 against white.
Touch and pointer
The Figma action is a 52px button. LinkButtons are 20px tall, so give them space (C28).
You must: choose a heading level that fits the page, and give every action a clear label.
Figma mapping
| Figma layer | Figma value | Code |
|---|---|---|
| stack-line | 24px Remix icon | icon |
| “Organize your learning into spaces” | Label/Medium | title |
| “Group related lessons…” | Paragraph/Small | description |
| Buttons (Primary, Ghost, Rounded, Medium 40) | “+ Create Space” | actions with <Button size="lg"> (C4) |
Guidelines and related components
Use Empty State for
- First use, before anything is created
- No search or filter results
- Cleared lists, like an empty inbox
Don't use Empty State for
- Content that is still loading (use Skeleton)
- Errors that need fixing (show an error message with a retry)
Do and don't
Organize your learning
Group lessons by subject or goal.
No data