Finite state machines for building accessible design systems and UI components.
Alternatives To Zag
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Zag2,6472911 hours ago100July 15, 202213mitTypeScript
Finite state machines for building accessible design systems and UI components.
Zag Docs127
a day ago2TypeScript
Documentation website for Zag
a year ago53Kotlin
Automated accessibility testing on mobile devices.
Picture Gallery8
7 days agomitJavaScript
Universal JavaScript app, made with ECMAScript modules running natively in a browser or local environment 🖼️
Alternatives To Zag
Select To Compare

Alternative Project Comparisons
Zag.js hero image


Finite state machines for accessible JavaScript components

  • **Write once, use everywhere **: The component interactions are modelled in a framework agnostic way. We provide adapters for JS frameworks like React, Solid, or Vue.
  • **Focus on accessibility **: Zag is built with accessibility in mind. We handle many details related to keyboard interactions, focus management, aria roles and attributes.
  • **Headless **: The machine APIs are completely unstyled and gives you the control to use any styling solution you prefer.
  • **Powered by state machines **: Zag is built on top of the latest ideas in Statecharts. We don't follow the SCXML specifications, but we've created an API that we think will help us build more complex components fast.


To see the documentation, visit


For changelog, visit


With the rise of design systems and component-driven development, there's an endless re-implementation of common component patterns (Tabs, Menu, Modal, etc.) in multiple frameworks.

Most of these implementations seem to be fairly similar in spirit, the differences being around the reactivity and effects systems for the framework (e.g. useState, useEffect in React.js). Framework specific solutions tend to grow in complexity over time and often become hard to understand, debug, improve or test.


Zag is a JavaScript API that implements common component patterns using the state machine methodology.


npm i --save @zag-js/{component}

# or

yarn add @zag-js/{component}

{component} represents any component machine like dialog (@zag-js/dialog), tooltip (@zag-js/tooltip) , etc.

For framework specific solutions, we provide simple wrappers to help you consume the component state machines.

  • @zag-js/react - React hooks for consuming machines in React applications
  • @zag-js/vue - Vue composition for consuming machines in Vue applications
  • @zag-js/solid - Solid.js utilities for consuming machines in Solid.js applications
  • @zag-js/svelte - Svelte utilities for consuming machines in Svelte applications


import * as toggle from "@zag-js/toggle"
import { normalizeProps, useMachine } from "@zag-js/react"

function Example() {
  // if you need access to `state` or `send` from machine
  const [state, send] = useMachine(toggle.machine({ id: "2" }))

  // convert machine details into `DOM` props
  const api = toggle.connect(state, send, normalizeProps)

  // consume into components
  return <button {...api.buttonProps}>Toggle me</button>

Guiding Principles

  • All component machines and tests are modelled according to the WAI-ARIA authoring practices
  • Write end-to-end tests for every component based on the WAI-ARIA spec. Regardless of the framework, users expect component patterns to work the same way!
  • All machines should be light-weight, simple, and easy to understand. Avoid using complex machine concepts like spawn, nested states, etc.

Fun Facts

Zag means to take a sharp change in direction. This clearly describes our approach of using state machines to power the logic behind UI components.


  • When you see someone using classic react, vue or solid to build an interactive UI component that exists in Zag, tell them to "zag it!"

  • Anyone using Zag will be called a "zagger"

  • The feeling you get when you use Zag will be called "zagadat!"

  • The Zag community will be called "zag nation"


Build commands

Our build is managed with esbuild and turborepo to provide fast, concurrent builds across the packages.

  • build-fast : Build the CJS and ESM versions, without the types.
  • build : Build the CJS, ESM and DTS files. This is the actual production build that we run in the CI.
  • start : The command to run when developing for Zag. It runs the build:fast command, watches for changes and rebuilds as needed.


Since zag is framework agnostic, we need a way to test it within a framework. The examples/ directory includes starter projects for the frameworks we support.

  • start-react : Starts the Next.js TypeScript project
  • start-vue : Starts the Vue 3 TypeScript project
  • start-solid : Starts the Solid TypeScript project
  • start-svelte : Starts the Svelte TypeScript project

E2E Tests

We've setup end-to-end tests for every machine we built. We use Playwright for testing and we ensure that the component works the same way regardless of the framework.

  • e2e-react : Starts the E2E tests for the React project
  • e2e-vue : Starts the E2E tests for the Vue project
  • e2e-solid : Starts the E2E tests for the Solid project
  • e2e-svelte : Starts the E2E tests for the Svelte project

Contributing new machines/features

  • generate-machine : Generates a new machine package in the packages/ directory. It sets up the required files and structure for new machine.
  • generate-util : Generates a new utility package in the packages/utilities directory.

Other commands

  • test : Run the tests for all packages
  • lint : Lint all packages



Looking to contribute? Look for the Good First Issue label.


Please file an issue for bugs, missing documentation, or unexpected behavior.

Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a . This helps maintainers prioritize what to work on.


MIT Segun Adebayo

Popular Accessibility Projects
Popular State Machine Projects
Popular User Interface Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Headless Browsers
State Machine