Angular

Make it Accessible: Better Layout with HTML

Published May 22, 2020

Updated Feb 14, 2023

5 min read

Make it Accessible - 8 Part Series

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

Make it Accessible: Better layouts with HTML

In this article, I'm going to teach you how to use the HTML tags <div>, <section> and <article>, and how they can improve your web applications accessibility.

Here you can access all the resources used in the article.

The Problem

Web applications are built with HTML, and even though it isn't a programming language, it is nontheless complex. One of the first issues you may encounter is knowing which element to use, and the huge amount of elements available makes this issue even more challenging.

When it comes to your page's layout, some of the options are; <div>, <section> and <article>. Today, you're going to learn when you should use each of them.

The Solution

First, we will conceptualize each of the elements I just mentioned. You can learn more about these in the w3c wai aria practices guide, but let's discuss those concepts here:

The <div> element is often used as a container for other HTML elements to style them with CSS or to perform certain tasks with JavaScript. w3schools.com

You may be tempted to use <div> with some styles instead of learning about the available elements in HTML5. I have to tell you, if you do that, you're hurting your users. Each element has a specific purpose, and you should be using the right element. <div> is useful when you want to group some elements and give them some styling, that doesn't mean you should make everything with <div>.

The <section> tag defines sections in a document, such as chapters, headers, footers, or any other sections of the document. w3school.com

This is a very important tag as you start your accessibility journey. It gives context to your users, specially those with Screen Readers. By "context", I mean that if you wrap a group of elements with a section and give it an accessible name, once users focus one of the elements, it reads the parent container too.

The <article> tag specifies independent, self-contained content. w3school.com

Almost every application has some kind of catalogue showing several items having the same styles, and if you think it through, these items could be placed anywhere without any context. Articles are cool for those cases, even though these aren't landmarks, it's common for Screen Readers to have a mechanism to allow users to navigate through articles easily.

The Implementation

Next, we're going to do a small sample using each of the mentioned elements. Let's start with the <div>.

Using divs right

Now that you are fully aware of the purpose of a <div>, it is time to use it. For this one, I decided to take the easy road and make a very simple example. Let's say you have multiple "things" you want to group, and to which you want to apply some additional styling. That can be easily done like this:

