Components | omverse-ui

Overview

Use EmptyState when a region has no content to show, a search returns no results, or access and system conditions prevent the expected outcome.

First-use project state

Live preview

The message explains why the region is empty and offers a direct next step.

No projects yet

Create your first enterprise project to coordinate work, owners, and delivery milestones.

ProjectsEmptyState.tsx

tsx

1import { Button, EmptyState } from 'omverse-ui'
2 
3<EmptyState
4  variant="bordered"
5  title="No projects yet"
6  description="Create your first project to coordinate work and delivery."
7  primaryAction={<Button leadingIcon="plus">Create project</Button>}
8  secondaryAction={<Button variant="outlined">Import projects</Button>}
9/>

Anatomy

A useful empty state pairs a recognizable visual with a concise outcome, supporting guidance, and proportionate actions.

No projects yet

Create a project to coordinate work.

Create projectImport

Visible to workspace members.12345

1
Visual
Reinforces the state without carrying meaning alone.
2
Title
Names the outcome in a short, direct phrase.
3
Description
Explains why it happened or what to do next.
4
Actions
Offer one primary path and an optional alternative.
5
Context
Adds low-emphasis detail only when it supports a decision.

When to use

Use EmptyState for a meaningful absence that benefits from explanation or recovery guidance.

When not to use

Do not use EmptyState when absence is expected, temporary, or too small to justify a full message.

Avoid

Do not replace loading feedback
Use Spinner or Skeleton while data is still being resolved.
Do not interrupt brief gaps
Leave intentionally optional or self-explanatory regions quiet.
Do not report transient operations
Use Toast for short-lived success or failure feedback.

Variants

Container emphasis and semantic status adapt EmptyState to page-level, bounded, and elevated regions.

Plain

Integrates into a region whose boundary is already clear.

Bordered

Defines an otherwise ambiguous empty region.

Raised

Supports a contained state on an elevated workspace surface.

Semantic status

Empty, search, error, permission, and success select a relevant visual.

States

The component communicates stable outcomes; asynchronous transitions remain owned by the surrounding workflow.

State	Trigger	Visual response	Interaction
First use	No records exist	Neutral visual and creation guidance	Primary creation action
No results	Filters match nothing	Search visual and query guidance	Clear or edit filters
Error	Content cannot be retrieved	Error treatment and explanation	Retry or get help
Permission	Access is restricted	Lock treatment and policy context	Request access when allowed
Success	A completion replaces content	Success treatment and outcome	Continue to next task

Behavior

EmptyState structures content and visual hierarchy while applications own conditions, actions, analytics, and navigation.

Action priority

Render one primary action before a lower-emphasis alternative.

Responsive centering

Content remains centered while actions wrap on narrow surfaces.

Visual override

Product illustrations can replace the status icon without changing structure.

Bounded scale

Three sizes provide predictable minimum height and spacing.

Accessibility

EmptyState is a semantic section whose heading names the region; action components retain their native keyboard behavior.

Connect the section to a visible heading when the surrounding page does not already provide one.
Treat decorative icons and illustrations as hidden from assistive technology.
Include meaningful alternative text only when a custom visual contributes unique information.
Do not rely on status color or iconography to communicate the outcome.
Use descriptive action labels such as “Clear filters” instead of “Click here”.
Move focus only when the surrounding workflow requires a newly important announcement.

Content guidelines

Write for the next decision: confirm the outcome, add only useful context, and label the best available action.

State the outcome

Use a direct title without blame or alarm.

ExampleNo matching projects

Explain the next step

Keep supporting text to one or two short sentences.

ExampleTry removing a filter.

Use specific actions

Name the action and its object.

ExampleCreate project

Avoid dead ends

When no action is possible, explain when or how the state can change.

ExampleAsk a workspace admin for access.

Examples

Status and size can create a compact zero-result message without changing the action model.

Search with no results

Live preview

A compact search state points directly to filter recovery.

No matching projects

Try removing a filter or using a broader search term.

SearchEmptyState.tsx

tsx

1<EmptyState
status="search"
size="sm"
title="No matching projects"
description="Try removing a filter or using a broader search term."
primaryAction={<Button variant="text" onClick={clearFilters}>Clear filters</Button>}
7/>

Props / API

EmptyState extends section attributes and composes design-system actions without owning their behavior.

Props

PropTypeDefaultDescription

titleReactNoderequiredConcise outcome that explains the current state.

descriptionReactNodeundefinedSupporting context or a useful next step.

status'empty' | 'search' | 'error' | 'permission' | 'success''empty'Selects the semantic default visual treatment.

iconIconNamestatus iconOverrides the icon associated with the status.

visualReactNodestatus iconReplaces the icon with an illustration or product asset.

primaryActionReactNodeundefinedHighest-priority recovery or creation action.

secondaryActionReactNodeundefinedLower-priority alternative action.

childrenReactNodeundefinedOptional contextual detail after the actions.

variant'plain' | 'bordered' | 'raised''plain'Controls container emphasis.

size'sm' | 'md' | 'lg''md'Controls spacing, minimum height, and visual scale.

EmptyState