Empty State

The Empty State component displays a placeholder when there's no data to show. It's useful for empty lists, no results, or initial states in your application.

Installation

Add the empty state component to your project:

npx velyx@latest add empty-state

pnpm dlx velyx@latest add empty-state

yarn dlx velyx@latest add empty-state

bunx --bun velyx@latest add empty-state

Usage

Default Empty State

        <x-ui.empty-state
            title="No projects yet"
            description="Create your first project to start collaborating with your team."
            icon="folder-open"
        />
    

With Action Button

        <x-ui.empty-state
            title="No projects yet"
            description="Create your first project to start collaborating with your team."
            icon="folder-open"
            action-label="Create project"
            action-url="#"
        />
    

Ghost Variant

        <x-ui.empty-state
            title="No notifications"
            description="You are all caught up for now."
            icon="bell-off"
            variant="ghost"
            size="sm"
        />
    

Props

Examples

Basic Empty State

<x-ui.empty-state
    title="No results found"
    description="Try adjusting your search terms."
    icon="search"
/>

With Action Button

<x-ui.empty-state
    title="No projects yet"
    description="Get started by creating your first project."
    icon="folder-open"
    action-label="New Project"
    action-url="/projects/create"
/>

Without Icon

<x-ui.empty-state
    title="All caught up"
    description="You have no pending tasks."
/>

With Custom Icon

<x-ui.empty-state
    title="No files uploaded"
    description="Upload files to see them here."
    icon="upload-cloud"
/>

Small Size

<x-ui.empty-state
    title="No data"
    size="sm"
/>

Large Size

<x-ui.empty-state
    title="No results"
    size="lg"
    description="Try adjusting your filters."
/>

Outline Variant

<x-ui.empty-state
    title="Empty list"
    description="This list is currently empty."
    variant="outline"
/>

Ghost Variant (Minimal)

<x-ui.empty-state
    title="No notifications"
    description="You're all caught up!"
    variant="ghost"
    size="sm"
/>

In a Card

<div class="rounded-lg border bg-card p-6">
    <h2 class="text-lg font-semibold mb-4">Projects</h2>

    <div class="rounded-lg border border-border p-8">
        <x-ui.empty-state
            title="No projects yet"
            description="Create your first project to get started."
            icon="folder-open"
            action-label="Create Project"
            action-url="/projects/create"
        />
    </div>
</div>

With Conditional Content

@if ($projects->count() === 0)
    <div class="rounded-lg border border-border p-8">
        <x-ui.empty-state
            title="No projects yet"
            description="Create your first project to get started."
            icon="folder-open"
            action-label="Create Project"
            action-url="/projects/create"
        />
    </div>
@else
    <div class="space-y-2">
        @foreach ($projects as $project)
            <!-- project items -->
        @endforeach
    </div>
@endif

After Search

<div class="rounded-lg border border-border p-6">
    <h2 class="text-lg font-semibold mb-4">Search Results</h2>

    @if ($results->count() > 0)
        <!-- results list -->
    @else
        <x-ui.empty-state
            title="No results found"
            description="No results match your search for '{{ $query }}'."
            icon="search"
        />
    @endif
</div>

With Custom Styling

<div class="my-12 rounded-xl bg-muted/30 border border-dashed p-12">
    <x-ui.empty-state
        title="No data available"
        description="Select a date range to view data."
        icon="calendar"
        size="lg"
    />
</div>

With Description Only

<x-ui.empty-state
    title="All done!"
    description="You've completed all your tasks for today."
    icon="check-circle"
    variant="ghost"
/>

Common Use Cases

Empty Project List

<x-ui.empty-state
    title="No projects"
    description="Create your first project to get started."
    icon="folder-open"
    action-label="New Project"
    action-url="/projects/new"
/>

No Search Results

<x-ui.empty-state
    title="No results found"
    description="We couldn't find anything matching '{{ $query }}'."
    icon="search"
/>

No Notifications

<x-ui.empty-state
    title="No notifications"
    description="You're all caught up!"
    icon="bell-off"
    variant="ghost"
    size="sm"
/>

Empty Folder

<x-ui.empty-state
    title="This folder is empty"
    description="Upload files to see them here."
    icon="folder-open"
    action-label="Upload Files"
    action-url="/upload"
/>

No Favorites

<x-ui.empty-state
    title="No favorites yet"
    description="Save items to your favorites to access them quickly."
    icon="heart"
    variant="outline"
/>

Icon Suggestions

Popular HugeIcons for empty states:

Styling

The Empty State component uses Tailwind CSS utility classes:

• Container: Flexbox with centered content
• Icon: Large icon with muted color
• Title: Medium font weight for heading
• Description: Smaller text with muted color
• Button: Primary button for action (if provided)

Size Variants

Variant Styles

• default: Standard styling with icon and text
• **ghost`: Minimal styling, muted colors
• outline: Bordered variant for more emphasis

Accessibility

The Empty State component includes accessibility features:

• Semantic heading: Proper heading hierarchy for screen readers
• Descriptive text: Clear explanation of the empty state
• Action links: Clear call-to-action when available
• Icon support: Visual icons enhance understanding
• ARIA attributes: Proper labeling for assistive technologies

Notes

• The component is designed to be self-contained and informative
• Icons are rendered using the HugeIcons component system
• Action buttons use the primary button styling by default
• The ghost variant is great for less prominent empty states
• Consider adding helpful actions or guidance when appropriate
• Use descriptive titles and descriptions to guide users

Next Steps

• Explore Card component
• Learn about Button component
• View File Upload component