<html>
  <head>
    <style>
      .square {
        display: inline-block;
        width: 150px;
        height: 150px;
        border: 1px solid black;
        margin: 10px;
        background-color: white;
      }

      .group {
        display: inline-block;
        margin: 0;
        background-color: #bbb;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Using divs right</h1>
    </header>

    <main>
      <div class="group">
        <div class="square"></div>
        <div class="square"></div>
      </div>
      <div class="square"></div>
      <div class="square"></div>
      <div class="square"></div>
    </main>
  </body>
</html>

To test this, create a file with the .html extension containing what I just gave you, and open it with your preferred browser. You'll notice that the first two have a light gray background. Once again, very simple and easy to follow. Let's jump to the next example.

Sections are the way to go

For this one, I was looking for a more exciting example. Let's say you are building an application for a movie theater that allows customers to order tickets online. If you buy a ticket, you want to have a page where you can see all the details about the movie and your ticket.

Let's start by thinking it through. We want to see all the information about the movie, title, synopsis, a banner image, and a genre. When it comes to the ticket, I want to see its worth, my seat number, and the time left for the show to start.

The HTML for something like this would look like this:

<html>
  <head>
    <style>
      body {
        margin: 0;
        padding: 0;
      }

      main {
        display: flex;
        align-items: flex-start;
        justify-content: center;
        flex-wrap: wrap;
        background-color: #333;
        min-height: calc(100vh - 80px);
        margin-top: 80px;
      }

      header {
        position: absolute;
        height: 80px;
        color: white;
        background-color: #444;
        padding: 2px 0;
        text-align: center;
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        width: 100%;
        top: 0px;
      }

      .card {
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        display: inline-block;
        margin: 20px;
      }

      .movie-details {
        width: 400px;
      }

      .movie-details figure {
        width: 100%;
        margin: 0;
      }

      .movie-details figure img {
        width: 100%;
        object-fit: cover;
      }

      .container {
        padding: 10px;
        border: 1px solid #333;
        background-color: #444;
        color: white;
      }

      .ticket-summary {
        width: 250px;
      }

      .ticket-summary dt {
        color: #ccc;
        font-size: 1.1rem;
        font-weight: bold;
        margin-top: 8px;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Your Ticket Details</h1>
    </header>

    <main>
      <section class="card movie-details" aria-label="movie details">
        <figure>
          <img src="./img.jpg" alt="" />
        </figure>

        <div class="container">
          <h2 style="margin: 6px 0;">Parasite</h2>
          <p style="text-align: justify;">
            Greed and class discrimination threaten the newly formed symbiotic
            relationship between the wealthy Park family and the destitute Kim
            clan.
          </p>
          <p><b>Comedy, Drama</b></p>
        </div>
      </section>

      <section
        class="card ticket-summary"
        aria-labelledby="ticket-summary-title"
        aria-describedby="ticket-summary-description"
      >
        <div class="container">
          <h2
            id="ticket-summary-title"
            style="margin: 6px 0; text-align: center;"
          >
            Ticket Summary
          </h2>
          <p id="ticket-summary-description" style="text-align: justify;">
            Remember to exchange your ticket identifier for the actual ticket as
            soon as you get to the movie theater.
          </p>
          <dl>
            <dt>Identifier</dt>
            <dd>123</dd>
            <dt>Seat</dt>
            <dd>B-12</dd>
            <dt>Price</dt>
            <dd>$ 2,00 USD</dd>
            <dt>Starts in</dt>
            <dd>2h 30m</dd>
          </dl>
        </div>
      </section>
    </main>
  </body>
</html>

For now you can ignore the styles, it's just to make it look less ugly, what I want you to pay attention to is the HTML part. Look at how I created two sections- one for the movie details, and one for the ticket summary. Another important takeaway is how I used aria-label and aria-labelledby. Both have the same results, but in the movie details, I wanted to read "Movie Details" instead of the movie title, and in the case of the Ticket Summary, it's different because we want to read the same title.

By structuring your HTML document this way, using sections with the proper accessible names, you're not only giving context to the user, but you're creating a hierachical view of the landmarks of your application. This makes it easier for Screen Readers to understand your page, and as a consequence, you get better usability for your disabled users.

Articles are useful too

I know that example may have set the bar a little high. For this example, I'm doing something simpler. Let's say that this movie theater we are "working for" wants to show all the available movies to possible customers. This is where articles shine the most, because let's face it, no matter how many movies there are, all of them will have the same styles.

Let's roll up our sleeves, and create a new html file with this content:

<html>
  <head>
    <style>
      body {
        margin: 0;
        padding: 0;
      }

      main {
        display: flex;
        align-items: flex-start;
        justify-content: center;
        flex-wrap: wrap;
        background-color: #333;
        min-height: calc(100vh - 80px);
        margin-top: 80px;
      }

      header {
        position: absolute;
        height: 80px;
        color: white;
        background-color: #444;
        padding: 2px 0;
        text-align: center;
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        top: 0px;
        width: 100%;
      }

      .card {
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        display: inline-block;
        margin: 20px;
      }

      .movies {
        display: flex;
        justify-content: center;
        flex-wrap: wrap;
        width: 800px;
      }

      .feed {
        display: flex;
        margin-top: 10px;
      }

      .movie {
        width: 200px;
        height: 420px;
      }

      .movie figure {
        width: 100%;
        height: 300px;
        margin: 0;
        overflow: hidden;
      }

      .movie figure img {
        width: 100%;
        object-fit: cover;
        height: 100%;
      }

      .container {
        padding: 10px;
        height: 100px;
        border: 1px solid #333;
        background-color: #444;
        color: white;
      }

      .movie h2 {
        margin: 8px 0;
        font-size: 1.2rem;
        font-weight: bold;
      }

      .movie p {
        margin: 8px 0;
        font-style: italic;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Movies List</h1>
    </header>

    <main>
      <section class="movies" aria-label="available movies">
        <div role="feed" class="feed">
          <article
            class="movie card"
            aria-labelledby="movie-name-1"
            aria-describedby="movie-genre-1"
            tabindex="0"
            aria-posinset="1"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-1.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-1">The Shawshank Redemption</h2>
              <p id="movie-genre-1">Drama</p>
            </div>
          </article>
          <article
            class="movie card"
            aria-labelledby="movie-name-2"
            aria-describedby="movie-genre-2"
            tabindex="0"
            aria-posinset="2"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-2.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-2">The Godfather</h2>
              <p id="movie-genre-2">Crime, Drama</p>
            </div>
          </article>
          <article
            class="movie card"
            aria-labelledby="movie-name-3"
            aria-describedby="movie-genre-3"
            tabindex="0"
            aria-posinset="3"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-3.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-3">The Dark Knight</h2>
              <p id="movie-genre-3">Crime, Drama</p>
            </div>
          </article>
        </div>
      </section>
    </main>
  </body>
</html>

Remember to focus on the HTML structure, not the styles. The first time I saw this kind of code, I was like, wow, what's all that aria stuff doing? Today, I'm going to make this easier for you.

First of all, I have to remind you that all of these ideas come from the WAI ARIA Authoring Practice Guide.

One thing to notice before heading to the code is that a list of movies is a feed. Also, don't reinvent the wheel. The WAI ARIA guide has a very detailed description of how a feed should be implemented while prioritizing accessibility. You have to start with <div> and role="feed", next you have to work on the articles.

Setting up the feed container is very simple. What's not so straightforward are the articles themselves. Each of the aria properties has a specific purpose:

aria-labelledby: Title of the movie.
aria-describedby: Additional information about the movie.
aria-posinset: Position of the movie in the list.
aria-setsize: Size of the list of movies.

There's also a tabindex="0" because once in a feed, screen readers provide users with additional navigation mechanisms that require us to make the articles "focusable".

NOTE: All the <img> in the samples have an empty alt like this alt="". It's because using an empty alt tells screen readers to ignore the images entirely, in a real life project for images that provide information, you always give a proper alt value.

Conclusion

Every time I write one of these series, I come up with the same conclusion: Just use HTML! I'm even thinking of changing the name to "It's Already Accessible". It's common to hear developers saying that HTML is too simple. It might be for some, but you still have to learn it. Whenever you write an application, try to build it following patterns like the ones in WAI-ARIA. Make sure to follow their specifications, and you'll make applications all of your users will love.

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.

Testing Accessibility Features With Playwright

Testing Accessibility Features With Playwright In one of my previous posts, I mentioned the importance of having e2e tests to verify that your keyboard navigation works properly. I also suggested Playwright as a tool to write those tests. I owe you a little tutorial on how to do that. And because keyboard navigation is not the only accessibility feature you should test and since Playwright has some nice built-in tools for accessibility testing, I will also show you how to test other aspects of your website. What is Playwright? Let's start with a short introduction for those who don't know Playwright yet. Playwright is an open-source automation library developed by Microsoft, designed to enable developers and testers to write scripts that can control a web browser's behavior. It is a Node.js library that provides a high-level API to control headless Chrome, Firefox, and WebKit with a single interface. This means you can write your tests once and run them in multiple browsers, ensuring cross-browser compatibility. If you're new to Playwright, you can check out Dane's article, which nicely introduces the basics such as configuration or selectors, and presents some nice test examples. Keyboard Accessibility Testing Now, as promised, let's dive into keyboard accessibility testing with Playwright. As I already mentioned, keyboard navigation is one of the most important accessibility features to test, given that it can break anytime you add new functionality to your application and the problem can easily go unnoticed. It is also one of the easiest to test with Playwright because it provides a neat keyboard API that allows you to simulate keyboard input and verify that the correct elements are focused or activated. Verifying Element Focus To check which element is selected after a series of keyboard inputs, you can use the toBeFocused() method to check whether it is focused or not, like this: ` This code snippet simulates pressing the Tab key three times and then checks that an input is focused. It then presses the Tab key again, verifying that the input is no longer focused. If you read my previous article, you might remember that I mentioned that many websites have a bug that prevents you from tabbing out of a textbox. This simple test can catch this bug and prevent headaches for your users. Simulating Complex Keyboard Interactions Playwright's keyboard class provides a keyboard.press() method to simulate pressing a key and releasing it immediately. It allows you to simulate pressing a single key, a combination of keys, or a key combination with a modifier key: ` You can find the full list of keys you can pass to the keyboard.press function on MDN. If you need finer control over the keyboard, you can use the keyboard.down() and keyboard.up() methods to simulate pressing and releasing a key separately. One use case for this is to simulate pressing a key and holding it down for a certain amount of time, such as holding the Shift key to select multiple elements or lines of text: ` You can also use the keyboard.insertText() method to insert text into an element, but note that modifier keys _do not affect_ this method (e.g. holding down the Shift key will not type the text uppercase) and it only dispatches the input event and does not emit the keydown, keyup or keypress events. ` The keyboard API allows you to test keyboard input, keyboard shortcuts; and ensure that your application responds correctly to user input without a mouse. Although this might seem unnecessary, believe me when I say it is not. As I mentioned in my previous article, many applications try to implement keyboard navigation but contain a nasty bug that renders the effort useless. And it is worth spending some time writing a few simple e2e tests to avoid invalidating your efforts. Testing Other Accessibility Features This article focuses mostly on keyboard accessibility, but I have good news! You can easily test other accessibility aspects with Playwright too! It conveniently integrates with the axe accessibility testing engine using the @axe-core/playwright package to run automated accessibility tests. These tests can catch various issues, such as poor color contrast, missing labels on UI controls, and duplicate IDs that can confuse assistive technologies. Example Test for Entire Page Accessibility Here's how you can scan your entire page for accessibility issues using Playwright: ` Scanning Specific Page Sections You can also target specific parts of your page by using AxeBuilder.include() to focus the accessibility scan: ` Handling Known Accessibility Issues When you have known accessibility issues that you cannot immediately fix, Playwright allows you to exclude certain elements from scans or disable specific rules: ` Reporting Accessibility Issues If you want to report accessibility issues in your test results, you can use the testInfo.attach() method to attach the scan results to your test report: ` You can then use reporters to embed or link the scan results in your test output. Conclusion While your e2e tests should not serve as a replacement for manual testing and you should still check your app yourself to catch any issues that automated tests won't reveal, Playwright provides a convenient way to automate checks whether all of your website's accessibility features work as intended. It allows you to test keyboard navigation and other accessibility aspects such as color contrast or missing labels to make sure you aren't shipping a broken experience. Testing accessibility with Playwright requires little effort, and in my opinion, is very much worth it. So, if you haven't done so yet, I encourage you to give it a try! And if you're still unconvinced, read about how I broke my hand to appreciate the importance of accessibility....

Jan 31, 2024

5 mins

AccessibilityA11yTestingPlaywright

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

Welcome to a journey of discovery where we'll explore the often-overlooked capabilities of the Next.js Image component. At first glance, this component might seem like a straightforward tool, merely enhancing performance compared to a regular img tag. However, there's more to it than meets the eye. In this blog post, we'll uncover the magic of some features of the Next.js Image component. It's easy to use, yes, but it also packs a punch with features that go beyond simple image rendering. These hidden features can significantly impact your project, and missing them could mean not fully utilizing the component's potential. Let's dive into this exploration, unraveling the subtle yet powerful aspects of the Next.js Image component that are easy to overlook. So, without further delay, let's get started! Size First up, let's chat about width and height. These are rules for how big your image shows on the screen. You gotta use them most of the time. But hey, if you're pulling in an image directly into your code (that's what we call 'static importing') or you want your image to just fill up whatever space it's in (using the 'fill' prop), then you can skip these rules. Neat, right? But that's not all there's to it. You see, when Next.js fetches the image from the server, it does something behind the scenes. It doesn’t just grab any size of the image. Instead, Next.js is smart and picks the best size that fits the spot on your webpage. This means your images load faster and look just right, whether on a big desktop screen or a small phone screen. It's like having a personal assistant for your images, making sure they are always looking their best and not slowing down your site. Here's a part that's easy to miss: Next.js uses a feature called 'srcset' to decide which image size to download from the server. By default, Next.js uses the following default: ` So, imagine you have an image that's 75 pixels wide. Next.js will look at this list and pick the closest size. In our case, with these default settings, it would download the 96-pixel version. This occurs because Next.js selects the smallest available size from the list that exceeds the original's width, ensuring the image remains clear on all devices; even if your image is a bit smaller or larger, Next.js picks the nearest size from this list. This is important to know because if you are looking to get the most performant image possible, you should be aware of these size values. By understanding how Next.js selects the image size, you can better tailor your images to match these presets. This way, you ensure that your site is not only loading the appropriate image size for different devices but also optimizing for speed and efficiency. Keeping an eye on these sizes helps you balance between image quality and fast loading times, which is key for a great user experience on your site. Quality Now, let's highlight something about image quality. It's often overlooked, but by default, Next.js sets the image quality to 75. Sure, you can tweak this with the quality prop, but here's the catch: bumping up the quality to 100 will significantly increase the image's file size. This means your images will look super sharp, but they'll also take longer to load. It's all about finding that sweet spot where your images look great without slowing down your website. Remember, a faster site often means a better experience for your visitors. My advice is to always check what is better for you in each situation. Ask yourself: Consider whether it's more beneficial to opt for larger images at a slightly reduced quality, in alignment with the “srcset” configurations we explored, or if it's preferable to enhance the image quality, even if it means working with smaller dimensions? It's a balancing act. Usually, cranking up the quality to 100 isn't the best move because it makes the image file really big, which can slow down your site. It's all about making smart choices. Go for a quality that makes your images look good without burdening your site's load time. Sometimes, a slightly lower quality image, but well optimized, can be way more effective than a perfect but sluggish, high-quality image. Loader The loader prop in Next.js is a key player. It's not just about fetching images; it’s about fetching them smartly and securely. When using images from different places, like a CMS or your server, the loader prop helps you manage them efficiently and safely. For instance, say you have images on Contentful. Next.js doesn't automatically know the best way to fetch these, but with a custom loader, you can define this process. This loader optimizes your images, selecting the right format, width, and quality. Your images not only look great but load faster, too. Remember, when fetching images from external sources, it's crucial to use remotePatterns (inside your next.config file) for security reasons. This ensures your site stays safe while handling images from outside. This approach is scalable and saves time. You set up the loader once, and it works for all your images, making your site efficient and your code neat. Here’s an example: ` ` Placeholder Prop A little-known yet impactful feature of the Next.js Image component is the placeholder prop. It's all about improving the user experience while your images are loading. Imagine visiting a website and waiting for images to load – it can be a bit dull, right? The placeholder prop can make this wait a lot more pleasant. You can use this prop to display a blur effect or a solid color before the image fully loads. This creates a smoother visual experience. The blur placeholder is particularly popular because it gives a sneak peek of the image without revealing all the details. It's like a teaser, building anticipation for what's to come. Here’s how you can use it: ` In this example, blurDataURL is a small, low-quality version of your image that loads much faster. Once the actual image is ready, it seamlessly replaces the blur. This approach significantly enhances the perceived loading speed and keeps your users engaged. Incorporating the placeholder prop can make a big difference in how professional and polished your site feels, especially on slower connections where image load times are noticeable. Conclusion The Next.js Image component is a powerful tool that goes beyond simple image rendering. By understanding its hidden features and capabilities, you can optimize your project for performance and user experience. From utilizing the 'width' and 'height' properties to ensuring the right image quality and using the 'loader' prop for efficient image fetching, there are several aspects to consider. Additionally, the 'placeholder' prop can enhance the user experience by displaying a blur effect or solid color while images load. By exploring these often-overlooked features, you can unlock the full potential of the Next.js Image component and create a more engaging and optimized website....

Feb 9, 2024

5 mins

UXJavaScriptNextJS

AI Leadership: Data-Driven Decision Making & Avoiding "Analysis Paralysis" with Jerry Reghunadh

In this episode of Leadership Exchange, host Rob Ocel chats with Jerry Reghunadh, Senior Director of Enterprise Architecture at Data Nimbus, about leadership, AI adoption, and data-driven decision-making. Jerry shares his career journey, insights on leveraging tools like ChatGPT and Copilot, and strategies for building effective data pipelines. They explore how companies can avoid "analysis paralysis," adopt AI strategically, and evaluate new technologies to solve real-world problems. Tune in for practical advice on aligning innovation with business goals and staying competitive in a rapidly evolving tech landscape. Chapters 00:00 – Introduction 00:31 – Jerry’s Leadership Journey 02:01 – Discussing AI in Leadership 03:59 – Experimenting with AI Tools 06:24 – Overcoming Analysis Paralysis 09:18 – Importance of Early AI Adoption 13:12 – AI’s Impact on Efficiency 14:30 – Sponsor Message 16:26 – Setting Realistic Goals for AI 19:41 – Data Management and AI 23:09 – Is AI Just a Fad? 27:22 – Testing New Technologies 29:56 – Final Thoughts on AI 30:25 – Connect with Jerry 30:44 – Closing Remarks 31:20 – Outro Follow Jerry on Social Media Linkedin: https://www.linkedin.com/in/jerrymannel/ Sponsored by This Dot: thisdot.co...

Nov 18, 2024

1 min

AIEngineering Leadership

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Make it Accessible: Better Layout with HTML

Make it Accessible - 8 Part Series

Make it Accessible: Better layouts with HTML

The Problem

The Solution

The Implementation

Using divs right

Sections are the way to go

Articles are useful too

Conclusion

You might also like

Testing Accessibility Features With Playwright

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

AI Leadership: Data-Driven Decision Making & Avoiding "Analysis Paralysis" with Jerry Reghunadh

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

Testing Accessibility Features With Playwright

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

AI Leadership: Data-Driven Decision Making & Avoiding "Analysis Paralysis" with Jerry Reghunadh

Introduction to Zod for Data Validation