npmpackage.info

xstate

Actor-based state management & orchestration for complex app logic.

5.19.0

27,238

MIT

TypeScript

309,018,023 5.3

Installations

npm install xstate

Score

99.5

Supply Chain

100

Quality

92.7

Maintenance

100

Vulnerability

100

License

Pull Requests

Open

46

Total

2,319

Closed

381

Merged

1,892

Issues

Open

89

Total

1,351

Closed

1,262

Releases

383

@xstate/vue@4.0.0

Published on 12 Nov 2024

@xstate/store@2.6.1

Published on 12 Nov 2024

@xstate/svelte@4.0.0

Published on 12 Nov 2024

xstate@5.19.0

Published on 12 Nov 2024

@xstate/solid@1.0.0

Published on 12 Nov 2024

@xstate/react@5.0.0

Published on 12 Nov 2024

View all 383 releases

Developer

statelyai

Developer Guide

BETA

Module System

CommonJS, ESM

Min. Node Version

Typescript Support

Yes

Node Version

20.18.0

NPM Version

10.8.2 Statistics

27,238 Stars

6,728 Commits

1,255 Forks

192 Watching

274 Branches

337 Contributors

Updated on 28 Nov 2024

Languages

TypeScript (97.71%)

Vue (0.82%)

JavaScript (0.67%)

Svelte (0.45%)

CSS (0.27%)

HTML (0.08%)

Total Downloads

Cumulative downloads

Total Downloads

309,018,023

Last day

-9.2%

301,246

Compared to previous day

Last week

0.7%

1,684,687

Compared to previous week

Last month

7,112,546

Compared to previous month

Last year

19.3%

80,816,084

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

@scion-scxml/test-framework ajv pkg-up rxjs xml-js @xstate-repo/jest-utils

Versions

Actor-based state management & orchestration for complex app logic. → Documentation

XState is a state management and orchestration solution for JavaScript and TypeScript apps. It has zero dependencies, and is useful for frontend and backend application logic.

It uses event-driven programming, state machines, statecharts, and the actor model to handle complex logic in predictable, robust, and visual ways. XState provides a powerful and flexible way to manage application and workflow state by allowing developers to model logic as actors and state machines.

✨ Create state machines visually in Stately Studio → state.new

📖 Read the documentation

➡️ Create state machines with the Stately Editor

🖥 Download our VS Code extension

📑 Inspired by the SCXML specification

💬 Chat on the Stately Discord Community

✍️ Browse through the many XState examples

Templates

Get started by forking one of these templates on CodeSandbox:

Template
🤖 XState Template (CodeSandbox)	XState v5 TypeScript No framework
⚛️ XState + React Template (CodeSandbox)	React XState v5 TypeScript
💚 XState + Vue Template (CodeSandbox)	Vue XState v5 TypeScript
🧡 XState + Svelte Template (CodeSandbox)	Svelte XState v5 TypeScript

Super quick start

1npm install xstate

1import { createMachine, createActor, assign } from 'xstate';
2
3// State machine
4const toggleMachine = createMachine({
5  id: 'toggle',
6  initial: 'inactive',
7  context: {
8    count: 0
9  },
10  states: {
11    inactive: {
12      on: {
13        TOGGLE: { target: 'active' }
14      }
15    },
16    active: {
17      entry: assign({ count: ({ context }) => context.count + 1 }),
18      on: {
19        TOGGLE: { target: 'inactive' }
20      }
21    }
22  }
23});
24
25// Actor (instance of the machine logic, like a store)
26const toggleActor = createActor(toggleMachine);
27toggleActor.subscribe((state) => console.log(state.value, state.context));
28toggleActor.start();
29// => logs 'inactive', { count: 0 }
30
31toggleActor.send({ type: 'TOGGLE' });
32// => logs 'active', { count: 1 }
33
34toggleActor.send({ type: 'TOGGLE' });
35// => logs 'inactive', { count: 1 }

Stately Studio

Visually create, edit, and collaborate on state machines
Export to many formats, including XState v5
Test path & documentation autogeneration
Deploy to Stately Sky
Generate & modify machines with Stately AI

state.new

Why?

Statecharts are a formalism for modeling stateful, reactive systems. This is useful for declaratively describing the behavior of your application, from the individual components to the overall application logic.

Read 📽 the slides (🎥 video) or check out these resources for learning about the importance of finite state machines and statecharts in user interfaces:

