Learn how to build a pin-input component with state machines, Zag.js and React.

We’ll look at modeling a UI component with state machines, implementing those in a framework agnostic way using Zag.js, and connect the logic to the UI component.

This course is a must-watch if you’re unfamiliar with State machines, and want to learn how to use them to build UI components with ease.

In this course, you will:

- Learn fundamental concept of state machine, event and transition
- Model a UI component with state machine
- Connect state machine logic to UI
- Manage DOM events in state machines
- Create custom React hooks with state machines

Thanks for taking a look at my course on how to build statechart driven UI components with Zag.js.

Logic in a UI component can get tricky with the states and actions that you are juggling as a user interacts with your interface. This is why I believe statecharts are a game changer in building out logic that is bug-free and maintainable. 

In this course you will learn how to: 
- Breakdown components into a set of finite states
- Capture logic in a state machine that is readable and understandable
- Share logic visually with your team
- Interact with state machines from a UI component

Introduction: Statechart Driven UI Components with Zag.js

A state machine is a method of modeling a finite number of states and events. When an event is sent, actions and transitions are triggered within the machine to update it's state.

Here we model a a state machine for a check box. There are `unchecked` and `checked` states with a `click` event that transitions the machine between these two states.


Model Finite Number of State and Events with State Machines

A pin input is a common UI pattern that has more state than you might initially think. We have a handful of use-cases to think through when modeling a state machine that will power a pin input. It should: 

- Automatically focus the next field on typing and focuses the previous field on deletion.
- Support numeric and alphanumeric values.
- Support for copy/paste to autofill all fields.

We’ll break down the interactions and logic of a pin input component, detailing its state and transitions as well as talk through the actions that will be emitted when certain events are fired.


Model the Basic Events, Actions, and Transitions of a Pin Input Component

We’ll spin up a Vite project for React and install the required Zag.js dependency to model the pin input component logic.

Set up a React + Zag.js Project with Vite

Now that we have a project, we need a Pin input to work with. We'll create 4 inputs and style them so they look like a security code pin input that you would expect to see.

Style a Pin Input through Data Attributes in React

We've mapped out what a Pin input state machine should look like so now it's time to start implementing that in code. 

We'll be using Zag.js to model the machine for us. Zag.js works well with TypeScript so the first thing to do is create types for the machine context and state. Then we'll stub out the states, transitions, and actions for the machine. 

While we aren't implementing the actions in this lesson you'll quickly see how a state machine makes complex interactions easier to understand by the events that occur and the actions that are triggered by those events.

Lastly, we'll paste our machine in the stately machine visualizer and you'll see a visual representation of the machine that was created.


Create and Visualize a Pin Input State Machine with TypeScript and Zag.js

Now that we have a machine defined we need to send it events with the relevant data from the UI. To do this we'll need to install the useMachine hook from `@zag-js/react`. From there we'll wire up the actions that we need to send on the input element (e.g. onChange, onFocus, onBlur, and onKeyDown).

Connect Zag.js Machine Logic to React UI through the useMachine Hook

Now that we have a machine and our UI is sending it events, we need to actually do something with events that are sent. This is where actions come into play.

We'll implement focus and blur events for the input by setting the context `focusedIndex` to the index that is coming in from the UI. We can mutate context directly in Zag.js because it handles mutations through proxies to stay reactive.


Implement a State Machine Action for Setting Input Focus in Zag.js

Let's actually implement inputting values into our Pin input. We have 3 functions that need implemented. They are `setFocusedValue`, `focusNextInput`, and `executeFocus`. The first two will be pretty straight forward in grabbing values from context and our events and setting new values to our context. 

When we finish implementing `setFocusedValue` and `setFocusedInput` we'll need a way to actually trigger our focus to be set in the DOM. This is where the watch property in a Zag.js State Machine comes into play. We will watch the `focusedIndex` context value and run `executeFocus` any time the focus index changes in our machine (e.g. when `focusNextInput` is triggered after an input event).


Trigger Side Effects in a Zag.js State Machine with the watch Property

We'll be implementing the backspace event which triggers two actions: `clearFocusedValue`, and `focusPreviousInput`. 

These implementations you'll be familiar with at this point but what you'll notice when we actually try to hit backspace that the focus value will get cleared but we won't be setting focus to the previous input. This is because there are several DOM mutations happening at the same time. We'll fix this by scheduling the focus of inputs to the next animation frame with `requestAnimationFrame`


Schedule Input Focus with requestAnimationFrame to Handle Multiple DOM Mutations in Zag.js

The paste event is a unique input event that we need to handle. When we paste a value in from the clipboard, we need to split that value and input single characters to the individual inputs in our Pin Input.

To do this we will need to `preventDefault` in the `onPaste` event so that we can implement our custom logic here. Next we'll implement `setPastedValue` that splits and iterates over the input value we receive and sets it into context. 

Finally we'll implement `focusLastEmptyInput` that looks up the index of the first empty value with `findIndex` and focuses that index.


Spread Values Across a Pin Input Field in a Zag.js State Machine 

We have a bug in our pin input. Only 1 value should be allowed per input but if we focus an input that already has a value we can still input another value. 

Let's fix that.

We'll need to implement a function `getNextValue` that will take in the focused value of the current input and the event input that is coming in. After a set of conditionals we will select the value that wasn't the current focused value to update the field.


Implement Conditional Logic in a Zag.js Action to Enforce a Single Character Per Input

When the pin input values are full we will want to do something with those values such as sending an HTTP request.

To do this we'll implement a callback in context that will get invoked when all the values are computed. We'll do this by creating a computed property that returns true when all values in context are full. From there we will watch that computed property to invoke our callback.

Trigger Side Effects using Zag.js computed and watch Properties

In some cases you'll want to actually have your pin input in a form to handle submitting the values. What's awesome about our implementation is that it doesn't get in the way of adding functionality like this.

First we'll extend our state machine to focus the first input when we click on the input label. Then we'll wrap our Pin Input component in a form element and implement an onSubmit. We can submit values of the form by creating a hidden input and set it's values to the joined values of the other inputs.


Submit Pin Input Values in a Form with a Hidden Input

In many projects, it is useful to separate the logic that you right with the view that you create so that you can easily share that logic throughout your application. In React we do this with custom React hooks.

We'll improve on the reusability of the pin input component by refactoring it to a custom React hook. To do this we will utilize the prop getter pattern 

This Headless Component pattern is a very useful pattern when building reusable components. It allows you separate functionality from presentation, making it easy to style them as needed.


Statechart Driven UI Components with Zag.js

Instructor

Course content (15 lessons)

Instructor