Error state

new

Empty's anatomy for a failure, with an error icon, a title, a description and a place for Retry, announced as an alert.

Demo

Open Props in the corner of the example to try size.

Installation

Usage

<script setup lang="ts">
import { RotateCw } from '@lucide/vue'

import { Button } from '@/components/ui/button'
import {
  ErrorState,
  ErrorStateActions,
  ErrorStateDescription,
  ErrorStateHeader,
  ErrorStateMedia,
  ErrorStateTitle,
} from '@/components/ui/error-state'
</script>

<template>
  <ErrorState>
    <ErrorStateHeader>
      <ErrorStateMedia />
      <ErrorStateTitle>Couldn't load projects</ErrorStateTitle>
      <ErrorStateDescription>Try again in a moment.</ErrorStateDescription>
    </ErrorStateHeader>
    <ErrorStateActions>
      <Button variant="outline" color="neutral" @click="refetch">
        <RotateCw data-icon="inline-start" />
        Retry
      </Button>
    </ErrorStateActions>
  </ErrorState>
</template>

The parts are Empty's, so the layout, the surface (none) and size work the same. Three things differ: the root is an alert, ErrorStateMedia shows a circled exclamation mark in the destructive colour when you give it nothing, and the actions part is named for what goes there. Put your own icon or image in ErrorStateMedia to replace the default.

There is no Retry part and no retry event: the button is yours, so it can show a spinner, disable itself or do something else entirely.

Examples

In a data table

A DataTable draws its error slot where the empty message goes.

Loading, empty and error states
InvoiceCustomerAmount
INV-1Ada Lovelace$250
INV-2Grace Hopper$150
INV-3Linus Torvalds$350

In a data tree

A DataTree draws its error slot inside its frame, next to the tree.

Data tree states
  • Inbox
  • Archive

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
error-statedata-sizeThe root, with role="alert". The parts read data-size through the group/empty class.
error-state-header—The media, title and description.
error-state-media—The icon or image.
error-state-title—The heading, an h3 unless as says otherwise.
error-state-description—The muted paragraph.
error-state-actions—The actions.

Accessibility

  • The root is role="alert", so a screen reader reads it out as soon as it appears.
  • An error that is on the page from the start, or one the user went looking for, needn't interrupt: pass role="status" or role="none".

Changelog

  1. registry 0.21.0

    a45ad9f — New ErrorState: Empty's anatomy for a failure. Six parts (ErrorState, ErrorStateHeader, ErrorStateMedia, ErrorStateTitle, ErrorStateDescription, ErrorStateActions) over the Empty parts, role="alert" on the root unless you pass another role, a circled exclamation mark in the destructive colour as the default media, and size from xs to xl as on Empty.