ReactJS

Creating Custom Scrollbars with React

Published Jan 14, 2022

Updated Nov 22, 2023

6 min read

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.

Styling scrollbars is no simple task. The CSS available to style them is different across browsers, and not very featureful. If you want to make something extremely customized, you can't rely on the native scrollbars—you have to build your own out of DOM elements. This blog post shows you how to do just that using React and TypeScript. If you want to skip straight to the final functional demo, go here.

Structure of a Scrollbar

A scroll bar has two main components: a thumb (this piece you click and drag to scroll) and a track (the space within which the thumb moves). The size of the thumb usually gives a hint to how large the visible content is in relation to the total size of the content. That is to say, the smaller the thumb, the more content there is outside of the current view. Thumb position on the track tells you how much off-screen content there is in each scroll direction. Scrollbars sometimes also have buttons on the ends that you can click to scroll a set amount in a certain direction, though these aren't seen as often as they used to be. We'll be recreating both of these user interface elements with div elements.

Hide Native Scrollbars

Before we create our custom scrollbars, we'll need to hide the native browser scrollbars to prevent interference. This is easily accomplished with a bit of CSS. We're also including overflow: auto, because we want to make sure that out content is still scrollable even if we can't see the native scrollbars.

.custom-scrollbars__content {
  overflow: auto;
  scrollbar-width: none;
  -ms-overflow-style: none;
}

.custom-scrollbars__content::-webkit-scrollbar {
  display: none;
}

Custom Scrollbar Functionality

Laying out Scrollbar Elements

The content we want to scroll and the scrollbar itself will go inside a wrapper div. That div will have two children: another div containing the content, and a div containing our scrollbar.

The scrollbar div will contain a button to scroll up, the elements of the thumb and track inside a wrapper div, and another button to scroll down. In the example below, they've been given classes (remember, we're using React, so we're using className) to help identify them.

<div className="custom-scrollbars__container">
  <div className="custom-scrollbars__content">
    {children}
  </div>
  <div className="custom-scrollbars__scrollbar">
    <button className="custom-scrollbars__button">⇑</button>
    <div className="custom-scrollbars__track-and-thumb">
      <div className="custom-scrollbars__track"></div>
      <div className="custom-scrollbars__thumb"></div>
    </div>
    <button className="custom-scrollbars__button">⇓</button>
  </div>
</div>

The track and thumb elements are siblings and will both be positioned absolutely with CSS. The top style of the thumb will be modified with JavaScript. It's better to have these two side-by-side and positioned absolutely, rather than have the thumb as a child of the track, because it prevents any ambiguity about whether you've clicked one or the other. If you click and drag the thumb, but drag so fast that your cursor is over the track when you realease it, it's possible, when nesting them, to accidentally trigger a click event on the track. That would could weird scrolling bugs. Keeping them as siblings prevents that.

.custom-scrollbars__track-and-thumb {
  display: block;
  height: 100%;  /* must have some height */
  position: relative;
  width: 16px; /* must have some width */
}

/* The track is meant to fill the space it's given, so top and bottom are set to 0. */
.custom-scrollbars__track {
  bottom: 0;
  cursor: pointer;
  position: absolute;
  top: 0;
  width: 16px; /* must have some width */
}

/* No top or bottom set for the thumb. That will be controlled by JavaScript. */
.custom-scrollbars__thumb {
  position: absolute;
  width: 16px; /* must have some width */
}

Sizing the Thumb

Your content may change size from initial render, due to data fetch requests completing or for other reasons. The size of the thumb needs to be able to adjust to match whatever the current content's size is.

Because the content resizing won't necessarily result in the window resizing, we'll use a ResizeObserver to what for changes in just the content size.

We store references to the content element, the track, the thumb, and the resize observer with useRef. Our handleResize() function computes the ratio of visible content to total scrollable content (clientHeight / scrollHeight) of the content container, then multiplies it by the track's height to get a height for the thumb. We set a minimum of 20 pixels for the height in case the content is so long that the thumb would otherwise be too small to click. The thumb's height is finally stored in React state.

