@zag-js/core

What is @zag-js/core?

@zag-js/core is a state management library designed to help developers build complex, interactive user interfaces with ease. It provides a set of tools to manage state machines and statecharts, making it easier to handle UI states and transitions in a predictable and maintainable way.

What are @zag-js/core's main functionalities?

State Machines

This feature allows you to define state machines with states and transitions. The example demonstrates a simple toggle machine with two states: 'inactive' and 'active'.

const { createMachine } = require('@zag-js/core');

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

console.log(toggleMachine.initialState.value); // 'inactive'

Statecharts

Statecharts extend state machines by adding hierarchical states and parallel states. The example shows a traffic light statechart with three states: 'green', 'yellow', and 'red'.

const { createMachine } = require('@zag-js/core');

const lightMachine = createMachine({
  id: 'light',
  initial: 'green',
  states: {
    green: {
      on: { TIMER: 'yellow' }
    },
    yellow: {
      on: { TIMER: 'red' }
    },
    red: {
      on: { TIMER: 'green' }
    }
  }
});

console.log(lightMachine.initialState.value); // 'green'

Contextual State

This feature allows you to manage contextual state within your state machines. The example demonstrates a counter machine with an initial count of 0 and actions to increment and decrement the count.

const { createMachine } = require('@zag-js/core');

const counterMachine = createMachine({
  id: 'counter',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: { actions: 'increment' },
        DECREMENT: { actions: 'decrement' }
      }
    }
  }
}, {
  actions: {
    increment: (context) => context.count++,
    decrement: (context) => context.count--
  }
});

console.log(counterMachine.initialState.context.count); // 0

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.

README

@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 (non-nested)
• Initial state
• Transitions (object or strings)
• Context
• Entry actions
• Exit actions
• Delayed timeout actions (basically setTimeout)
• Delayed interval actions (basically setInterval)
• Transition actions
• Boolean guard helpers
• Basic spawn helpers
• Activities (for state nodes)

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

Usage (machine):

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

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

toggleMachine.start()
console.log(toggleMachine.state.value) // => "inactive"

toggleMachine.send("TOGGLE")
console.log(toggleMachine.state.value) // => "active"

toggleMachine.send("TOGGLE")
console.log(toggleMachine.state.value) // => "inactive"

Usage (service):

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

const toggleMachine = createMachine({...})
toggleMachine.start()

toggleService.subscribe((state) => {
  console.log(state.value)
})

toggleService.send("TOGGLE")
toggleService.send("TOGGLE")
toggleService.stop()

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, which provides:

• machine.initialState: the machine's resolved initial state
• machine.start(): the function to start the machine in the specified initial state.
• machine.stop(): the function to stop the machine completely. It also cleans up all scheduled actions and timeouts.
• machine.transition(state, event): a transition function that returns the next state given the current state and event. It also performs any delayed, entry or exit side-effects.
• machine.send(event): a transition function instructs the machine to execute a transition based on the event.
• machine.onTransition(fn): a function that gets called when the machine transition function instructs the machine to execute a transition based on the event.
• machine.onChange(fn): a function that gets called when the machine's context value changes.
• machine.state: the state object that describes the machine at a specific point in time. It contains the following properties:
  • value: the current state value
  • previousValue: the previous state value
  • event: the event that triggered the transition to the current state
  • nextEvents: the list of events the machine can respond to at its current state
  • tags: the tags associated with this state
  • done: whehter the machine that reached its final state
  • context: the current context value
  • matches(...): a function used to test whether the current state matches one or more state values

The machine config has this schema:

Machine config

• id (string) - an identifier for the type of machine this is. Useful for debugging.
• context (object) - the extended state data that represents quantitative data (string, number, objects, etc) that can be modified in the machine.
• initial (string) - the key of the initial state.
• states (object) - an object mapping state names (keys) to states
• on (object) - an global mapping of event types to transitions. If specified, this event will called if the state node doesn't handle the emitted event.

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

Function syntax:

• (function) - the action function to execute. Resolves to { type: actionFn.name, exec: actionFn } and the function takes the following arguments:
  1. context (any) - the machine's current context.
  2. event (object) - the event that caused the action to be executed.

Object syntax:

• type (string) - the action type.
• exec? (function) - the action function to execute.

String syntax:

• (string) - the action type.
  • By default it resolves to { type: actionType, exec: undefined }. It can resolve to resolved function or resolved object action if the action can be looked up in the options.actions object.