https://github.com/davidkpiano/xstate

Skip to content
 
Sign up

  * Why GitHub?
    Features -
      + Mobile -
      + Actions -
      + Codespaces -
      + Packages -
      + Security -
      + Code review -
      + Project management -
      + Integrations -
      + GitHub Sponsors -
      + Customer stories-
  * Team
  * Enterprise
  * Explore
      + Explore GitHub -

    Learn and contribute

      + Topics -
      + Collections -
      + Trending -
      + Learning Lab -
      + Open source guides -

    Connect with others

      + The ReadME Project -
      + Events -
      + Community forum -
      + GitHub Education -
      + GitHub Stars program -
  * Marketplace
  * Pricing
    Plans -
      + Compare plans -
      + Contact Sales -
      + Nonprofit -
      + Education -

[                    ] [search-key]

  *  
    #
    In this repository All GitHub |
    Jump to |

  * No suggested jump to results

  *  
    #
    In this repository All GitHub |
    Jump to |
  *  
    #
    In this user All GitHub |
    Jump to |
  *  
    #
    In this repository All GitHub |
    Jump to |

Sign in Sign up
{{ message }}

davidkpiano / xstate

  * Sponsor

    Sponsor davidkpiano/xstate

  * Notifications
  * Star 15.1k
  * Fork 649

State machines and statecharts for the modern web.

xstate.js.org/docs
MIT License
15.1k stars 649 forks
Star
Notifications

  * Code
  * Issues 100
  * Pull requests 32
  * Discussions
  * Actions
  * Projects 2
  * Security
  * Insights

More

  * Code
  * Issues
  * Pull requests
  * Discussions
  * Actions
  * Projects
  * Security
  * Insights

master
Switch branches/tags
[                    ]
Branches Tags
Nothing to show
{{ refName }} default View all branches
Nothing to show
{{ refName }} default
View all tags
89 branches 145 tags
Go to file Code
 