A useEffect sets an initial height, then creates a ResizeObserver to watch the size of the content, and trigger the handleResize() function again if it occurs.

import React, { useState, useEffect, useRef } from 'react';

const Scrollbar = ({
  children,
  className,
  ...props
}: React.ComponentPropsWithoutRef<'div'>) => {
  const contentRef = useRef<HTMLDivElement>(null);
  const scrollTrackRef = useRef<HTMLDivElement>(null);
  const scrollThumbRef = useRef<HTMLDivElement>(null);
  const observer = useRef<ResizeObserver | null>(null);
  const [thumbHeight, setThumbHeight] = useState(20);

  function handleResize(ref: HTMLDivElement, trackSize: number) {
    const { clientHeight, scrollHeight } = ref;
    setThumbHeight(Math.max((clientHeight / scrollHeight) * trackSize, 20));
  }

  // If the content and the scrollbar track exist, use a ResizeObserver to adjust height of thumb and listen for scroll event to move the thumb
  useEffect(() => {
    if (contentRef.current && scrollTrackRef.current) {
      const ref = contentRef.current;
      const {clientHeight: trackSize} = scrollTrackRef.current;
      observer.current = new ResizeObserver(() => {
        handleResize(ref, trackSize);
      });
      observer.current.observe(ref);
      return () => {
        observer.current?.unobserve(ref);
      };
    }
  }, []);

  return (
    <div className="custom-scrollbars__container">
      <div className="custom-scrollbars__content" ref={contentRef} {...props}>
        {children}
      </div>
      <div className="custom-scrollbars__scrollbar">
        <button className="custom-scrollbars__button">⇑</button>
        <div className="custom-scrollbars__track-and-thumb">
          <div className="custom-scrollbars__track"></div>
          <div
            className="custom-scrollbars__thumb"
            ref={scrollThumbRef}
            style={{
              height: `${thumbHeight}px`,
            }}
          ></div>
        </div>
        <button className="custom-scrollbars__button">⇓</button>
      </div>
    </div>
  );
};

export default Scrollbar;

Handle the Position of the Thumb

When we scroll, the thumb should move in proportion to our scrolling. We'll do this with a useCallback that is called on the scroll event. We take the proportion of how far the content has been scrolled (scrollTop) to the total scrollable area (scrollHeight), and multiply it by the track's height to get the new position of the top edge of the thumb. To make sure the thumb doesn't fly off the end of the track, we cap the top position to no more than the difference between the track's height and the thumb's height.

- import React, { useState, useEffect, useRef } from 'react';
+ import React, { useState, useEffect, useRef, useCallback } from 'react';

const handleThumbPosition = useCallback(() => {
  if (
    !contentRef.current ||
    !scrollTrackRef.current ||
    !scrollThumbRef.current
  ) {
    return;
  }
  const { scrollTop: contentTop, scrollHeight: contentHeight } =
    contentRef.current;
  const { clientHeight: trackHeight } = scrollTrackRef.current;
  let newTop = (+contentTop / +contentHeight) * trackHeight;
  newTop = Math.min(newTop, trackHeight - thumbHeight);
  const thumb = scrollThumbRef.current;
  thumb.style.top = `${newTop}px`;
}, []);

useEffect(() => {
  if (contentRef.current && scrollTrackRef.current) {
    const ref = contentRef.current;
    const {clientHeight: trackSize} = scrollTrackRef.current;
    observer.current = new ResizeObserver(() => {
      handleResize(ref, trackSize);
    });
    observer.current.observe(ref);
+   ref.addEventListener('scroll', handleThumbPosition);
    return () => {
      observer.current.unobserve(ref);
+     ref.removeEventListener('scroll', handleThumbPosition);
    };
  }
}, []);

