Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

EmptyState

A composable presentation layout for empty results and first-use states.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

No archived projects

Projects you archive will appear here.

Install

Run in your project
bunx --bun @getweini/cli@latest add empty-state

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

No messages

Start a conversation with your team.

Vue
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import EmptyState from './components/ui/empty-state/EmptyState.vue'
import EmptyStateActions from './components/ui/empty-state/EmptyStateActions.vue'
import EmptyStateDescription from './components/ui/empty-state/EmptyStateDescription.vue'
import EmptyStateIcon from './components/ui/empty-state/EmptyStateIcon.vue'
import EmptyStateTitle from './components/ui/empty-state/EmptyStateTitle.vue'
</script>

<template>
  <EmptyState as="section" aria-labelledby="empty-title" aria-describedby="empty-description">
    <EmptyStateIcon><span>□</span></EmptyStateIcon>
    <EmptyStateTitle id="empty-title">No messages</EmptyStateTitle>
    <EmptyStateDescription id="empty-description">
      Start a conversation with your team.
    </EmptyStateDescription>
    <EmptyStateActions><Button>Compose</Button></EmptyStateActions>
  </EmptyState>
</template>

The component provides presentation only and adds no copy, focus stops, or live-region behavior. The icon region is hidden from assistive technology; associate semantic sections with their title and description.

When to use it

First-use guidance

Explain what a new workspace can do and offer a first action.

No search results

Explain that a query has no matches and suggest a useful recovery path.

More examples

New workspace

Connect the section to its title and description.

New workspace
<script setup lang="ts">
import Button from './components/ui/button/Button.vue'
import EmptyState from './components/ui/empty-state/EmptyState.vue'
import EmptyStateActions from './components/ui/empty-state/EmptyStateActions.vue'
import EmptyStateDescription from './components/ui/empty-state/EmptyStateDescription.vue'
import EmptyStateTitle from './components/ui/empty-state/EmptyStateTitle.vue'
</script>

<template>
  <EmptyState as="section" aria-labelledby="workspace-empty" aria-describedby="workspace-hint">
    <EmptyStateTitle id="workspace-empty">No projects yet</EmptyStateTitle>
    <EmptyStateDescription id="workspace-hint">
      Create a project to organize your team’s work.
    </EmptyStateDescription>
    <EmptyStateActions><Button>Create project</Button></EmptyStateActions>
  </EmptyState>
</template>

Search with no matches

An aligned empty state can sit naturally in a results column.

Search with no matches
<script setup lang="ts">
import EmptyState from './components/ui/empty-state/EmptyState.vue'
import EmptyStateDescription from './components/ui/empty-state/EmptyStateDescription.vue'
import EmptyStateTitle from './components/ui/empty-state/EmptyStateTitle.vue'
</script>

<template>
  <EmptyState align="start">
    <EmptyStateTitle>No matching files</EmptyStateTitle>
    <EmptyStateDescription>Try a shorter name or clear your filters.</EmptyStateDescription>
  </EmptyState>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

EmptyState

Complete API for EmptyState
NameType or signatureDefaultWhat it does
asprop"div" | "section" | "article" | undefined"div"Choose the HTML element or Vue component used for this control.
alignprop"start" | "center" | undefined"center"Choose how content aligns within its container.
defaultslot() => unknownRequiredContent shown inside EmptyState.

EmptyStateActions

Complete API for EmptyStateActions
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside EmptyStateActions.

EmptyStateDescription

Complete API for EmptyStateDescription
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside EmptyStateDescription.

EmptyStateIcon

Complete API for EmptyStateIcon
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside EmptyStateIcon.

EmptyStateTitle

Complete API for EmptyStateTitle
NameType or signatureDefaultWhat it does
asprop"h2" | "h3" | "h4" | "h5" | "h6" | undefined"h3"Choose the HTML element or Vue component used for this control.
defaultslot() => unknownRequiredContent shown inside EmptyStateTitle.
Public type definitions
Public types
// packages/frameworks/vue/components/empty-state/types.ts
// ------- TYPES -------

export interface EmptyStateProps {
  as?: 'div' | 'section' | 'article'
  align?: 'start' | 'center'
}

export interface EmptyStateTitleProps {
  as?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
}

Implementation notes

  • Write a title that states what is empty, then explain a useful next step.
  • Use a real action when recovery is possible; avoid a button that repeats the same failed search.

Accessibility and localization

  • The icon area is decorative; put meaningful information in title and description text.

Source contract and editing guidance