Clone
HTTPS GitHub CLI
[https://github.com/d]

Use Git or checkout with SVN using the web URL.

[gh repo clone davidk]

Work fast with our official CLI. Learn more.

  * Open with GitHub Desktop
  * Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching Xcode

If nothing happens, download Xcode and try again.

Go back

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio
and try again.

Go back

Latest commit

@davidkpiano
davidkpiano Merge pull request #1971 from lekterable/patch-1
...
b0e4aa8 Mar 4, 2021
Merge pull request #1971 from lekterable/patch-1

docs: use correct link

b0e4aa8

Git stats

  * 3,282 commits

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
.changeset
Version Packages (#1949)
Feb 18, 2021
.github
Add pull_request as a trigger for the CI job
Nov 14, 2020
.vscode
chore: don't ignore settings.json
Jul 15, 2019
docs
docs: use correct link
Mar 4, 2021
packages
Fix README.md
Feb 23, 2021
scripts
Run prettier on the codebase
Apr 4, 2020
.gitignore
Migrate to Jest
Aug 2, 2019
.prettierrc
Prettier + adding unit tests for guard conditions
Dec 6, 2017
CODE_OF_CONDUCT.md
Create CODE_OF_CONDUCT.md
Nov 24, 2018
CONTRIBUTING.md
Update CONTRIBUTING.md
Aug 25, 2020
ISSUE_TEMPLATE.md
Update ISSUE_TEMPLATE.md
Aug 2, 2020
LICENSE
Initial commit
Sep 14, 2015
README.md
Update README.md
Feb 9, 2021
jest.config.js
Remove xstate-dev
Feb 3, 2021
lerna.json
Migrate to Yarn & move core package to separate directory
Oct 5, 2019
migration.md
Create migration.md
Nov 1, 2018
package.json
Remove xstate-dev
Feb 3, 2021
tsconfig.base.json
chore: add skipLibCheck: true to tsconfig.base.json
Nov 28, 2019
tsconfig.monorepo.json
chore(build): fix reference to types file in @xstate/fsm
Nov 5, 2019
tslint.json
Add withServiceScope
Apr 28, 2019
yarn.lock
Update immer
Feb 3, 2021
View code

README.md


                               XState
             [JavaScript state machines and statecharts]


npm version [6874747073]

JavaScript and TypeScript finite state machines and statecharts for
the modern web.

 Read the documentation

 Adheres to the SCXML specification

 Chat on the Stately Discord Community

 Packages

  *  xstate - Core finite state machine and statecharts library +
    interpreter
  *  @xstate/fsm - Minimal finite state machine library
  *  @xstate/graph - Graph traversal utilities for 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/test - Model-Based-Testing utilities (using XState) for
    testing any software
  *  @xstate/inspect - Inspection utilities for XState

 Templates

Get started by forking one of these templates on CodeSandbox:

  * XState Template - no framework
  * XState + TypeScript Template - no framework
  * XState + React Template
  * XState + React + TypeScript Template
  * XState + Vue Template
  * XState + Vue 3 Template
  * XState + Svelte Template

 Super quick start

npm install xstate

import { createMachine, interpret } from 'xstate';

// Stateless machine definition
// machine.transition(...) is a pure function used by the interpreter.
const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

// Machine instance with internal state
const toggleService = interpret(toggleMachine)
  .onTransition((state) => console.log(state.value))
  .start();
// => 'inactive'

toggleService.send('TOGGLE');
// => 'active'

toggleService.send('TOGGLE');
// => 'inactive'

 Promise example

 See the visualization on xstate.js.org/viz

import { createMachine, interpret, assign } from 'xstate';

const fetchMachine = createMachine({
  id: 'Dog API',
  initial: 'idle',
  context: {
    dog: null
  },
  states: {
    idle: {
      on: {
        FETCH: 'loading'
      }
    },
    loading: {
      invoke: {
        id: 'fetchDog',
        src: (context, event) =>
          fetch('https://dog.ceo/api/breeds/image/random').then((data) =>
            data.json()
          ),
        onDone: {
          target: 'resolved',
          actions: assign({
            dog: (_, event) => event.data
          })
        },
        onError: 'rejected'
      },
      on: {
        CANCEL: 'idle'
      }
    },
    resolved: {
      type: 'final'
    },
    rejected: {
      on: {
        FETCH: 'loading'
      }
    }
  }
});

const dogService = interpret(fetchMachine)
  .onTransition((state) => console.log(state.value))
  .start();

dogService.send('FETCH');

  * Visualizer
  * Why?
  * Finite State Machines
  * Hierarchical (Nested) State Machines
  * Parallel State Machines
  * History States
  * Sponsors

 Visualizer

Visualize, simulate, and share your statecharts in XState Viz!

xstate visualizer

 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
  * Pure UI by Guillermo Rauch
  * Pure UI Control by Adam Solove
  * Spectrum - Statecharts Community (For XState specific questions,
    please use the GitHub Discussions)

 Finite State Machines

Light Machine

import { createMachine } from 'xstate';

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

const currentState = 'green';

const nextState = lightMachine.transition(currentState, 'TIMER').value;

// => 'yellow'

 Hierarchical (Nested) State Machines

Hierarchical Light Machine

import { createMachine } from 'xstate';

const pedestrianStates = {
  initial: 'walk',
  states: {
    walk: {
      on: {
        PED_TIMER: 'wait'
      }
    },
    wait: {
      on: {
        PED_TIMER: 'stop'
      }
    },
    stop: {}
  }
};

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

const currentState = 'yellow';

const nextState = lightMachine.transition(currentState, 'TIMER').value;
// => {
//   red: 'walk'
// }

lightMachine.transition('red.walk', 'PED_TIMER').value;
// => {
//   red: 'wait'
// }

Object notation for hierarchical states:

// ...
const waitState = lightMachine.transition({ red: 'walk' }, 'PED_TIMER').value;

// => { red: 'wait' }

lightMachine.transition(waitState, 'PED_TIMER').value;

// => { red: 'stop' }

lightMachine.transition({ red: 'stop' }, 'TIMER').value;

// => 'green'

 Parallel State Machines

Parallel state machine

const wordMachine = createMachine({
  id: 'word',
  type: 'parallel',
  states: {
    bold: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_BOLD: 'off' }
        },
        off: {
          on: { TOGGLE_BOLD: 'on' }
        }
      }
    },
    underline: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_UNDERLINE: 'off' }
        },
        off: {
          on: { TOGGLE_UNDERLINE: 'on' }
        }
      }
    },
    italics: {
      initial: 'off',
      states: {
        on: {
          on: { TOGGLE_ITALICS: 'off' }
        },
        off: {
          on: { TOGGLE_ITALICS: 'on' }
        }
      }
    },
    list: {
      initial: 'none',
      states: {
        none: {
          on: { BULLETS: 'bullets', NUMBERS: 'numbers' }
        },
        bullets: {
          on: { NONE: 'none', NUMBERS: 'numbers' }
        },
        numbers: {
          on: { BULLETS: 'bullets', NONE: 'none' }
        }
      }
    }
  }
});