Handle Clicking the Buttons

Wiring the up and down scroll buttons is very straightforward. We simply create a function that accepts a direction, and scrolls the content by a fixed amount in that direction. Keep in mind that in browsers, the y axis is positive going from top to bottom. That means scrolling down would mean a positive number of pixels, and up would be negative. Then we add this function to the onClick of our buttons.

function handleScrollButton(direction: 'up' | 'down') {
  const { current } = contentRef;
  if (current) {
    const scrollAmount = direction === 'down' ? 200 : -200;
    current.scrollBy({ top: scrollAmount, behavior: 'smooth' });
  }
}

<button
  className="custom-scrollbars__button"
+ onClick={() => handleScrollButton('up')}
>
  ⇑
</button>

...

<button
  className="custom-scrollbars__button"
+ onClick={() => handleScrollButton('down')}
>
  ⇓
</button>

Handle Clicking the Track

In most scrollbars, clicking on the scroll track will jump the thumb ahead in that direction. We'll once again useCallback to handle clicking on the track and updating the content's scroll position. The following snippet and comments walk through the steps of figuring out the new position for the content to scroll to.

const handleTrackClick = useCallback(
  (e) => {
    e.preventDefault();
    e.stopPropagation();
    const { current: trackCurrent } = scrollTrackRef;
    const { current: contentCurrent } = contentRef;
    if (trackCurrent && contentCurrent) {
      // First, figure out where we clicked
      const { clientY } = e;
      // Next, figure out the distance between the top of the track and the top of the viewport
      const target = e.target as HTMLDivElement;
      const rect = target.getBoundingClientRect();
      const trackTop = rect.top;
      // We want the middle of the thumb to jump to where we clicked, so we subtract half the thumb's height to offset the position
      const thumbOffset = -(thumbHeight / 2);
      // Find the ratio of the new position to the total content length using the thumb and track values...
      const clickRatio =
        (clientY - trackTop + thumbOffset) / trackCurrent.clientHeight;
      // ...so that you can compute where the content should scroll to.
      const scrollAmount = Math.floor(
        clickRatio * contentCurrent.scrollHeight
      );
      // And finally, scroll to the new position!
      contentCurrent.scrollTo({
        top: scrollAmount,
        behavior: 'smooth',
      });
    }
  },
  [thumbHeight]
);

<div
  className="custom-scrollbars__track"
  ref={scrollTrackRef}
+ onClick={handleTrackClick}
></div>

Handle Dragging the Thumb

At last, the hardest part: clicking and dragging the thumb to scroll. To do this, we write three functions to handle mousedown, mousemove, and mouseup events. We'll track whether or not we're actively dragging, where the mouse was when we started dragging, and where the scroll position of the content was where we started dragging with React state.

The handleThumbMouseup() function is simplest: it simply sets isDragging to false so we know we're not dragging the thumb anymore.

handleThumbMousedown does a bit more. In addition to setting isDragging to true, it records the mouse's y position, and the content's scrollTop when you click down, and sets them to scrollStartPosition and initialScrollTop respectively. We will use these values to calculate the new scrollTop for the content.

The handleThumbMousemove() function is the trickiest. First, we figure out how far the mouse now is (e.clientY) from where it was when we started (scrollStartPosition). This tells us the absolute number of pixels the thumb should have moved up or down. But we've decoupled the size of the content's container from the size of the scrollbar track, so pixels of thumb scrolling doesn't equal the number of pixels the content should scroll. (E.g., if the total content length is 7 times longer than the height of the track, then dragging the thumb by one pixel should scroll the content by 7 pixels.) To scale the value, we multiply it by the ratio of the content's height to the thumb's height. Finally, set calculate the new scrollTop and set it to the content. The thumb's position will take care of itself thanks to handleThumbPosition() being called by the scroll event listener on the content.

  const contentRef = useRef<HTMLDivElement>(null);
  const scrollTrackRef = useRef<HTMLDivElement>(null);
  const scrollThumbRef = useRef<HTMLDivElement>(null);
  const observer = useRef<ResizeObserver | null>(null);
  const [thumbHeight, setThumbHeight] = useState(20);
