model-state-with-xstate

Model State with XState

Recipes for common XState v5 patterns. For core rules (createMachine vs setup, types), see the xstate instruction file which auto-loads for *.machine.ts files.

React Integration

Provider pattern — create actor once, share via context

import { createActorContext } from "@xstate/react"

const MyMachineContext = createActorContext(myMachine)

// Provider
function App() {
  return (
    <MyMachineContext.Provider>
      <MyFeature />
    </MyMachineContext.Provider>
  )
}

// Consumer — select minimum slice
function MyFeature() {
  const isLoading = MyMachineContext.useSelector((s) => s.matches("loading"))
  const data = MyMachineContext.useSelector((s) => s.context.data)
  const actorRef = MyMachineContext.useActorRef()

  return <button onClick={() => actorRef.send({ type: "RETRY" })}>Retry</button>
}

Manual approach (without createActorContext)

import { useActorRef, useSelector } from "@xstate/react"

function MyFeature() {
  const actorRef = useActorRef(myMachine)
  const isLoading = useSelector(actorRef, (s) => s.matches("loading"))
  const error = useSelector(actorRef, (s) => s.context.error)

  actorRef.send({ type: "RETRY" })
}

Expose actorRef via React context so consumers don't recreate the machine.

Actor Recipes

fromPromise — async operations

const fetchDataActor = fromPromise(async ({ input }: { input: { id: string } }) => {
  const response = await fetch(`/api/items/${input.id}`)
  if (!response.ok) throw new Error("Fetch failed")
  return response.json() as Promise<Item>
})

fromCallback — event-based / DOM listeners

const resizeActor = fromCallback(({ sendBack }) => {
  const handler = () => sendBack({ type: "RESIZE", width: window.innerWidth })
  window.addEventListener("resize", handler)
  return () => window.removeEventListener("resize", handler)
})

Pass runtime dependencies via input, never close over mutable state:

invoke: {
  src: "fetchData",
  input: ({ context }) => ({ id: context.itemId }),
}