0
# @zag-js/core
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @zag-js/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @zag-js/core`
10

11
## Core Imports
12

13
```typescript
14
import { createMachine, setup, createGuards, MachineSchema, Service } from "@zag-js/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createMachine, setup, createGuards } = require("@zag-js/core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createMachine, MachineSchema } from "@zag-js/core";
27

28
// Define machine schema
29
interface ToggleMachine extends MachineSchema {
30
  state: "inactive" | "active";
31
  event: { type: "TOGGLE" };
32
}
33

34
// Create state machine configuration
35
const toggleMachine = createMachine<ToggleMachine>({
36
  initialState: () => "inactive",
37
  states: {
38
    inactive: {
39
      on: { TOGGLE: { target: "active" } }
40
    },
41
    active: {
42
      on: { TOGGLE: { target: "inactive" } }
43
    }
44
  }
45
});
46

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

51
## Architecture
52

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

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

61
## Capabilities
62

63
### Machine Creation
64

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

67
```typescript { .api }
68
function createMachine<T extends MachineSchema>(config: Machine<T>): Machine<T>;
69

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

76
function createGuards<T extends MachineSchema>(): GuardUtilities<T>;
77
```
78

79
[Machine Creation](./machine-creation.md)
80

81
### Type System
82

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

85
```typescript { .api }
86
interface MachineSchema {
87
  props?: MachineBaseProps | undefined;
88
  context?: Record<string, any> | undefined;
89
  refs?: Record<string, any> | undefined;
90
  computed?: Record<string, any> | undefined;
91
  state?: string | undefined;
92
  tag?: string | undefined;
93
  guard?: string | undefined;
94
  action?: string | undefined;
95
  effect?: string | undefined;
96
  event?: ({ type: string } & Record<string, any>) | undefined;
97
}
98

99
interface Service<T extends MachineSchema> {
100
  getStatus(): MachineStatus;
101
  state: Bindable<T["state"]> & {
102
    matches(...values: T["state"][]): boolean;
103
    hasTag(tag: T["tag"]): boolean;
104
  };
105
  context: BindableContext<T>;
106
  send(event: EventType<T["event"]>): void;
107
  prop: PropFn<T>;
108
  scope: Scope;
109
  computed: ComputedFn<T>;
110
  refs: BindableRefs<T>;
111
  event: EventType<T["event"]> & {
112
    current(): EventType<T["event"]>;
113
    previous(): EventType<T["event"]>;
114
  };
115
}
116
```
117

118
[Type System](./type-system.md)
119

120
### Utility Functions
121

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

124
```typescript { .api }
125
function mergeProps<T extends Props>(...args: T[]): UnionToIntersection<TupleTypes<T[]>>;
126

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

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

136
[Utility Functions](./utilities.md)