+ const [scrollStartPosition, setScrollStartPosition] = useState<number | null>(
    null
  );
+ const [initialScrollTop, setInitialScrollTop] = useState<number>(0);
+ const [isDragging, setIsDragging] = useState(false);

const handleThumbMousedown = useCallback((e) => {
  e.preventDefault();
  e.stopPropagation();
  setScrollStartPosition(e.clientY);
  if (contentRef.current) setInitialScrollTop(contentRef.current.scrollTop);
  setIsDragging(true);
}, []);

const handleThumbMouseup = useCallback(
  (e) => {
    e.preventDefault();
    e.stopPropagation();
    if (isDragging) {
      setIsDragging(false);
    }
  },
  [isDragging]
);

const handleThumbMousemove = useCallback(
  (e) => {
    e.preventDefault();
    e.stopPropagation();
    if (isDragging) {
      const {
        scrollHeight: contentScrollHeight,
        offsetHeight: contentOffsetHeight,
      } = contentRef.current;

      // Subtract the current mouse y position from where you started to get the pixel difference in mouse position. Multiply by ratio of visible content height to thumb height to scale up the difference for content scrolling.
      const deltaY =
        (e.clientY - scrollStartPosition) *
        (contentOffsetHeight / thumbHeight);
      const newScrollTop = Math.min(
        initialScrollTop + deltaY,
        contentScrollHeight - contentOffsetHeight
      );

      contentRef.current.scrollTop = newScrollTop;
    }
  },
  [isDragging, scrollStartPosition, thumbHeight]
);

// Listen for mouse events to handle scrolling by dragging the thumb
useEffect(() => {
  document.addEventListener('mousemove', handleThumbMousemove);
  document.addEventListener('mouseup', handleThumbMouseup);
  document.addEventListener('mouseleave', handleThumbMouseup);
  return () => {
    document.removeEventListener('mousemove', handleThumbMousemove);
    document.removeEventListener('mouseup', handleThumbMouseup);
    document.removeEventListener('mouseleave', handleThumbMouseup);
  };
}, [handleThumbMousemove, handleThumbMouseup]);

<div className="custom-scrollbars__track-and-thumb">
  <div
    className="custom-scrollbars__track"
    ref={scrollTrackRef}
    onClick={handleTrackClick}
+   style={{ cursor: isDragging ? 'grabbing' : 'pointer' }}
  ></div>
  <div
    className="custom-scrollbars__thumb"
    ref={scrollThumbRef}
+   onMouseDown={handleThumbMousedown}
    style={{
      height: `${thumbHeight}px`,
+     cursor: isDragging ? 'grabbing' : 'grab',
    }}
  ></div>
</div>

Full Code and Demo

That's it! You've now got a completely custom scrollbar in React and TypeScript using DOM elements instead of native scrollbars. You can customize these scrollbars with any kind of CSS you like!

You can see the full code here and play around with the demo.

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.

About the author(s)

Tom VanAntwerp
@tvanantwerp @tvanantwerp

D1 SQLite: Writing queries with the D1 Client API

