or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-utilities.mdcore-hooks.mdindex.mdutility-functions.md
tile.json

tessl/npm-xstate--react

React hooks and utilities for integrating XState finite state machines and statecharts into React applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@xstate/react@6.0.x

To install, run

npx @tessl/cli install tessl/npm-xstate--react@6.0.0

index.mddocs/

@xstate/react

@xstate/react provides React-specific utilities and hooks for integrating XState finite state machines and statecharts into React applications. It offers comprehensive state management capabilities with automatic re-rendering, TypeScript integration, and SSR compatibility.

Package Information

  • Package Name: @xstate/react
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install xstate @xstate/react

Note: XState is a peer dependency and must be installed separately.

Core Imports

import { useActor, useActorRef, useSelector, createActorContext, shallowEqual } from "@xstate/react";

For CommonJS:

const { useActor, useActorRef, useSelector, createActorContext, shallowEqual } = require("@xstate/react");

Basic Usage

import { useActor } from "@xstate/react";
import { createMachine } from "xstate";

const toggleMachine = createMachine({
  id: "toggle",
  initial: "inactive",
  states: {
    inactive: { on: { TOGGLE: "active" } },
    active: { on: { TOGGLE: "inactive" } }
  }
});

function Toggle() {
  const [state, send] = useActor(toggleMachine);

  return (
    <button onClick={() => send({ type: "TOGGLE" })}>
      {state.value === "inactive" ? "Click to activate" : "Active! Click to deactivate"}
    </button>
  );
}

Architecture

@xstate/react is built around several key components:

  • React Hooks: Core hooks (useActor, useActorRef, useSelector) that manage XState actors within React's lifecycle
  • Context System: createActorContext for sharing actors across component trees via React Context
  • State Synchronization: Integration with React's useSyncExternalStore for optimal re-rendering
  • SSR Compatibility: Isomorphic layout effects for server-side rendering support
  • Type Safety: Full TypeScript integration preserving XState's type system in React components

Capabilities

Core State Management Hooks

Primary hooks for managing XState actors and subscribing to state changes with automatic React integration.

function useActor<TLogic extends AnyActorLogic>(
  logic: TLogic,
  options?: ActorOptions<TLogic>
): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];

function useActorRef<TLogic extends AnyActorLogic>(
  machine: TLogic,
  options?: ActorOptions<TLogic>,
  observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)
): Actor<TLogic>;

function useSelector<TActor, T>(
  actor: TActor,
  selector: (snapshot: TActor extends { getSnapshot(): infer TSnapshot } ? TSnapshot : undefined) => T,
  compare?: (a: T, b: T) => boolean
): T;

Core Hooks

Context and Provider Utilities

Factory function for creating React context providers and hooks for sharing XState actors across component trees.

interface ActorContextReturn<TLogic extends AnyActorLogic> {
  useSelector: <T>(
    selector: (snapshot: SnapshotFrom<TLogic>) => T,
    compare?: (a: T, b: T) => boolean
  ) => T;
  useActorRef: () => Actor<TLogic>;
  Provider: React.ComponentType<{
    children: React.ReactNode;
    options?: ActorOptions<TLogic>;
    logic?: TLogic;
  }>;
}

function createActorContext<TLogic extends AnyActorLogic>(
  actorLogic: TLogic,
  actorOptions?: ActorOptions<TLogic>
): ActorContextReturn<TLogic>;

Context Utilities

Utility Functions

Helper functions for common operations and compatibility.

function shallowEqual(objA: any, objB: any): boolean;

// Deprecated - use useActor instead
function useMachine<TMachine extends AnyStateMachine>(
  machine: TMachine,
  options?: ActorOptions<TMachine>
): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];

Utility Functions

Common Types

The following types are commonly used throughout the @xstate/react API:

// From XState - these types are re-exported or used in signatures
type AnyActorLogic = any; // XState's actor logic type
type Actor<TLogic> = any; // XState's actor reference type
type SnapshotFrom<TLogic> = any; // Extracted snapshot type from logic
type ActorOptions<TLogic> = any; // XState's actor configuration options
type Observer<T> = any; // XState's observer interface
type AnyStateMachine = any; // XState's state machine type
type StateFrom<TMachine> = any; // Extracted state type from machine

// React integration types
interface ReactNode {} // React's node type for children
interface ComponentType<P> {} // React's component type

Note: These types are defined by XState and React. Refer to their respective documentation for complete type definitions.