Statecharts - A Visual Formalism for Complex Systems by David Harel
The World of Statecharts by Erik Mogensen

Packages

Package	Description
🤖 `xstate`	Core finite state machine and statecharts library + interpreter
📉 `@xstate/graph`	Graph traversal and model-based testing utilities using XState
⚛️ `@xstate/react`	React hooks and utilities for using XState in React applications
💚 `@xstate/vue`	Vue composition functions and utilities for using XState in Vue applications
🎷 `@xstate/svelte`	Svelte utilities for using XState in Svelte applications
🥏 `@xstate/solid`	Solid hooks and utilities for using XState in Solid applications
🔍 `@statelyai/inspect`	Inspection utilities for XState
🏪 `@xstate/store`	Small library for simple state management

Finite State Machines

Code Statechart

1import { createMachine, createActor } from 'xstate';
2
3const lightMachine = createMachine({
4  id: 'light',
5  initial: 'green',
6  states: {
7    green: {
8      on: {
9        TIMER: 'yellow'
10      }
11    },
12    yellow: {
13      on: {
14        TIMER: 'red'
15      }
16    },
17    red: {
18      on: {
19        TIMER: 'green'
20      }
21    }
22  }
23});
24
25const actor = createActor(lightMachine);
26
27actor.subscribe((state) => {
28  console.log(state.value);
29});
30
31actor.start();
32// logs 'green'
33
34actor.send({ type: 'TIMER' });
35// logs 'yellow'

Code	Statechart

Open in Stately Studio

Hierarchical (Nested) State Machines

Code Statechart

Code	Statechart
1import { createMachine, createActor } from 'xstate'; 2 3const pedestrianStates = { 4 initial: 'walk', 5 states: { 6 walk: { 7 on: { 8 PED_TIMER: 'wait' 9 } 10 }, 11 wait: { 12 on: { 13 PED_TIMER: 'stop' 14 } 15 }, 16 stop: {} 17 } 18}; 19 20const lightMachine = createMachine({ 21 id: 'light', 22 initial: 'green', 23 states: { 24 green: { 25 on: { 26 TIMER: 'yellow' 27 } 28 }, 29 yellow: { 30 on: { 31 TIMER: 'red' 32 } 33 }, 34 red: { 35 on: { 36 TIMER: 'green' 37 }, 38 ...pedestrianStates 39 } 40 } 41}); 42 43const actor = createActor(lightMachine); 44 45actor.subscribe((state) => { 46 console.log(state.value); 47}); 48 49actor.start(); 50// logs 'green' 51 52actor.send({ type: 'TIMER' }); 53// logs 'yellow' 54 55actor.send({ type: 'TIMER' }); 56// logs { red: 'walk' } 57 58actor.send({ type: 'PED_TIMER' }); 59// logs { red: 'wait' }	Open in Stately Studio

1import { createMachine, createActor } from 'xstate';
2
3const pedestrianStates = {
4  initial: 'walk',
5  states: {
6    walk: {
7      on: {
8        PED_TIMER: 'wait'
9      }
10    },
11    wait: {
12      on: {
13        PED_TIMER: 'stop'
14      }
15    },
16    stop: {}
17  }
18};
19
20const lightMachine = createMachine({
21  id: 'light',
22  initial: 'green',
23  states: {
24    green: {
25      on: {
26        TIMER: 'yellow'
27      }
28    },
29    yellow: {
30      on: {
31        TIMER: 'red'
32      }
33    },
34    red: {
35      on: {
36        TIMER: 'green'
37      },
38      ...pedestrianStates
39    }
40  }
41});
42
43const actor = createActor(lightMachine);
44
45actor.subscribe((state) => {
46  console.log(state.value);
47});
48
49actor.start();
50// logs 'green'
51
52actor.send({ type: 'TIMER' });
53// logs 'yellow'
54
55actor.send({ type: 'TIMER' });
56// logs { red: 'walk' }
57
58actor.send({ type: 'PED_TIMER' });
59// logs { red: 'wait' }

Open in Stately Studio

Parallel State Machines

Code Statechart

