---
title: "GuideState"
description: "A state view that guides users through initial setup."
category: Status
status: beta
since: 0.3.4
tags: [empty, state, guide, onboarding]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
Use the preset title and description when the surrounding page already explains the context.
::::TuffDemoWrapper{demo="GuideStateBasicDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGuideState
      :primary-action="{ label: 'Get Started', type: 'primary' }"
      :secondary-action="{ label: 'Learn More' }"
    />
  </template>
---
::::

### Custom Copy
When the guide stands alone in a page or panel, override the copy and set `surface="card"`.
::::TuffDemoWrapper{demo="GuideStateCustomDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGuideState
      title="Create your first workspace"
      description="Workspaces help you organize projects, members, and automations. Follow the guide to finish setup."
      surface="card"
      size="large"
      :primary-action="{ label: 'Create Workspace', type: 'primary' }"
    />
  </template>
---
::::

### Best Practices

- Use it for first use, setup prompts, or "start here" panels; use `TxNoData` for missing data.
- Make the title name the next step, not describe an empty screen.
- Use `surface="card"` among dashboard content; keep `plain` inside an already framed panel.
- Keep action labels specific, such as "Create workspace" or "Connect account", not "Continue".
- Pass slots only when the preset illustration or generated buttons cannot express the target action.

## API Reference

Takes every [TxEmptyState](./empty-state.en.mdc) prop, event, and slot except `variant`, which is fixed to `guide`.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `'Start here'` | Overrides the preset title. |
| `description` | `string` | `'Follow the steps to get started.'` | Overrides the preset description. |
| `icon` | `TxIconSource \| string \| null` | guide illustration | Replaces the illustration; `null` hides the icon area. |
| `iconSize` | `number` | size preset | Icon or spinner size in px. |
| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction. |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Content alignment. |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Visual size. |
| `surface` | `'plain' \| 'card'` | `'plain'` | `card` adds a card surface. |
| `primaryAction` | `EmptyStateAction` | - | Generated primary action; emits `primary`. |
| `secondaryAction` | `EmptyStateAction` | - | Generated secondary action; emits `secondary`. |
| `actionSize` | `TxButtonProps['size']` | `'sm'` | Default size of the generated buttons. |
| `loading` | `boolean` | `false` | Shows a spinner when there is no `icon` slot or prop. |

### Events

| Event | Payload | Description |
|------|---------|-------------|
| `primary` | `()` | Fires when the generated primary button is clicked. |
| `secondary` | `()` | Fires when the generated secondary button is clicked. |

### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `icon` | - | Replaces the guide illustration. |
| `title` | - | Replaces the title. |
| `description` | - | Replaces the description. |
| `actions` | - | Replaces the generated primary and secondary buttons. |

## Technologies

- Source: `packages/tuffex/packages/components/src/guide-state/`.

<TuffDocSourceLink />