or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmachine-creation.mdtype-system.mdutilities.md
tile.json

tessl/npm-zag-js--core

A minimal implementation of xstate fsm for UI machines

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@zag-js/core@1.22.x

To install, run

npx @tessl/cli install tessl/npm-zag-js--core@1.22.0

index.mddocs/

@zag-js/core

@zag-js/core is a minimal implementation of XState FSM (Finite State Machine) specifically designed for UI component state management. It provides a lightweight alternative to XState with essential features for building interactive UI components including finite states, transitions, context management, entry/exit actions, effects, guards, and activities.

Package Information

  • Package Name: @zag-js/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @zag-js/core

Core Imports

import { createMachine, setup, createGuards, MachineSchema, Service } from "@zag-js/core";

For CommonJS:

const { createMachine, setup, createGuards } = require("@zag-js/core");

Basic Usage

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

// Define machine schema
interface ToggleMachine extends MachineSchema {
  state: "inactive" | "active";
  event: { type: "TOGGLE" };
}

// Create state machine configuration
const toggleMachine = createMachine<ToggleMachine>({
  initialState: () => "inactive",
  states: {
    inactive: {
      on: { TOGGLE: { target: "active" } }
    },
    active: {
      on: { TOGGLE: { target: "inactive" } }
    }
  }
});

// toggleMachine is a configuration object that can be used with a runtime service
// (The runtime service/interpreter is provided by other packages in the Zag.js ecosystem)

Architecture

@zag-js/core is built around several key components:

  • Machine Configuration: Declarative state machine definitions with typed states, events, and context
  • Type System: Full TypeScript integration with generic schemas for compile-time safety
  • Bindable System: Reactive context and refs management with change tracking and memoization
  • Scope Management: DOM query utilities for element access and manipulation
  • Utility Functions: Property merging, memoization, and helper functions for UI component development

Capabilities

Machine Creation

Core machine creation and setup utilities for defining finite state machines with typed schemas, guards, and actions.

function createMachine<T extends MachineSchema>(config: Machine<T>): Machine<T>;

function setup<T extends MachineSchema>(): {
  guards: GuardUtilities<T>;
  createMachine: (config: Machine<T>) => Machine<T>;
  choose: (transitions: Transition<T> | Transition<T>[]) => (params: Params<T>) => T["action"][] | undefined;
};

function createGuards<T extends MachineSchema>(): GuardUtilities<T>;

Machine Creation

Type System

Comprehensive type definitions for machine schemas, services, parameters, and all core interfaces required for type-safe state machine development.

interface MachineSchema {
  props?: MachineBaseProps | undefined;
  context?: Record<string, any> | undefined;
  refs?: Record<string, any> | undefined;
  computed?: Record<string, any> | undefined;
  state?: string | undefined;
  tag?: string | undefined;
  guard?: string | undefined;
  action?: string | undefined;
  effect?: string | undefined;
  event?: ({ type: string } & Record<string, any>) | undefined;
}

interface Service<T extends MachineSchema> {
  getStatus(): MachineStatus;
  state: Bindable<T["state"]> & {
    matches(...values: T["state"][]): boolean;
    hasTag(tag: T["tag"]): boolean;
  };
  context: BindableContext<T>;
  send(event: EventType<T["event"]>): void;
  prop: PropFn<T>;
  scope: Scope;
  computed: ComputedFn<T>;
  refs: BindableRefs<T>;
  event: EventType<T["event"]> & {
    current(): EventType<T["event"]>;
    previous(): EventType<T["event"]>;
  };
}

Type System

Utility Functions

Helper functions for property merging, memoization, and scope management essential for UI component development.

function mergeProps<T extends Props>(...args: T[]): UnionToIntersection<TupleTypes<T[]>>;

function memo<TDeps extends any[], TDepArgs, TResult>(
  getDeps: (depArgs: TDepArgs) => [...TDeps],
  fn: (...args: [...TDeps]) => TResult,
  opts?: { onChange?: (result: TResult) => void }
): (depArgs: TDepArgs) => TResult;

function createScope(props: Pick<Scope, "id" | "ids" | "getRootNode">): Scope;

Utility Functions