What is the recommended way to provide an XState machine instance that depends on external props?

[inakiarroyo]

Hi everyone 👋

I'm working on integrating an XState machine (tagMachine) into a React project and want to clarify the best approach for initialising and providing an interpreter instance based on external props (e.g., tags, isNote, onTagsUpdate). My goal is to keep the interpreter:

• Stable across renders
• Recreated only when necessary (e.g., when entryType or selectedTags should be reset)
• Performance-friendly, avoiding unnecessary restarts or leaks

Ensure a stable machine instance

We want the machine to remain stable between renders, unless a meaningful prop change requires resetting the machine (e.g., switching from "note" to "message" mode)

🅰️ Alternative A: interpret + useMemo

Here I use useMemo to memoize and interpret(...).start() directly:

const tagMachineRef = useMemo(
  () =>
    interpret(
      tagMachine
        .withContext({
          entryType: isNote ? 'note' : 'message',
          selectedTags: tags ?? [],
          tags: [],
        })
        .withConfig({
          actions: {
            onUpdate: ({ selectedTags }) =>
              onTagsUpdate?.(selectedTags),
          },
        })
    ).start(),
  [tags, isNote, onTagsUpdate]
);

return (
  <TagsMachineContext.Provider value={tagMachineRef}>
    {children}
  </TagsMachineContext.Provider>
);

<TagsMachineProvider
  tags={tags}
  isNote={isNote}
  onTagsUpdate={onTagsUpdate}
/>

Possible Pros:

• Machine instance resets when inputs change
• Easy to control when it’s recreated via deeps array

Possible Cons:

• The interpreter is created during render, which might go against React best practices?
• It might not clean up old interpreters - potentially leading to memory leaks?

🅱️ Alternative B: useInterpret + key remount

Here, I use useInterpret from @xstate/react, and rely on key at the component level to force remounting the provider:

const tagMachineRef = useInterpret(tagMachine, {
  context: {
    entryType: isNote ? 'note' : 'message',
    selectedTags: tags ?? [],
    tags: [],
  },
  actions: {
    onUpdate: ({ selectedTags }) =>
      onTagsUpdate?.(selectedTags),
  },
});

return (
  <TagsMachineContext.Provider value={tagMachineRef}>
    {children}
  </TagsMachineContext.Provider>
);

const updaterKey = useMemo(
  () =>
    `${isNote ? 'note' : 'message'}-${[...(tags ?? [])].sort().join(',')}`,
  [isNote, tags]
);

<TagsMachineProvider
  tags={tags}
  isNote={isNote}
  onTagsUpdate={onTagsUpdate}
  key={updaterKey}
/>

Possible Pros:

• useInterpret starts the service in a React-safe way (in an useEffect)?
• React handles cleanup when the key changes - no manual stop needed?

Possible Cons:

• Slightly more boilerplate at the usage site
• Less granular control over when the machine is recreated (depends on key implementation)

Why I moved away from useInterpret initially

I initially used useInterpret directly, but found that it does not recreate the interpreter when the machine config/context changes. The interpreter remained the same across renders. This meant selectedTags, entryType, etc., were only set on initial mount, unless I manually sent sync events.

This led me to consider using interpret directly inside useMemo - until I realised that doing so might introduce render-phase side effects and potential memory leaks.

❓ My Questions

1. Which approach is considered more correct / idiomatic with XState v4/v5?
2. Is Alternative B with useInterpret + key the recommended way to safely recreate interpreters with new context/config?
3. Are there better alternatives I should consider?
4. Are my assumptions above about possible pros/cons of each approach correct? Especially regarding render-phase side effects and interpreter cleanup behaviour?

Any thoughts, insights, or best practices would be super appreciated 🙏

Thanks in advance!

[davidkpiano]

Before providing a detailed answer, would it be possible to migrate to XState v5? interpreter/useInterpret is part of v4, and significant improvements have been made since then in the latest version.

[inakiarroyo]

Hello @davidkpiano,

Thank you for reaching out. At the moment, our project has a strong dependency on v4, and upgrading to v5 is quite challenging. However, it would still be possible in the future. Would it be possible for you to provide two separate solutions: one compatible with v4 and another for v5? This would allow us to integrate the v4 version right away in our current setup, while also having a clear reference for how to implement it once we upgrade to v5.

[MILLERMARRU]

While you sort out the v4 vs v5 question with David, one thing worth knowing regardless of version: the input/snapshot you pass to a Provider (or useMachine/useActor) is only ever read once, on mount.

I checked useActorRef in xstate-react (packages/xstate-react/src/useActorRef.ts):

let [[currentConfig, actorRef], setCurrent] = useState(() => {
  const actorRef = createActor(logic, options)
  ...
})

That is a lazy useState initializer, React only calls it on the very first render. So whatever input/snapshot were inside options at that moment gets baked into the actor for its whole lifetime, changing those props on later renders does nothing, the actor keeps running with whatever it started with.

That matches your "stable across renders, recreated only when necessary" requirement pretty directly actually, since there is no reactive path from props to a running actor's input, the only way to force a genuinely new actor with new input is to make React unmount and remount the Provider itself, which means changing its key prop when one of the props that should reset the machine changes:

<ConnectMachineContext.Provider
  key={entryType} // change this when you want a fresh actor
  options={{ input: { portfolioConnect: portfolioConnectItem }, snapshot: portfolioConnectItem.persistedSnapshot }}
>
  ...
</ConnectMachineContext.Provider>

Leave key alone for props that should NOT reset the machine, only tie it to whatever should trigger a full reset (your note vs message mode switch, sounds like). This is a React pattern more than an XState one, but it is the actual mechanism available here either way, v4 or v5.