ReactJS

Building interactive forms with TanStack Form

Jan 12, 2024

5 min read

TanStack Form is a new headless form library that makes building more complex and interactive forms easy. TanStack has understood the power of ‘headless’ UI libraries for quite some time with some really incredible tools like TanStack Table and TanStack Query. Given the high quality of all the other libraries in the TanStack suite, I was excited to give this new form library a try.

If you’ve used react-hook-form before the two libraries have quite a bit in common. The transition should be mostly straightforward. Let's start by comparing the two libraries and bit and then dig into the TanStack Form API with some examples and code.

Comparison to react-hook-form

At a high level, the two libraries are pretty similar:

Headless, hook-based API
Performance (both libraries minimize amount of renders triggered by state changes)
Lightweight, zero-dependencies (TanStack 4.4kb, react-hook-form 9.7kb)
Comprehensive feature set
Type-safety / TypeScript support
Form / Input validation and schemas

There are a few things that set TanStack Form apart:

UI Agnostic - TanStack Form offers support for other UI libraries and frameworks through a plugin-style system. Currently, React & Solid is supported out of the box.
Simpler API and documentation - The API surface area is a bit smaller, and the documentation makes it easy to find the details on all the APIs.
First-class TypeScript support - TanStack Form provides really impressive type inference. It stays out of your way and lets you focus on writing code instead of wrangling types.

Building forms

Since the API for TanStack Form is pretty small, we can walk through the important APIs pretty quickly to see how they work together to help us build interactive client-side forms.

useForm(options)

useForm accepts an options object that accepts defaultValues, defaultState, and event handler functions like onSubmit, onChange, etc. The types are clear, and the source code is easy to read so you can refer to FormApi.ts file for more specifics. Currently, the examples on the website don’t provide a type for the generic TData that useForm accepts. It will infer the form types based on the defaultValues that are provided, but in this example, I will provide the type explicitly.

import { useForm } from "@tanstack/react-form";

interface CreateAccountFormData {
	email: string;
	password: string;
	displayName: string;
}

function CreateAccountForm() {
	const form = useForm<CreateAccountFormData>({
		defaultValues: {
			email: '',
			password: '',
			displayName: '',
		},
		onSubmit: (values) => {
			// values are typed for us
			// values.[email, password, displayName]
		}
	});
}

The API for your form is returned from the useForm hook. We will use this API to build the fields and their functionality in our component.

useField(opts)

If you want to abstract one of your form fields into its own component we can use the useField hook. The useField generic parameters take the type definition of your form and the field name.

function PasswordField() {
  const field = useField<CreateAccountFormData, "password">({
    name: "password",
    onChange: (value) =>
      value.length > 8 ? undefined : "Password must be 8 characters long",
  });
  const error = field.state.meta.errors[0];
  return (
    <>
      <label htmlFor={field.name}>Password</label>
      <input
        type="password"
        name={field.name}
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
      />
      {error && <span>{error}</span>}
    </>
  );
}

Validation is as simple as returning a string from your field onChange handler. For our password field we return an error message if the length isn’t at least 8 characters long. We bind our field states and event handlers to the form input by passing them in as props.

Component API

form includes a component API with a Context Provider, a component for rendering Field components, and a Subscribe component for subscribing to state changes. I’ve added the remaining fields to our form using the Field component and included our PasswordField from above. Using the Field component is similar to using the useField hook - the difference is our field instance gets passed in via a render prop.