const boldState = wordMachine.transition('bold.off', 'TOGGLE_BOLD').value;

// {
//   bold: 'on',
//   italics: 'off',
//   underline: 'off',
//   list: 'none'
// }

const nextState = wordMachine.transition(
  {
    bold: 'off',
    italics: 'off',
    underline: 'on',
    list: 'bullets'
  },
  'TOGGLE_ITALICS'
).value;

// {
//   bold: 'off',
//   italics: 'on',
//   underline: 'on',
//   list: 'bullets'
// }

 History States

Machine with history state

const paymentMachine = createMachine({
  id: 'payment',
  initial: 'method',
  states: {
    method: {
      initial: 'cash',
      states: {
        cash: { on: { SWITCH_CHECK: 'check' } },
        check: { on: { SWITCH_CASH: 'cash' } },
        hist: { type: 'history' }
      },
      on: { NEXT: 'review' }
    },
    review: {
      on: { PREVIOUS: 'method.hist' }
    }
  }
});

const checkState = paymentMachine.transition('method.cash', 'SWITCH_CHECK');

// => State {
//   value: { method: 'check' },
//   history: State { ... }
// }

const reviewState = paymentMachine.transition(checkState, 'NEXT');

// => State {
//   value: 'review',
//   history: State { ... }
// }

const previousState = paymentMachine.transition(reviewState, 'PREVIOUS').value;

// => { method: 'check' }

 Sponsors

Huge thanks to the following companies for sponsoring xstate. You can
sponsor further xstate development on OpenCollective.

[6874747073] [6874747073]

About

State machines and statecharts for the modern web.

xstate.js.org/docs

Topics

workflow interpreter state-management state-machine statechart state 
orchestration visualizer scxml

Resources

Readme

License

MIT License

Releases 145

 
@xstate/react@1.3.1 Latest
Feb 18, 2021
+ 144 releases

Sponsor this project

  * 
     

  * open_collective opencollective.com/xstate

Learn more about GitHub Sponsors

Packages 0

No packages published

Used by 61.1k

 

  * @pattaraphol
  * @AleBlondin
  * @jesster2k10
  * @KyleAMathews
  * @pcsandford
  * @hjortureh
  * @iuzairjan
  * @fenagel

+ 61,093

Contributors 200

  * @davidkpiano
  * @Andarist
  * @mogsie
  * @hnordt
  * @studnitz
  * @chenxsan
  * @jamesopstad
  * @nlopin
  * @carloslfu

+ 189 contributors

Languages

  * TypeScript 98.2%
  * JavaScript 1.1%
  * Other 0.7%

  * (c) 2021 GitHub, Inc.
  * Terms
  * Privacy
  * Security
  * Status
  * Docs

 

  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session.