Writing queries with the D1 Client API In the previous post we defined our database schema, got up and running with migrations, and loaded some seed data into our database. In this post we will be working with our new database and seed data. If you want to participate, make sure to follow the steps in the first post. We’ve been taking a minimal approach so far by using only wrangler and sql scripts for our workflow. The D1 Client API has a small surface area. Thanks to the power of SQL, we will have everything we need to construct all types of queries. Before we start writing our queries, let's touch on some important concepts. Prepared statements and parameter binding This is the first section of the docs and it highlights two different ways to write our SQL statements using the client API: prepared and static statements. Best practice is to use prepared statements because they are more performant and prevent SQL injection attacks. So we will write our queries using prepared statements. We need to use parameter binding to build our queries with prepared statements. This is pretty straightforward and there are two variations. By default we add ? ’s to our statement to represent a value to be filled in. The bind method will bind the parameters to each question mark by their index. The first ? is tied to the first parameter in bind, 2nd, etc. I would stick with this most of the time to avoid any confusion. ` I like this second method less as it feels like something I can imagine messing up very innocently. You can add a number directly after a question mark to indicate which number parameter it should be bound to. In this exampl, we reverse the previous binding. ` Reusing prepared statements If we take the first example above and not bind any values we have a statement that can be reused: ` Querying For the purposes of this post we will just build example queries by writing them out directly in our Worker fetch handler. If you are building an app I would recommend building functions or some other abstraction around your queries. select queries Let's write our first query against our data set to get our feet wet. Here’s the initial worker code and a query for all authors: ` We pass our SQL statement into prepare and use the all method to get all the rows. Notice that we are able to pass our types to a generic parameter in all. This allows us to get a fully typed response from our query. We can run our worker with npm run dev and access it at http://localhost:8787 by default. We’ll keep this simple workflow of writing queries and passing them as a json response for inspection in the browser. Opening the page we get our author results. joins Not using an ORM means we have full control over our own destiny. Like anything else though, this has tradeoffs. Let’s look at a query to fetch the list of posts that includes author and tags information. ` Let’s walk through each part of the query and highlight some pros and cons. ` * The query selects all columns from the posts table. * It also selects the name column from the authors table and renames it to author_name. * It aggregates the name column from the tags table into a JSON array. If there are no tags, it returns an empty JSON array. This aggregated result is renamed to tags. ` * The query starts by selecting data from the posts table. * It then joins the authors table to include author information for each post, matching posts to authors using the author_id column in posts and the id column in authors. * Next, it left joins the posts_tags table to include tag associations for each post, ensuring that all posts are included even if they have no tags. * Next, it left joins the tags table to include tag names, matching tags to posts using the tag_id column in posts_tags and the id column in tags. * Finally, group the results by the post id so that all rows with the same post id are combined in a single row SQL provides a lot of power to query our data in interesting ways. JOIN ’s will typically be more performant than performing additional queries.You could just as easily write a simpler version of this query that uses subqueries to fetch post tags and join all the data by hand with JavaScript. This is the nice thing about writing SQL, you’re free to fetch and handle your data how you please. Our results should look similar to this: ` This brings us to our next topic. Marshaling / coercing result data A couple of things we notice about the format of the result data our query provides: Rows are flat. We join the author directly onto the post and prefix its column names with author. ` Using an ORM we might get the data back as a child object: ` Another thing is that our tags data is a JSON string and not a JavaScript array. This means that we will need to parse it ourselves. ` This isn’t the end of the world but it is some more work on our end to coerce the result data into the format that we actually want. This problem is handled in most ORM’s and is their main selling point in my opinion. insert / update / delete Next, let’s write a function that will add a new post to our database. ` There’s a few queries involved in our create post function: * first we create the new post * next we run through the tags and either create or return an existing tag * finally, we add entries to our post_tags join table to associate our new post with the tags assigned We can test our new function by providing post content in query params on our index page and formatting them for our function. ` I gave it a run like this: http://localhost:8787authorId=1&tags=Food%2CReview&title=A+review+of+my+favorite+Italian+restaurant&content=I+got+the+sausage+orchette+and+it+was+amazing.+I+wish+that+instead+of+baby+broccoli+they+used+rapini.+Otherwise+it+was+a+perfect+dish+and+the+vibes+were+great And got a new post with the id 11. UPDATE and DELETE operations are pretty similar to what we’ve seen so far. Most complexity in your queries will be similar to what we’ve seen in the posts query where we want to JOIN or GROUP BY data in various ways. To update the post we can write a query that looks like this: ` COALESCE acts similarly to if we had written a ?? b in JavaScript. If the binded value that we provide is null it will fall back to the default. We can delete our new post with a simple DELETE query: ` Transactions / Batching One thing to note with D1 is that I don’t think the traditional style of SQLite transactions are supported. You can use the db.batch API to achieve similar functionality though. According to the docs: Batched statements are SQL transactions ↗. If a statement in the sequence fails, then an error is returned for that specific statement, and it aborts or rolls back the entire sequence. ` Summary In this post, we've taken a hands-on approach to exploring the D1 Client API, starting with defining our database schema and loading seed data. We then dove into writing queries, covering the basics of prepared statements and parameter binding, before moving on to more complex topics like joins and transactions. We saw how to construct and execute queries to fetch data from our database, including how to handle relationships between tables and marshal result data into a usable format. We also touched on inserting, updating, and deleting data, and how to use transactions to ensure data consistency. By working through these examples, we've gained a solid understanding of how to use the D1 Client API to interact with our database and build robust, data-driven applications....