return (
    <form.Provider>
      <form
        onSubmit={(e) => {
          e.preventDefault();
          e.stopPropagation();
          void form.handleSubmit();
        }}
      >
        <div>
          <form.Field name="email">
            {(field) => (
              <>
                <label htmlFor={field.name}>Email</label>
                <input
                  name={field.name}
                  value={field.state.value}
                  onBlur={field.handleBlur}
                  onChange={(e) => field.handleChange(e.target.value)}
	      required
                />
              </>
            )}
          </form.Field>
        </div>
        <div>
	<PasswordField />
        </div>
        <div>
          <form.Field name="displayName">
            {(field) => (
              <>
                <label htmlFor={field.name}>Display Name</label>
                <input
                  name={field.name}
                  value={field.state.value}
                  onBlur={field.handleBlur}
                  onChange={(e) => field.handleChange(e.target.value)}
	      required
                />
              </>
            )}
          </form.Field>
        </div>
        <form.Subscribe
selector={(state) => [state.canSubmit, state.isSubmitting]}>
{([canSubmit, isSubmitting]) => (
<button type="submit" disabled={!canSubmit}>
              			{isSubmitting ? "..." : "Submit"}
            </button>
          )}
        </form.Subscribe>
      </form>
    </form.Provider>
  );

We wrapped our submit button with the Subscribe component which has a pretty interesting API. Subscribe allows you to subscribe to state changes granularly. Whatever state items you return from the selector gets passed into the render prop and re-render it on changes. This will be really useful in places where render performance is critical.

Async event handlers

We can use the built-in async handlers and debounce options to implement a search input. This feature makes a common pattern like this trivial.

function SearchField() {
  const field = useField<{ query: string }>, "query">({
    name: "query",
    onChangeAsync: (value) => searchFn(value),
    onChangeAsyncDebounceMs: 500
  });
  return (
      <input
        type="text"
        name={field.name}
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
      />
  );
}

Async event handlers can be used for other things like async validation as well. We could update our email input from our create account form to check to see if the account already exists.

<form.Field 
  name="email" 
  onBlurAsync={async (value) => api.isEmailRegistered(value)}>
  {(field) => (
    <>
      <label htmlFor={field.name}>Email</label>
      <input
        name={field.name}
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
        required
      />
    </>
  )}
</form.Field>

Validation adapters

Since this post was first written, TanStack Form has added adapters for popular schema validation libraries like Yup and Zod. The actual API for using the schemas is a little bit different then what you might be used to from react-hook-form. Instead of passing a schema definition for all of the fields to the root form API, you provide schemas for each field individually. We’ll look at the Zod example from the documentation.

import { useForm } from '@tanstack/react-form'
import { zodValidator } from '@tanstack/zod-form-adapter'

