Empty States

Empty states appear when there’s no content to display. They guide users on what to do next and prevent confusion when lists, search results, or data views are empty.

When to Use

Empty states should be used whenever a view that normally contains content is empty:

• First-time use - When users haven’t created any content yet
• Search results - When no items match the search criteria
• Filtered views - When filters exclude all content
• Error states - When content fails to load
• Deleted content - After users remove all items
• Permission issues - When users lack access to content

Anatomy

A well-designed empty state contains:

1. Icon or illustration - Visual representation of the state
2. Title - Clear headline explaining the situation
3. Description - Brief explanation or guidance
4. Action - Button or link to resolve the empty state

Implementation

Basic Empty State

<EmptyState
	title="No results found"
	description="Try adjusting your filters or search terms"
	icon="/svg/search.svg"
/>

With Action Button

<EmptyState
	title="No projects yet"
	description="Create your first project to get started"
	icon="/svg/folder.svg"
>
	{#snippet actions()}
		<Button variant="primary">Create Project</Button>
	{/snippet}
</EmptyState>

With Border

<EmptyState
	title="No data available"
	description="Data will appear here once available"
	icon="/svg/chart.svg"
	border={true}
/>

Size Variants

Small (sm)

Use for inline empty states within cards or sidebars.

• Compact layout
• Smaller icon (32px)
• Minimal padding

Medium (md) - Default

Standard size for most empty states.

• Balanced proportions
• Medium icon (48px)
• Comfortable spacing

Large (lg)

Full-page empty states or onboarding.

• Generous spacing
• Large icon (64px)
• Prominent call-to-action

Content Guidelines

Writing Effective Empty States

Title

• Be specific about what’s missing
• Use positive framing when possible
• Keep it short - 3-5 words ideal

Description

• Explain why the state is empty
• Provide guidance on next steps
• Be encouraging rather than apologetic
• Stay concise - 1-2 sentences max

Examples

✅ Good

• Title: “No messages yet”
• Description: “Messages from your team will appear here”

❌ Poor

• Title: “Empty”
• Description: “There is no data to display at this time”

Common Patterns

Search Results

<EmptyState
	title="No matches found"
	description="Try different keywords or remove filters"
	icon="🔍"
/>

First Time User

<EmptyState
	title="Welcome! Let's get started"
	description="Create your first document to begin"
	icon="📝"
	size="lg"
>
	{#snippet actions()}
		<Button variant="primary">Create Document</Button>
		<Button variant="ghost">Watch Tutorial</Button>
	{/snippet}
</EmptyState>

Permission Denied

<EmptyState
	title="Access restricted"
	description="Contact your admin for access to this content"
	icon="🔒"
>
	{#snippet actions()}
		<Button variant="secondary">Request Access</Button>
	{/snippet}
</EmptyState>

Loading Failed

<EmptyState
	title="Couldn't load content"
	description="Check your connection and try again"
	icon="/svg/error.svg"
>
	{#snippet actions()}
		<Button variant="primary" onclick={retry}>Retry</Button>
	{/snippet}
</EmptyState>

Best Practices

Do’s

• ✅ Provide clear next steps
• ✅ Use friendly, encouraging language
• ✅ Include relevant illustrations
• ✅ Offer alternative actions when possible
• ✅ Match the tone to your brand

Don’ts

• ❌ Leave users confused about what to do
• ❌ Use technical error messages
• ❌ Show empty states during loading
• ❌ Blame the user for the empty state
• ❌ Use generic messages for all cases

Accessibility

• Include appropriate ARIA labels
• Ensure keyboard navigation to actions
• Provide sufficient color contrast
• Use semantic HTML structure
• Test with screen readers

Alternative Approaches

Progressive Disclosure

Instead of showing everything empty, reveal sections as users complete actions.

Skeleton States

Show content structure while loading instead of empty states.

Default Content

Provide sample or demo content for new users.

Inline Prompts

Use smaller, contextual prompts instead of full empty states.