Kotick
<Kotick /> is a development overlay for React apps that use state machines. It lists each machine that runs on the page and all of its states, also the states the UI never went to. Click a state to show it in the real app, with real layout and data. You do not have to click through the flow, slow down the network, or force an API error to get there. kotick supports useReducer machines through kotick/reducer, and XState v5 machines through kotick/xstate.
How it works
A checkout page with the real overlay docked beside it. The panel lists the checkout machine and all of its states, also the states that the page has not gone to. Select useReducer or XState to see the same checkout with each adapter.
- Click the bubble to open the panel. Select checkout-reducer, then error. The checkout shows Card declined. You did not have to type a declined card and pay to get there.
- Click Retry. The machine does not get the event. Scroll down the panel to Blocked events. It lists RETRY.
- Select error again to release the preview. The checkout shows the real state again.
A preview needs context. The marks after each leaf in the panel show where it comes from:
| Source | Mark | What it is |
|---|---|---|
| Recorded | R | The last context that the real machine had in this state. It stays in sessionStorage, so it is still there after a reload. |
| Fixture | F | Context that you wrote with defineFixtures(). |
| None | – | The state is greyed out, and you cannot preview it, because the live state object fits only the state that the machine is in. |
This demo has a fixture for each state, so each state has data for a preview.
This site builds kotick in development mode for the demo. In your production build, <Kotick /> renders nothing.
During a preview, your components get the selected state in place of the real one, and the real machine continues to run. With kotick/reducer, useMachineReducer returns it. With kotick/xstate, they read the state from a proxy of the actor. For the adapters, the registry and the overlay, see How kotick works.
Why kotick
| Benefit | What it means |
|---|---|
| In context | Previews render in the running app, not in a separate story or sandbox. |
| Safe | A preview changes only what components see. The real machine keeps running, and events that the UI sends during a preview are blocked and logged. |
| Realistic data | Previews use context recorded from earlier visits, context you write as fixtures, or the live context. The panel shows which one it uses. |
| Hidden | <Kotick /> renders nothing in a production build, and the registry and the panel are removed from the bundle. |
Adapters
kotick has an adapter for each kind of machine, and neither is the default. An app can use one of them or both. Choose an adapter compares them.
Reducer machines
If a component keeps a union of states in useReducer, declare the reducer as a machine with defineReducerMachine, and call useMachineReducer instead of useReducer. The app does not need XState. Refer to useReducer.
XState machines
The adapter needs two changes to your app. Mount <Kotick />, and import the hooks from kotick/xstate instead of @xstate/react. Refer to XState.