Code	Statechart
1import { createMachine, createActor } from 'xstate'; 2 3const wordMachine = createMachine({ 4 id: 'word', 5 type: 'parallel', 6 states: { 7 bold: { 8 initial: 'off', 9 states: { 10 on: { 11 on: { TOGGLE_BOLD: 'off' } 12 }, 13 off: { 14 on: { TOGGLE_BOLD: 'on' } 15 } 16 } 17 }, 18 underline: { 19 initial: 'off', 20 states: { 21 on: { 22 on: { TOGGLE_UNDERLINE: 'off' } 23 }, 24 off: { 25 on: { TOGGLE_UNDERLINE: 'on' } 26 } 27 } 28 }, 29 italics: { 30 initial: 'off', 31 states: { 32 on: { 33 on: { TOGGLE_ITALICS: 'off' } 34 }, 35 off: { 36 on: { TOGGLE_ITALICS: 'on' } 37 } 38 } 39 }, 40 list: { 41 initial: 'none', 42 states: { 43 none: { 44 on: { 45 BULLETS: 'bullets', 46 NUMBERS: 'numbers' 47 } 48 }, 49 bullets: { 50 on: { 51 NONE: 'none', 52 NUMBERS: 'numbers' 53 } 54 }, 55 numbers: { 56 on: { 57 BULLETS: 'bullets', 58 NONE: 'none' 59 } 60 } 61 } 62 } 63 } 64}); 65 66const actor = createActor(wordMachine); 67 68actor.subscribe((state) => { 69 console.log(state.value); 70}); 71 72actor.start(); 73// logs { 74// bold: 'off', 75// italics: 'off', 76// underline: 'off', 77// list: 'none' 78// } 79 80actor.send({ type: 'TOGGLE_BOLD' }); 81// logs { 82// bold: 'on', 83// italics: 'off', 84// underline: 'off', 85// list: 'none' 86// } 87 88actor.send({ type: 'TOGGLE_ITALICS' }); 89// logs { 90// bold: 'on', 91// italics: 'on', 92// underline: 'off', 93// list: 'none' 94// }	Open in Stately Studio

1import { createMachine, createActor } from 'xstate';
2
3const wordMachine = createMachine({
4  id: 'word',
5  type: 'parallel',
6  states: {
7    bold: {
8      initial: 'off',
9      states: {
10        on: {
11          on: { TOGGLE_BOLD: 'off' }
12        },
13        off: {
14          on: { TOGGLE_BOLD: 'on' }
15        }
16      }
17    },
18    underline: {
19      initial: 'off',
20      states: {
21        on: {
22          on: { TOGGLE_UNDERLINE: 'off' }
23        },
24        off: {
25          on: { TOGGLE_UNDERLINE: 'on' }
26        }
27      }
28    },
29    italics: {
30      initial: 'off',
31      states: {
32        on: {
33          on: { TOGGLE_ITALICS: 'off' }
34        },
35        off: {
36          on: { TOGGLE_ITALICS: 'on' }
37        }
38      }
39    },
40    list: {
41      initial: 'none',
42      states: {
43        none: {
44          on: {
45            BULLETS: 'bullets',
46            NUMBERS: 'numbers'
47          }
48        },
49        bullets: {
50          on: {
51            NONE: 'none',
52            NUMBERS: 'numbers'
53          }
54        },
55        numbers: {
56          on: {
57            BULLETS: 'bullets',
58            NONE: 'none'
59          }
60        }
61      }
62    }
63  }
64});
65
66const actor = createActor(wordMachine);
67
68actor.subscribe((state) => {
69  console.log(state.value);
70});
71
72actor.start();
73// logs {
74//   bold: 'off',
75//   italics: 'off',
76//   underline: 'off',
77//   list: 'none'
78// }
79
80actor.send({ type: 'TOGGLE_BOLD' });
81// logs {
82//   bold: 'on',
83//   italics: 'off',
84//   underline: 'off',
85//   list: 'none'
86// }
87
88actor.send({ type: 'TOGGLE_ITALICS' });
89// logs {
90//   bold: 'on',
91//   italics: 'on',
92//   underline: 'off',
93//   list: 'none'
94// }

Open in Stately Studio

History States

Code Statechart

