@zag-js/core

@zag-js/core

This package contains a minimal implementation of XState FSM for finite state machines with addition of extra features we need for our components.

Features

• Finite states with optional nested (hierarchical) states
• Initial state
• Transitions (object or strings)
• Context
• Entry actions
• Exit actions
• Transition actions
• Effects
• Boolean guard helpers (and, or, not)

Note: The core package is intentionally minimal. It doesn't include delayed transitions, interval scheduling, spawn helpers, or activities. Use actions/effects to perform side effects.

To better understand the state machines, we strongly recommend going though the xstate docs and videos. It'll give you the foundations you need.

Quick start

Installation

npm i @zag-js/core
# or
yarn add @zag-js/core

Usage (machine):

import { createMachine } from "@zag-js/core"

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

Usage (service via adapter):

import { createMachine } from "@zag-js/core"
import { VanillaMachine } from "@zag-js/vanilla"

const machine = createMachine({
  initialState() {
    return "inactive"
  },
  states: {
    inactive: { on: { TOGGLE: "active" } },
    active: { on: { TOGGLE: "inactive" } },
  },
})

const service = new VanillaMachine(machine)
service.start()

service.subscribe(() => {
  console.log(service.state.get())
})

service.send({ type: "TOGGLE" })
service.send({ type: "TOGGLE" })
service.stop()

Nested states (dot notation)

import { createMachine } from "@zag-js/core"

const machine = createMachine({
  initialState() {
    return "dialog"
  },
  states: {
    dialog: {
      tags: ["overlay"],
      initial: "closed",
      states: {
        closed: { on: { OPEN: { target: "dialog.open" } } },
        open: { on: { CLOSE: { target: "dialog.closed" } } },
      },
      // parent-level transitions still work
      on: { RESET: { target: "dialog.closed" } },
    },
  },
})

// service.state.matches("dialog.open") === true when nested state is active

State IDs and #id targets

Use id on a state node when you want to target it explicitly from anywhere in the machine.

import { createMachine } from "@zag-js/core"

const machine = createMachine({
  initialState() {
    return "dialog"
  },
  states: {
    dialog: {
      initial: "open",
      states: {
        focused: {
          id: "dialogFocused",
        },
        open: {
          initial: "idle",
          states: {
            idle: {
              on: {
                CLOSE: { target: "#dialogFocused" },
              },
            },
          },
        },
      },
    },
  },
})

Notes:

• #id targets resolve by state node id (XState-style).
• State IDs must be unique within a machine.

API

createMachine(config, options)

Creates a new finite state machine from the config.

Argument	Type	Description
config	object (see below)	The config object for creating the machine.
options	object (see below)	The optional options object.

Returns:

A machine definition object consumed by framework adapters (React, Solid, Svelte, Vue, Preact, Vanilla) to create a runtime service.

The machine config has this schema:

Machine config

• initialState (function) - returns the machine's initial state value.
• states (object) - mapping of state names to state configs. Supports nested states and initial for child states.
• on (object) - optional global transitions available from any state.
• context (function) - returns bindable context fields.
• computed (object) - derived values based on context, props, refs.
• entry / exit / effects - root-level actions/effects.
• implementations (object) - lookup tables for actions, guards, effects.

State config

• on (object) - an object mapping event types (keys) to transitions

Transition config

String syntax:

• (string) - the state name to transition to.
  • Same as { target: stateName }

Object syntax:

• target (string) - the state name to transition to.
• actions (Action | Action[]) - the action(s) to execute when this transition is taken.
• guard (Guard) - the condition (predicate function) to test. If it returns true, the transition will be taken.

Machine options

• actions? (object) - a lookup object for your string actions.
• guards? (object) - a lookup object for your string guards specified as guard in the machine.
• activities? (object) - a lookup object for your string activities.
• delays? (object) - a lookup object for your string delays used in after and every config.

Action config

The action function to execute while transitioning from one state to another. It takes the following arguments:

• context (any) - the machine's current context.
• event (object) - the event that caused the action to be executed.

Similar packages

Other packages similar to @zag-js/core

xstate

XState is a popular library for managing state machines and statecharts in JavaScript. It offers a rich set of features for defining and interpreting state machines, and it integrates well with various frameworks like React, Vue, and Angular. Compared to @zag-js/core, XState has a larger community and more extensive documentation.

robot3

Robot3 is a lightweight state machine library for JavaScript. It focuses on simplicity and ease of use, making it a good choice for smaller projects or developers who prefer a minimalistic approach. While it may not have as many features as @zag-js/core, it provides a straightforward API for managing state machines.

redux

Redux is a widely-used state management library for JavaScript applications, particularly in the React ecosystem. While it is not specifically designed for state machines, it can be used to manage complex state logic through middleware and reducers. Compared to @zag-js/core, Redux offers a more general-purpose approach to state management.