Dec 23, 2024

6 mins

JavaScript

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

Understanding the Difference Between :focus and :focus-visible in CSS I have learned my fair share about the importance of keyboard accessibility, so I know that visual indication of the focused element is very important. But the well-known :focus pseudo-class is not always the best fit for this job. That's where :focus-visible comes in. Let's look at the differences between these two pseudo-classes and explore the best practices for using them effectively. What is the :focus Pseudo-Class? The :focus pseudo-class is a CSS selector that applies styles to any element that receives focus, regardless of how that focus was triggered. This includes focus events from keyboard navigation, mouse clicks, and touch interactions. Example Usage of :focus ` In this example, the button will display a blue outline whenever it is focused, whether the user clicks on it with a mouse, taps it on a touchscreen, or navigates to it using the keyboard. What is the :focus-visible Pseudo-Class? The :focus-visible pseudo-class is more specialized. It only applies styles to an element when the browser determines that the focus should be visible. This typically occurs when the user navigates via the keyboard or assistive technologies rather than through mouse or touch input. Example Usage of :focus-visible ` Here, the button will only show a blue outline when focused through keyboard navigation or another input method that usually requires visible focus indicators. Key Differences Between :focus and :focus-visible :focus - Behavior: Applies to any element that receives focus, regardless of the input method. - Use Cases: Ensures that all interactions with the element are visually indicated, whether by mouse, keyboard, or touch. :focus-visible - Behavior: Applies styles only when the focus should be visible, such as using a keyboard or assistive technology. - Use Cases: Ideal for scenarios where you want to provide focus indicators only to keyboard and assistive technology users while avoiding unnecessary outlines for mouse and touch users, typically required by design. Accessibility Implications :focus - Pros: - Guarantees that all users can see when an element is focused, which is critical for accessibility. - Cons: - Can lead to a suboptimal experience for mouse users, as focus styles may appear unnecessarily during mouse interactions. :focus-visible - Pros: - Enhances user experience by showing focus indicators only when necessary, thus keeping the interface clean for mouse and touch users. - Tailors the experience for keyboard and assistive technology users, providing them with clear visual cues. - Cons: - Additional considerations may be required to ensure that focus indicators are not accidentally omitted, especially in older browsers that do not support :focus-visible. - There may be cases where you want to show focus indicators for all users, regardless of input method. Best Practices for Using :focus and :focus-visible To achieve the best accessibility and user experience, combining both :focus and :focus-visible in your CSS is often a good idea. Combining :focus and :focus-visible ` Here is a Stackblitz example of what such styling could look like for you to try out and play with. Additional Tips - Test with Keyboard and Assistive Technology: Ensure that your web application is navigable using a keyboard (Tab, Shift + Tab, etc.) and that focus indicators are visible for those who rely on them. It's never a bad idea to include accessibility testing in your e2e testing suite. - Provide Clear Focus Indicators: Make sure that focus indicators are prominent and easy to see. A subtle or hard-to-spot focus indicator can severely impact accessibility for users who rely on keyboard navigation. Conclusion The :focus-visible pseudo-class offers a more refined way to manage focus indicators, improving accessibility and user experience, particularly for keyboard and assistive technology users. By understanding the differences between :focus and :focus-visible, and applying best practices in your CSS, you can create more accessible and user-friendly web applications. Remember, accessibility should never be an afterthought. By thoughtfully applying focus styles, you ensure that all users, regardless of how they interact with your site, can easily navigate and interact....

Nov 8, 2024

3 mins

AccessibilityCSSPlaywright

JavaScript Errors: An Introductory Primer

JavaScript Errors are an integral part of the language, and its runtime environment. They provide valuable feedback when something goes wrong during the execution of your script. And once you understand how to use and handle Errors, you'll find them a much better debugging tool than always reaching for console.log. Why Use Errors? When JavaScript throws errors, it's usually because there's a mistake in the code. For example, trying to access properties of null or undefined would throw a TypeError. Or trying to use a variable before it has been declared would throw a ReferenceError. But these can often be caught before execution by properly linting your code. More often, you'll want to create your own errors in your programs to catch problems unique to what you're trying to build. Throwing your own errors can make it easier for you to interrupt the control flow of your code when necessary conditions aren't met. Why would you want to use Error instead of just console.logging all sorts of things? Because an Error will force you to address it. JavaScript is optimistic. It will do its best to execute despite all sorts of issues in the code. Just logging some problem might not be enough to notice it. You could end up with subtle bugs in your program and not know! Using console.log won't stop your program from continuing to execute. An Error, however, interrupts your program. It tells JavaScript, "we can't proceed until we've fixed this problem". And then JavaScript happily passes the message on to you! Using Errors in JavaScript Here's an example of throwing an error: ` When an Error is thrown, nothing after that throw in your scope will be executed. JavaScript will instead pass the Error to the nearest error handler higher up in the call stack. If no handler is found, the program terminates. Since you probably don't want your programs to crash, it's important to set up Error handling. This is where something like try / catch comes in. Any code you write inside the try will attempt to execute. If an Error is thrown by anything inside the try, then the following catch block is where you can decide how to handle that Error. ` In the catch block, you receive an error object (by convention, this is usually named error or err, but you could give it any name) which you can then handle as needed. Asynchronous Code and Errors There are two ways to write asynchronous JavaScript, and they each have their own way of writing Error handling. If you're using async / await, you can use the try / catch block as in the previous example. However, if you're using Promises, you'll want to chain a catch to the Promise like so: ` Understanding the Error Object The Error object is a built-in object that JavaScript provides to handle runtime errors. All types of errors inherit from it. Error has several useful properties. - message: Probably the most useful of Error's properties, message is a human-readable description of the error. When creating a new Error, the string you pass will become the message. - name: A string representing the error type. By default, this is Error. If you're using a built-in sub-class of Error like TypeError, it will be that instead. Otherwise, if you're creating a custom type of Error, you'll need to set this in the constructor. - stack: While technically non-standard, stack is a widely supported property that gives a full stack trace of where the error was created. - cause: This property allows you to give more specific data when throwing an error. For example, if you want to add a more detailed message to a caught error, you could throw a new Error with your message and pass the original Error as the cause. Or you could add structured data for easier error analysis. Creating an Error object is quite straightforward: ` In addition to the generic Error, JavaScript provides several built-in sub-classes of Error: - EvalError: Thrown when a problem occurs with the eval() function. This only exists for backwards compatibility, and will not be thrown by JavaScript. You shouldn't use eval() anyway. - InternalError: Non-standard error thrown when something goes wrong in the internals of the JavaScript engine. Really only used in Firefox. - RangeError: Thrown when a value is not within the expected range. - ReferenceError: Thrown when a value doesn't exist yet / hasn't been initialized. - SyntaxError: Thrown when a parsing error occurs. - TypeError: Thrown when a variable is not of the expected type. - URIError: Thrown when using a global URI handling function incorrectly. Each of these error types inherits from the Error object and generally adds no additional properties or methods, but they do change the name property to reflect the error type. Making Your Own Custom Errors It's sometimes useful to extend the Error object yourself! This lets you add properties to particular Errors you throw, as well as easily check in catch blocks if an Error is of a particular type. To extend Error, use a class. ` In this example, CustomError extends the Error class. It changes the name to CustomError and gives it the new property foo: 'bar'. You can then throw your CustomError, check if the error in your catch block is an instance of the CustomError, and access the properties associated with your CustomError. This gives you a lot more control over how Errors are structured and validated, which could greatly aid with debugging because your errors won't all just be Errors. Common Confusions There are many ways that using Errors can go subtly wrong. Here are some of the common issues to keep in mind when working with Error. Failure to Catch When an Error is thrown, the program will cease executing anything else in its scope and start working its way back up the call stack until it finds a catch block to deal with the Error. If it never finds a catch, the program will crash. So it's important to make sure you actually catch your errors, or else you might terminate your program unintentionally for small and recoverable issues. It's especially helpful to think about catching errors when you're executing code from external libraries which you don't control. You may import a function to handle something for you, and it unexpectedly throws an Error. You should anticipate this possibility and ask yourself: "Should this code go inside of a try / catch block?" to prevent an error like this from crashing your code. Network Requests Don't Throw on 400 and 500 Statuses You might want to make a request to an API, and then handle an error if the request fails. ` Maybe you made a bad request and got back a 400. Maybe you're not properly authenticated and got a 401 or 403. Maybe the endpoint is invalid and you get a 404. Or maybe the server is having a bad day and you get a 500. In none of those cases will you get an Error! From JavaScript's point of view, your request worked. You sent some data to a place, and the place sent you something back. Mission accomplished! Except it's not. You need to deal with these HTTP error statuses. So if you want to handle responses that aren't OK, you need to do it explicitly. To fix the previous example: ` You Can Throw Anything You should throw new Errors. But you could throw 'literally anything'. There's nothing forcing you to only throw an Error. However, it's a lot harder to handle your errors if there's no consistency in what to expect in your catch blocks. It's a best practice to only throw an Error and not any other kind of JavaScript object. This problem becomes especially clear in TypeScript, when the default type of an error in a catch block is not Error, but unknown. TypeScript has no way to know if an error passed into the catch is going to actually be an Error or not, which can make it more frustrating to write error handling code. For this reason, it's often a good idea to check what exactly you've received before trying to handle it. ` (Alas, you cannot throw 🥳. That's a SyntaxError. But throw new Error('🥳') is still perfectly valid!) Conclusion Wielding JavaScript Errors is a big upgrade from console.logging all the things and hoping for the best. And it's not very hard to do it well! By using Error, your apps will be much more explicit in how you expect things to work, and how you expect things might not work. And when something does go wrong, you'll be more likely to notice and better equipped to figure out the problem....

Jul 14, 2023

6 mins

JavaScript

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.

Creating Custom Scrollbars with React

Structure of a Scrollbar

Hide Native Scrollbars

Custom Scrollbar Functionality

Laying out Scrollbar Elements

Sizing the Thumb

Handle the Position of the Thumb

Handle Clicking the Buttons

Handle Clicking the Track

Handle Dragging the Thumb

Full Code and Demo

Tom VanAntwerp

You might also like

D1 SQLite: Writing queries with the D1 Client API

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

JavaScript Errors: An Introductory Primer

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

D1 SQLite: Writing queries with the D1 Client API

Understanding the Difference Between `:focus` and `:focus-visible` in CSS

JavaScript Errors: An Introductory Primer

Introduction to Zod for Data Validation