Statefully Documentation

Defining States

States are the foundation of your state machine. Each state represents a distinct condition or mode your system can be in.

Basic States

Each line in your spec defines a state. State names can contain letters, numbers, spaces, and hyphens.

Login Screen
Dashboard
Settings
User Profile

Initial State

Mark the starting state with an asterisk *. When someone opens your state machine, this is where they start.

Login Screen *
Dashboard
Settings

Tip

Put the asterisk at the end of the state name, separated by a space.

State Naming Conventions

Good state names describe what the user sees or what the system is doing:

GOOD

  • Loading
  • Form - Step 1
  • Payment Processing
  • Error - Invalid Input

AVOID

  • state1
  • temp
  • x
  • foo

Duplicate State Names

You can have multiple states with the same name if they're in different parts of your hierarchy. Statefully generates unique IDs based on the path.

Form
	Step 1
		Error
			fix -> Step 1
	Step 2
		Error
			fix -> Step 2

Note

Both Error states are valid. When linking to them, you can use the full path like Step 1/Error if needed.