Code	Statechart
1import { createMachine, createActor } from 'xstate'; 2 3const paymentMachine = createMachine({ 4 id: 'payment', 5 initial: 'method', 6 states: { 7 method: { 8 initial: 'cash', 9 states: { 10 cash: { 11 on: { 12 SWITCH_CHECK: 'check' 13 } 14 }, 15 check: { 16 on: { 17 SWITCH_CASH: 'cash' 18 } 19 }, 20 hist: { type: 'history' } 21 }, 22 on: { NEXT: 'review' } 23 }, 24 review: { 25 on: { PREVIOUS: 'method.hist' } 26 } 27 } 28}); 29 30const actor = createActor(paymentMachine); 31 32actor.subscribe((state) => { 33 console.log(state.value); 34}); 35 36actor.start(); 37// logs { 38// value: { method: 'cash' }, 39// } 40 41actor.send({ type: 'SWITCH_CHECK' }); 42// logs { 43// value: { method: 'check' }, 44// } 45 46actor.send({ type: 'NEXT' }); 47// logs { 48// value: 'review', 49// } 50 51actor.send({ type: 'PREVIOUS' }); 52// logs { 53// value: { method: 'check' }, 54// }	Open in Stately Studio

1import { createMachine, createActor } from 'xstate';
2
3const paymentMachine = createMachine({
4  id: 'payment',
5  initial: 'method',
6  states: {
7    method: {
8      initial: 'cash',
9      states: {
10        cash: {
11          on: {
12            SWITCH_CHECK: 'check'
13          }
14        },
15        check: {
16          on: {
17            SWITCH_CASH: 'cash'
18          }
19        },
20        hist: { type: 'history' }
21      },
22      on: { NEXT: 'review' }
23    },
24    review: {
25      on: { PREVIOUS: 'method.hist' }
26    }
27  }
28});
29
30const actor = createActor(paymentMachine);
31
32actor.subscribe((state) => {
33  console.log(state.value);
34});
35
36actor.start();
37// logs {
38//   value: { method: 'cash' },
39// }
40
41actor.send({ type: 'SWITCH_CHECK' });
42// logs {
43//   value: { method: 'check' },
44// }
45
46actor.send({ type: 'NEXT' });
47// logs {
48//   value: 'review',
49// }
50
51actor.send({ type: 'PREVIOUS' });
52// logs {
53//   value: { method: 'check' },
54// }

Open in Stately Studio

SemVer Policy

We understand the importance of the public contract and do not intend to release any breaking changes to the runtime API in a minor or patch release. We consider this with any changes we make to the XState libraries and aim to minimize their effects on existing users.

Breaking changes

XState executes much of the user logic itself. Therefore, almost any change to its behavior might be considered a breaking change. We recognize this as a potential problem but believe that treating every change as a breaking change is not practical. We do our best to implement new features thoughtfully to enable our users to implement their logic in a better, safer way.

Any change could affect how existing XState machines behave if those machines are using particular configurations. We do not introduce behavior changes on a whim and aim to avoid making changes that affect most existing machines. But we reserve the right to make some behavior changes in minor releases. Our best judgment of the situation will always dictate such changes. Please always read our release notes before deciding to upgrade.

TypeScript changes

We also reserve a similar right to adjust declared TypeScript definitions or drop support for older versions of TypeScript in a minor release. The TypeScript language itself evolves quickly and often introduces breaking changes in its minor releases. Our team is also continuously learning how to leverage TypeScript more effectively - and the types improve as a result.

For these reasons, it is impractical for our team to be bound by decisions taken when an older version of TypeScript was its latest version or when we didn’t know how to declare our types in a better way. We won’t introduce declaration changes often - but we are more likely to do so than with runtime changes.

Packages

Most of the packages in the XState family declare a peer dependency on XState itself. We’ll be cautious about maintaining compatibility with already-released packages when releasing a new version of XState, but each release of packages depending on XState will always adjust the declared peer dependency range to include the latest version of XState. For example, you should always be able to update xstate without @xstate/react. But when you update @xstate/react, we highly recommend updating xstate too.

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