export default function App() {
 const form = useForm({
   defaultValues: {
     firstName: '',
     lastName: '',
   },
   onSubmit: async ({ value }) => {
     // Do something with form data
     console.log(value)
   },
   // Add a validator to support Zod usage in Form and Field
   validatorAdapter: zodValidator,
 })

To use the schema validation you need to pass the schema validation adapter into the validatorAdapter option in the useForm declaration. Looking at the FieldInfo component from the example we can see that the internal state and API for form validation is the same. The adapter takes care of wiring up the schema validation library to handle the underlying field validation.

function FieldInfo({ field }: { field: FieldApi<any, any, any, any> }) {
 return (
   <>
     {field.state.meta.touchedErrors ? (
       <em>{field.state.meta.touchedErrors}</em>
     ) : null}
     {field.state.meta.isValidating ? 'Validating...' : null}
   </>
 )
}

So we can easily check the state of our field to see if there are any errors or if it’s processing some async validation logic.

We mentioned that without the schema adapter we can just return an error message string from a validation function to indicate an error. With the schema adapter, we instead just return the schema itself. This works for async validations as well.

<form.Field
    name="firstName"
    validators={{
        onChange: z
          .string()
           .min(3, 'First name must be at least 3 characters'),
         onChangeAsyncDebounceMs: 500,
         onChangeAsync: z.string().refine(
              async (value) => {
                   await new Promise((resolve) => setTimeout(resolve, 1000))
                   return !value.includes('error')
               },
               {
                 message: "No 'error' allowed in first name",
               },
           ),
     }}
/>

Initially, I wasn’t sure that I would like defining a schema at the field level instead of providing a schema up front for the entire form. After sitting with it for a bit, I think it’s a better solution. The validations are decoupled from the value of the field and it allows a clean and simple API to decide when they run. In the example above validations against the schema will run on every change to the field value but we could easily change this to onBlur or any of the other available event handlers.

Conclusion

If you don’t mind taking a chance on a newer library from a well-established author in the ecosystem, Tanstack Form is a solid choice.

The APIs are easy to understand, and it has some nice async event handling features that are extremely useful.
It includes adapters for using schema validation libraries like Zod.
It is UI library/framework agnostic (currently has plugins to support React, React Native, and Solid)
Quality TypeScript support In my opinion, it’s the most intuitive and flexible form library out there. TanStack and all of its libraries are amazingly well designed. 10/10

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Dane Grant

JavaScript developer building things on web, native, and server environments. Free time filled with reading, cooking, dog, sports, comedy, and music.

@danecando @danecando

Next.js Route Groups

Starting from Next.js 13.4, Vercel introduced the App Router with a whole set of new and exciting features. The way we organize the routing in our application has changed radically compared to previous versions of Next.js, as well as the definition and usage of Layouts for our pages. In this article, we will focus on what is called Route Groups, their use cases, and how they can help us in our developer experience. Basic introduction to the new App Router In version 13, Next.js introduced a new App Router built on React Server Components, which supports shared layouts, nested routing, loading states, error handling, and more. The App Router works in a new directory named app Creating a page.tsx file inside the app/test-page folder allows you to define what users are going to see when they navigate to /test-page. So folder’s names inside app directory define your app routes. You can also have nested routes like this: In this case, the URL of your page will be /test-page/nested-page By default, components inside app are React Server Components. This is a performance optimization and allows you to easily adopt them, and you can also use Client Components. Layouts In Next.js, a Layout file is a special component that is used to define the common structure and layout of multiple pages in your application. It acts as a wrapper around the content of each page, providing consistent styling, structure, and functionality. The purpose of a Layout file is to encapsulate shared elements such as headers, footers, navigation menus, sidebars, or any other components that should be present on multiple pages. By using a Layout file, you can avoid duplicating code across multiple pages and ensure a consistent user experience throughout your application. To create a Layout file in Next.js, you typically create a separate component file, such as Layout.tsx, and define the desired layout structure within it. This component can then be imported and used on individual pages where you want to apply the shared layout. By wrapping your page content with the Layout component, Next.js will render the shared layout around each page, providing a consistent look and feel. This approach simplifies the management of common elements and allows for easy updates or modifications to the layout across multiple pages. Here is an example of how to use a Layout file with the new App Router Route Groups In Next.js, the folders in your app directory usually correspond to URL paths. But if you mark a folder as a Route Group, it won't be included in the URL path of the route. This means you can organize your routes and project files into groups without changing the URL structure. Route groups are helpful for: 1. Organizing routes into groups based on site sections, intent, or teams. 2. Creating nested layouts within the same route segment level: - You can have multiple nested layouts in the same segment, even multiple root layouts. - You can add a layout to only a subset of routes within a common segment. To create a route group inside your app folder you just need to wrap the folder’s name in parenthesis: (folderName) Since route groups won’t change the URL structure your page.tsx content will be shown under the/inside-route-group path. Use cases Route groups are amazing when you want to create multiple layouts inside your page: Or if you want to specify a layout for a specific group of pages You need to be careful because all the examples above can lead you to some misunderstanding. *What is root layout? The top-most layout is called the Root Layout. This required layout is shared across all pages in an application.* As you can see, the route folder in the two examples above always has a well-defined root layout. This means that the specific layouts we have defined for the various groups will not replace the root layout, but will be added to it. However, Route Groups also allow us to redefine the root layout. Specifically, they allow us to define different root layouts for different segments of pages. All we have to do is remove the common Root Layout file, create some Route groups, and re-define the different Root layout files for every group in the route folder: In this way, we will have pages with different root layouts, and our paths will once again not be affected by the folder name used in parentheses. Conclusion In conclusion, Next.js route groups offer a powerful and flexible solution for organizing and managing routes in your Next.js applications. By grouping related routes together, you can improve code organization, enhance maintainability, and promote code reusability. Route groups allow for the use of shared layout components, and the customization of root layouts for different segments of pages. With Next.js route groups, you can streamline your development process, create a more intuitive routing structure, and ultimately deliver a better user experience....

Feb 7, 2024

6 mins

NextJSReact

Improving INP in React and Next.js

Improving INP in React and Next.js In one of my previous articles, I've explained what INP is, how it works, and how it may affect your website. I also promised you to follow up with more concrete advice on how to improve your INP in your favorite framework. This is the follow-up article, where I'll focus on how to improve your INP score in React and Next.js. How to prepare for INP in React and Next.js? The first thing to do is to ensure you're using the latest version of React. The React team has been working on making React more INP-friendly and has already made some improvements in the latest versions. To enhance your INP score, consider fully taking advantage of new features introduced in React 18, such as Concurrent Rendering, Automatic Batching, and Selective Hydration. However, there are also some general areas to focus on, such as SSR and SSG in Next.js, Web Workers, or optimizing your hooks and state management. Concurrent Rendering The Concurrent Mode in React uses an algorithm that breaks rendering down into so-called "fiber nodes" and schedules the renders based on their expiration and priority. This effectively allows the user to interact with the page while the rendering is still in progress. In previous React versions, all updates, such as setState calls were treated as "urgent" and once the re-render had started, there was no way to interrupt it. Concurrent Mode changes this by being able to prioritize the updates and interrupt a non-blocking state update started with startTransition. For a simple explanation of concurrency in React, you can check out Dan Abramov's explanation. As part of the Concurrent Mode, React introduced several lifecycle methods that allow you to prioritize the rendering of certain parts of your UI, such as: - useTransition hook that allows you to update the state without blocking the UI, - useDeferredValue hook that allows you to defer the rendering of certain parts of your UI, - startTransition API that, similarly to the useTransition hook lets you mark a state update as non-blocking. It lacks, however, an indication of whether it's still pending. Automatic Batching Introduced in React 18, Automatic Batching reduces the number of re-renders that happen on state changes even when they happen outside of event handlers, e.g. in a setTimeout or Promise callback. This feature comes out of the box and you don't have to do anything to enable it, and it makes a great argument for upgrading to React 18. Selective Hydration Selective Hydration allows you to take hydration off the main thread by wrapping your components in a Suspense boundary. This way, components can become interactive faster as the browser can do other work on the main thread while the hydration is happening. To fully take advantage of selective hydration, consider the following: - Prioritizing Above-the-Fold Content: Use Suspense boundaries strategically around any parts of your application that may take the server longer to deliver to ensure they don’t block critical content from becoming interactive as soon as possible. - Hydration on Interaction: Implementing hydration upon user interaction for non-critical components can drastically reduce the main thread's workload, enhancing INP. Vercel even has a small case study showing how using selective hydration improved the performance of a Next.js site. Server-Side Rendering (SSR) and Static Site Generation (SSG) in Next.js Not everything has to run client-side. Next.js excels in SSR and SSG capabilities, which can significantly impact INP by delivering content to users faster. Optimizing SSR with techniques like incremental static regeneration (ISR) or leveraging SSG for static pages ensures that users can interact with content faster, improving the perceived performance. Workers Offloading heavy computations to Web Workers can free up the main thread, enhancing the responsiveness of React and Next.js applications. This strategy is especially useful when dealing with third-party scripts. Offloading such scripts in Next.js can be easily done by specifying the "worker" strategy on your Script component. Be aware that this feature is not yet stable and does not work with the app directory, though. If you want to take things one step further, you could use Partytown, which helps you offload any resource-intensive scripts to Web Workers. It comes with a React component that you can use to wrap your third-party scripts and offload them to a Web Worker, and it's compatible with Next.js as well. Hooks and State Management State management in React applications can easily get out of hand, leading to unnecessary re-renders and effectively an increased INP. Sometimes, using a state management library like Redux or MobX can help you consolidate your state and reduce the number of re-renders. However, they are not silver bullets and can also introduce performance issues if not used properly. If you are dealing with a lot of re-renders due to prop changes, make sure you are leveraging memoization. As of now, you may need to work with useMemo and useCallback hooks to memoize your values and functions, respectively. The upcoming React 19’s Forget Compiler, however, will apparently memoize everything under the hood, making these hooks obsolete. Using memoization properly can help you reduce the number of re-renders and improve your INP. To investigate your hook dependencies and re-renders, you can leverage React Developer Tools or use this handy helper hook I found on the internet to trace your re-renders: ` Conclusion Improving INP in React and Next.js is not easy and can require much investigation and fine-tuning. Still, it's worth doing to avoid being penalized by Google in its search results and provide a better experience for your users. Adopting React 18's new features, leveraging SSR and SSG in Next.js, utilizing Web Workers, and optimizing hooks and state management can significantly boost your INP score and deliver a faster application to your users. Remember, INP is just one among many performance metrics emphasizing the need for a comprehensive approach to performance optimization...

Apr 19, 2024

5 mins

Web PerformanceReactNextJSJavaScript

Level up your REST API's with JSON Schema

JSON Schema isn’t a hot topic that gets a lot of attention compared to GraphQL or other similar tools. I discovered the power of JSON Schema while I was building a REST API with Fastify. What is it exactly? The website describes it as “the vocabulary that enables JSON data consistency, validity, and interoperability at scale”. Or more simply, it’s a schema specification for JSON data. This article is going to highlight some of the benefits gained by defining a JSON Schema for a REST API. JSON Schema Basics Here’s an example of a simple schema representing a user: ` If you’re familiar with JSON already, you can probably understand most of this at a glance. This schema represents a JSON object with some properties that define a User in our system, for example. Along with the object’s properties, we can define additional metadata about the object. We can describe which fields are required and whether or not the schema can accept any additional properties that aren’t defined on the properties list. Types We covered a lot of types in our example schema. The root type of our JSON schema is an object with various properties defined on it. The base types available to define in your JSON Schema map to valid JSON types: object, array, string, number, integer, boolean. Check the type reference page to learn more. Formats The email property in our example has an additional field named format next to its type. The format property allows us to define a semantic identification for string values. This allows our schema definition to be more specific about the type of values allowed for a given field. “hello” is not a valid string value for our email type. Another common example is for date or timestamp values that get serialized. Validation implementations can use the format definition to make sure a value matches the expected type and format defined. There’s a section on the website that lists the various formats available for the string type. Schema Structuring JSON Schema supports referencing schemas from within a schema. This is a very important feature that helps us keep our schemas DRY. Looking back to our initial example we might want to define a schema for a list of users. We defined an id on our user schema of “user”, we can use this to reference that schema from another schema. ` In this example we have a simple schema that is just an array whose items definition references our user schema. This schema is exactly the same as if we defined our initial schema inside of "items": { }. The JSON Schema website has a page dedicated to structuring schemas. JSON Schema Benefits Validation One of the main benefits of defining a schema for your API is being able to validate inputs, outputs. Inputs include things like the request body, URL parameters, and search parameters. The output is your response JSON data or headers. There are some different libraries available to handle schema validation. A popular choice and the one used by Fastify is called Ajv. Security Validating inputs has some security advantages. It can prevent bad or malicious data from being accepted by your API. For instance, you can specify that a certain field must be an integer, or that a string must match a certain regex pattern. This can help prevent SQL injection, cross-site scripting (XSS). Defining a schema for your response types can help to prevent leaking sensitive data from your database. Your web server can be configured to not include any data that is not defined in the schema from your responses. Performance By validating data at the schema level, you can reject invalid requests early, before they reach more resource-intensive parts of your application. This can help protect against Denial of Service (DoS) attacks. fast-json-stringify is a library that creates optimized stringify functions from JSON schemas that can help improve response times and throughput for JSON API’s. Documentation JSON Schema also greatly aids in API documentation. Tools like OpenAPI and Swagger use JSON Schema to automatically generate human-readable API documentation. This documentation provides developers with clear, precise information about your API’s endpoints, request parameters, and response formats. This not only helps to maintain consistent and clear communication within your development team, but also makes your API more accessible to outside developers. Type-safety I plan to cover this in more detail in an upcoming post but there are tools available that can help achieve type-safety both on your server and client-side by pairing JSON Schema with TypeScript. In Fastify for example, you can infer types in your request handlers based on your JSON Schema specifications. Schema Examples I’ve taken some example schemas from the Fastify website to walk through how they would work in practice. ` ` We would use this schema to define, validate, and parse the query string of an incoming request in our API. Given a query string like: ?name=Dane&excitement=10&other=additional - we can expect to receive an object that looks like this: ` Since additionalProperties are not allowed, the other property that wasn’t defined on our schema gets parsed out. ` Imagining we had a route in our API defined like /users/:userId/posts/:slug ` Given this url: /users/1/posts/hello-world - we can expect to get an object in our handler that looks like this: ` We can be sure about this since the schema doesn’t allow for additional properties and both properties are required. If either field was missing or not matching its type, our API can automatically return a proper error response code. Just to highlight what we are getting here again. We are able to provide fine-grained schema definitions for all the inputs and outputs of our API. Aside from serving as documentation and specification, it powers validation, parsing, and sanitizing values. I’ve found this to be a very simple and powerful tool in my toolbox. Summary In this post, we've explored the power and functionality of JSON Schema, a tool that often doesn't get the spotlight it deserves. We've seen how it provides a robust structure for JSON data, ensuring consistency, validity, and interoperability on a large scale. Through our user schema example, we've delved into key features like types, formats, and the ability to structure schemas using references, keeping our code DRY. We've also discussed the substantial benefits of using JSON Schema, such as validation, enhanced security, improved performance, and the potential for type-safety. We've touched on useful libraries like Ajv for validation and fast-json-stringify for performance optimization. In a future post we will explore how we can utilize JSON Schema to achieve end-to-end type-safety in our applications....

Feb 16, 2024

5 mins

JSON

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

Join us backstage at CityJS Conf for this conversation with Jason Lengsdorf. In this discussion, we explore strategies for reducing stress and anxiety among engineers, ensuring they maintain relevance in the dynamic world of coding. Jason emphasizes the importance of self-assurance and the role of play in fostering continual engagement with evolving technologies. Moreover, we get a sneak peek into Jason's latest venture, "Web Lunch," a platform where he converses with developers who have found harmony between their careers and personal satisfaction. Coding isn't just a job; it's a passion and a lifestyle. Jason highlights the significance of pursuing work that excites and challenges us, echoing the sentiment that coding can be both a career and a hobby. By infusing enjoyment and creativity into our coding endeavors, we can shape our professional trajectories in alignment with our values and interests. This approach not only minimizes regret but also maximizes happiness and fulfillment in our careers. Central to our discussion is the pivotal role of effective leadership in creating a supportive and encouraging work environment. Leaders who prioritize the well-being and happiness of their team members foster a culture of collaboration and empowerment. Through mentorship, guidance, and opportunities for growth, these leaders enable developers to align their personal goals with organizational objectives, leading to increased job satisfaction and professional fulfillment. Adaptability is key to sustained success in software engineering. Jason emphasizes the value of remaining open-minded and continuously learning, even when it means stepping out of our comfort zones. Embracing discomfort is an integral part of personal growth, allowing us to overcome obstacles and unlock our full potential. By nurturing a spirit of curiosity and adaptability, developers can navigate the complexities of their careers with resilience and enthusiasm....

Apr 25, 2024

2 mins

JavaScriptMentorship

Building interactive forms with TanStack Form

Comparison to react-hook-form

Building forms

useForm(options)

useField(opts)

Component API

Async event handlers

Validation adapters

Conclusion

Dane Grant

You might also like

Next.js Route Groups

Improving INP in React and Next.js

Level up your REST API's with JSON Schema

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

You might also like

Next.js Route Groups

Improving INP in React and Next.js

Level up your REST API's with JSON Schema

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024