GuideState | Tuff Docs

Usage

Use the default guide title and description when the surrounding page already explains the context.

Loading demo...

Override copy and surface when the guide needs to stand alone inside a page or panel.

Loading demo...

Best Practices

Use TxGuideState for first-use help, setup prompts, or “start here” panels. Use TxEmptyState variant="no-data" or dedicated wrappers for data absence.
Keep guide copy action-oriented. The title should name the next meaningful step, not just describe an empty screen.
Prefer surface="card" when the guide sits among other dashboard content; keep plain inside already framed panels.
Pass slot content only when the preset illustration or generated buttons cannot express the target action.
Keep action labels specific, such as “Create workspace” or “Connect account”, rather than generic “Continue”.

TxGuideState accepts GuideStateProps, defined as Omit<EmptyStateProps, 'variant'>. It forwards those props to TxEmptyState and injects variant="guide". For the complete base contract, see EmptyState.

Props

Prop	Type	Default	Description
`title`	`string`	`'Start here'`	Overrides the guide preset title inherited from `TxEmptyState`.
`description`	`string`	`'Follow the steps to get started.'`	Overrides the guide preset description.
`icon`	`TxIconSource \| string \| null`	guide illustration	Replaces the preset guide illustration or hides it when set to `null`.
`iconSize`	`number`	size preset	Custom icon/spinner size in pixels.
`layout`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout forwarded to `TxEmptyState`.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Alignment forwarded to `TxEmptyState`.
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Visual scale.
`surface`	`'plain' \| 'card'`	`'plain'`	Adds the empty-state card surface when set to `card`.
`primaryAction`	`EmptyStateAction`	-	Primary generated action. Emits `primary` from `TxEmptyState`.
`secondaryAction`	`EmptyStateAction`	-	Secondary generated action. Emits `secondary` from `TxEmptyState`.
`actionSize`	`TxButtonProps['size']`	`'small'`	Default size for generated action buttons.
`loading`	`boolean`	`false`	Shows the spinner when no icon slot or icon prop is supplied.

Events

Event	Payload	Description
`primary`	`()`	Forwarded from the generated primary action button.
`secondary`	`()`	Forwarded from the generated secondary action button.

Slots

Slot	Props	Description
`icon`	-	Forwarded to `TxEmptyState` and replaces the guide illustration.
`title`	-	Forwarded title content.
`description`	-	Forwarded description content.
`actions`	-	Replaces generated primary/secondary buttons.

Overview

TxGuideState always renders TxEmptyState with variant="guide"; callers cannot change the variant through props.
Every other EmptyStateProps field is forwarded unchanged.
icon, title, description, and actions slots are forwarded only when provided.
Generated action buttons and emitted primary/secondary events come from TxEmptyState.
The component has no wrapper DOM of its own; styling and semantics are those of TxEmptyState.

Technologies

Accessibility note: TxGuideState adds no wrapper DOM or independent semantics; accessible structure, headings, action labels, and generated button events come directly from TxEmptyState.
Verified coverage: guide-state.test.ts verifies fixed variant="guide", prop forwarding to TxEmptyState, named slot forwarding, and plugin installation under TxGuideState.
Component source: packages/tuffex/packages/components/src/guide-state/src/TxGuideState.vue.
Types: packages/tuffex/packages/components/src/guide-state/src/types.ts exports GuideStateProps as Omit<EmptyStateProps, 'variant'>.
Export alias: packages/tuffex/packages/components/src/guide-state/index.ts exports TxGuideState, GuideStateProps, and TxGuideStateInstance.
Coverage: packages/tuffex/packages/components/src/guide-state/__tests__/guide-state.test.ts verifies variant locking, prop/slot forwarding, and install registration.

查看源码

packages/tuffex/packages/components/src/guide-state/index.ts