80 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
Warn: Project is vulnerable to: GHSA-64vr-g452-qvp3
Warn: Project is vulnerable to: GHSA-9cwx-2883-4wfx
Warn: Project is vulnerable to: GHSA-g3ch-rx76-35fx
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
Warn: Project is vulnerable to: GHSA-5rrq-pxf6-6jx5
Warn: Project is vulnerable to: GHSA-8fr3-hfg3-gpgp
Warn: Project is vulnerable to: GHSA-gf8q-jrpm-jvxq
Warn: Project is vulnerable to: GHSA-2r2c-g63r-vccr
Warn: Project is vulnerable to: GHSA-cfm4-qjh2-4765
Warn: Project is vulnerable to: GHSA-x4jg-mjrx-434g
Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
Warn: Project is vulnerable to: GHSA-566m-qj78-rww5
Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
Warn: Project is vulnerable to: GHSA-hwj9-h5mp-3pm3
Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
Warn: Project is vulnerable to: GHSA-qxrj-hx23-xp82
Warn: Project is vulnerable to: GHSA-mv48-hcvh-8jj8
Warn: Project is vulnerable to: GHSA-353f-5xf4-qw67
Warn: Project is vulnerable to: GHSA-vc8w-jr9v-vj7f
Warn: Project is vulnerable to: GHSA-hqq7-2q2v-82xq
Warn: Project is vulnerable to: GHSA-q8gg-vj6m-hgmj
Warn: Project is vulnerable to: GHSA-7q7g-4xm8-89cq
Warn: Project is vulnerable to: GHSA-h452-7996-h45h
Warn: Project is vulnerable to: GHSA-36jr-mh4h-2g58
Warn: Project is vulnerable to: GHSA-p3vf-v8qc-cwcr
Warn: Project is vulnerable to: GHSA-gx9m-whjm-85jf
Warn: Project is vulnerable to: GHSA-mmhx-hmjr-r674
Warn: Project is vulnerable to: GHSA-qrmc-fj45-qfc2
Warn: Project is vulnerable to: GHSA-74fj-2j2h-c42q
Warn: Project is vulnerable to: GHSA-pw2r-vq6v-hr8c
Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
Warn: Project is vulnerable to: GHSA-8mmm-9v2q-x3f9
Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97
Warn: Project is vulnerable to: GHSA-7wwv-vh3v-89cq
Warn: Project is vulnerable to: GHSA-pfq8-rq6v-vf5m
Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27
Warn: Project is vulnerable to: GHSA-8g7p-74h8-hg48
Warn: Project is vulnerable to: GHSA-pc5p-h8pf-mvwp
Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
Warn: Project is vulnerable to: GHSA-6vfc-qv3f-vr6c
Warn: Project is vulnerable to: GHSA-x3vm-38hw-55wf
Warn: Project is vulnerable to: GHSA-m4gq-x24j-jpmf
Warn: Project is vulnerable to: GHSA-wrvr-8mpx-r7pp
Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m / GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-5g97-whc9-8g7j
Warn: Project is vulnerable to: GHSA-8r4g-cg4m-x23c
Warn: Project is vulnerable to: GHSA-6fw4-hr69-g3rv
Warn: Project is vulnerable to: GHSA-gqgv-6jq5-jjj9
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
Warn: Project is vulnerable to: GHSA-3f95-r44v-8mrg
Warn: Project is vulnerable to: GHSA-28xr-mwxg-3qc8
Warn: Project is vulnerable to: GHSA-9p95-fxvg-qgq2
Warn: Project is vulnerable to: GHSA-9w5j-4mwv-2wj8
Warn: Project is vulnerable to: GHSA-pqhp-25j4-6hq9
Warn: Project is vulnerable to: GHSA-8225-6cvr-8pqp
Warn: Project is vulnerable to: GHSA-8266-84wp-wv5c
Warn: Project is vulnerable to: GHSA-5j4c-8p2g-v4jx
Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6
Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-c24v-8rfc-w8vw
Warn: Project is vulnerable to: GHSA-8jhw-289h-jh2g

Score

5.3

/10

Last Scanned on 2024-11-18

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More

Other packages similar to xstate

@xstate/react

5.0.0

XState tools for React

@xstate/fsm

2.1.0

XState for finite state machines

@xstate/inspect

0.8.0

XState inspection utilities

@xstate/cli

0.5.17

### xstate typegen <files>

xstate

Installations

Score

Pull Requests

46

2,319

381

1,892

Issues

89

1,351

1,262

Releases

Developer

Developer Guide

CommonJS, ESM

Yes

20.18.0

10.8.2

Statistics

Languages

Total Downloads

309,018,023

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

✨ Create state machines visually in Stately Studio → state.new

Templates

Super quick start

Stately Studio

Why?

Packages

Finite State Machines

Hierarchical (Nested) State Machines

Parallel State Machines

History States

Sponsors

SemVer Policy

Breaking changes

TypeScript changes

Packages

10

10

10

10

10

5

0

0

0

0

0

0

5.3

/10

Other packages similar to xstate