Forem: Alex K.

Understanding Controlled vs Uncontrolled Components In React

Alex K. — Thu, 28 Mar 2024 14:00:00 +0000

When building forms or handling input fields in React applications, developers often encounter the terms "controlled" and "uncontrolled" components. These concepts are fundamental to understanding how React handles user input and form states. Controlled components are those where form data is handled by the React component state, offering a single source of truth and enabling more complex interactions and validations. On the other hand, uncontrolled components rely on the DOM itself to manage form data, providing a more traditional HTML-like approach. Choosing the right type of component is crucial for maintaining code quality, scalability, and ease of development.

In this post, we'll look at the specifics of controlled versus uncontrolled components in React: how they work, their respective advantages, and guidelines for choosing the right approach for various scenarios in React applications. We'll also explore how to transition between the two types of components and provide code examples to illustrate the concepts.

Controlled components

Controlled components allow React to maintain the form data. This happens via the use of state within the component. Whenever there is a change in the form element, an event handler is invoked that manages the change and updates the component's state. As the state updates, so does the component, ensuring the data displayed is always in sync with the state of the component.

To implement a controlled component, you should:

Initialize the state in the constructor or use state hooks (useState) for function components.
Set the value of the form element to a corresponding state variable.
Create an event handler that will handle user input changes - this function uses setState or the updater function from useState to update the component's state whenever there is an input change.
Attach this event handler to the form element's 'onChange' event.

An example implementation for a controlled <input> element used in forms would look like this:

import React, { useState } from "react";

function LoginForm() {
  const [username, setUsername] = useState("");

  const handleChange = (event) => {
    setUsername(event.target.value);
  };

  return (
    <form>
      <label>
        Username:
        <input type="text" value={username} onChange={handleChange} />
      </label>
    </form>
  );
}

Controlled components come with several advantages. They enable developers to:

Implement instant field validation as the user types or when the field is blurred.
Integrate state management tools and libraries seamlessly.
Utilize the powerful React ecosystem, which includes features like Hooks, for more straightforward state management.
Enforce input formats, by controlling what the user can type into an input field.

Moreover, making use of controlled inputs allows React to act as the "single source of truth", which aligns with React's design philosophy and can lead to more predictable and easier-to-debug code.

In summary, controlled components are more declarative and align well with React's way of handling component states and reactivity, providing a robust mechanism to handle user input and form data.

Uncontrolled components

Uncontrolled components are another way to handle form inputs in React. Instead of writing an event handler for all your state updates, uncontrolled components allow you to use refs to access the DOM nodes directly. In uncontrolled components, you treat form elements as sources of truth, meaning that you retrieve the form values directly from the DOM nodes rather than from the React component's state. Using refs, you can easily access the form elements' underlying DOM node, making uncontrolled components closer in nature to traditional HTML form elements. This is how React Hook Form works under the hood when managing its uncontrolled components via the register function.

Implementing an uncontrolled component involves the following steps:

Create a ref using React.createRef() in a class component or useRef() hook in a function component.
Attach this ref to the form element.
Interact with the form element's value as needed directly through this ref, sparingly in the lifecycle methods like componentDidMount for class components, or inside event handlers.

Here's an example of an uncontrolled component using useRef in a function component:

import React, { useRef } from "react";

function LoginForm() {
  const usernameRef = useRef(null);

  const handleSubmit = (event) => {
    event.preventDefault();
    alert("A username was submitted: " + usernameRef.current.value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Username:
        <input type="text" ref={usernameRef} />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

In case you are using TypeScript, it's important to properly type the ref to avoid potential type issues.

Some advantages of using uncontrolled components include:

Slightly less code for managing form state, which can be more straightforward for simple forms.
More similar to traditional HTML form behaviors, which can be comfortable for developers transitioning from non-React environments.
Potentially less re-rendering since the state is not updated for every input change, which can be better for performance in some scenarios.

In essence, uncontrolled components provide a more straightforward but less "React-centric" way to work with form inputs, striking a balance between the native HTML experience and the reactivity that React offers. They can significantly simplify certain use cases, though the use of refs must be handled with care to maintain proper React paradigms and application integrity.

Comparing controlled and uncontrolled components

When deciding between controlled and uncontrolled components, understanding their differences and the trade-offs involved is important.

The core difference between controlled and uncontrolled components lies in how they handle and store their state. Controlled components rely on React to manage the state, whereas uncontrolled components use the actual DOM to manage the state. The implication of this distinction extends to how changes are monitored and how the component data is extracted.

Controlled components may lead to more render cycles because every change to the input triggers a state update and a consequent re-render of the component. This can impact performance, especially in large forms or when working on lower-powered devices. Uncontrolled components sidestep this by not linking state changes to input updates, thus reducing the number of re-renders.

In scenarios where real-time validation or enabling/disabling of form elements based on input is needed, controlled components shine due to their tight integration with the component's state. For simpler forms without complex logic or for quick prototyping, uncontrolled components are often more than sufficient and can allow for a more straightforward implementation.

Ultimately, the choice between controlled and uncontrolled components will come down to the specific needs of the application and the complexity of the form handling required.

Transitioning between controlled and uncontrolled components

There might be instances where you start with one approach and later realize that another would be more beneficial for your application. It's essential to know how to transition between controlled and uncontrolled components without causing significant refactoring headaches.

Transitioning from an uncontrolled to a controlled component often involves introducing a state variable and onChange handler and then binding the input's value to this state. Conversely, switching to an uncontrolled component from a controlled one typically requires removing the state bindings and introducing a ref to access the input's value. Here are points to consider during the transition:

Evaluate the reason for transition: ensure that the need to transition is driven by sound reasons related to functionality, performance, or code maintainability.
Update the component's structure: for controlled components, bind the input values to state variables. For uncontrolled components, set up refs to access form element values directly.
Refactor event handlers: controlled components will need handlers for updating state, while uncontrolled components might only need handlers for form submission or similar actions.
Test extensively: changing how state is handled in a component can introduce bugs; thorough testing is crucial.

Transitioning between controlled and uncontrolled patterns can lead to a mixture of patterns, which can cause confusion and errors. One pitfall includes mixing refs with state management, leading to split sources of truth. Clear guidelines and best practices should be established to avoid these pitfalls.

Conclusion

Controlled and uncontrolled components in React each offer unique advantages that cater to different scenarios. Controlled components provide a high level of control over the user input and form state, making them suitable for complex scenarios involving dynamic forms and real-time validation. On the other hand, uncontrolled components offer a simpler approach that might result in performance enhancements in specific use cases, particularly when dealing with large forms or form interactions that don't require granular control of the state.

In choosing between controlled and uncontrolled components, it is necessary to consider the nature of the form, the complexity of its behavior, and performance implications. Sometimes, you may even find a need to switch from one approach to the other as application requirements evolve.

Understanding the differences between controlled and uncontrolled components and knowing how to transition between them is crucial for building scalable and maintainable React applications. By leveraging the strengths of each approach, developers can build forms that are both performant and easy to maintain, ensuring a smooth user experience and a robust application.

References and resources

Build Dynamic Forms with React Hook Form

Alex K. — Thu, 28 Mar 2024 10:51:52 +0000

Developers often encounter the need to implement multiple forms that are visually similar but vary slightly in their fields. This is typical when creating configuration forms for different services. While the most straightforward approach might be to create a distinct form for each service, this method comes with several disadvantages: it's difficult to maintain, not easily scalable and lacks flexibility. A more effective solution is to design a dynamic form capable of accommodating any number of services with their respective configuration options.

In this article, we'll design a dynamic form to manage configuration for various social media integrations. We'll be working with four social media providers — Facebook, Twitter, Instagram, and LinkedIn — each having its unique set of configuration options. Rather than building a form filled with complex conditional logic or creating individual forms for each provider, or even creating a multistep form, we will pursue a more efficient strategy by crafting one adaptable form. This dynamic form will be designed to handle the distinct requirements of any number of providers and their configuration settings.

Getting Started

The idea here is to first define an array of field names for each provider. We'll also need a map with more detailed information about each field. This map will contain the field name, label, type, and validation options. We'll use this map to render the form fields and also to validate the form. Finally, we'll have a Form component that will render the form fields based on their type and handle the form submission. We'll use React Hook Form to handle the form state and validation.

The Data

First, we'll need to define the types for each provider. After that, we can combine them into a single type called SocialMediaIntegrationConfig to have a type for all the available fields. Additionally, we'll define a type for the provider names called Provider.

// types.ts

type FacebookConfig = {
  appID: string;
  appSecret: string;
  pageAccessToken: string;
  defaultPostPrivacy: string;
  enableAnalytics: boolean;
  scopes: string[];
};

type TwitterConfig = {
  apiKey: string;
  apiSecret: string;
  accessToken: string;
  accessTokenSecret: string;
  enableRetweets: boolean;
  scopes: string[];
};

type InstagramConfig = {
  clientID: string;
  clientSecret: string;
  accessToken: string;
  enableTagging: boolean;
  scopes: string[];
};

type LinkedInConfig = {
  clientID: string;
  clientSecret: string;
  accessToken: string;
  scopes: string[];
};

export type Provider = "facebook" | "twitter" | "instagram" | "linkedin";
export type SocialMediaIntegrationConfig = FacebookConfig &
  TwitterConfig &
  InstagramConfig &
  LinkedInConfig;

Next, we'll define the field names for each provider. These are the keys from the types we have defined previously. The field names will be stored in an array, so we have control over the order in which they are rendered.

// fields.ts
import { SocialMediaIntegrationConfig, Provider } from "./types";

export const fields: Record<
  Provider,
  Array<keyof SocialMediaIntegrationConfig>
> = {
  facebook: [
    "appID",
    "appSecret",
    "pageAccessToken",
    "defaultPostPrivacy",
    "enableAnalytics",
    "scopes",
  ],
  twitter: [
    "apiKey",
    "apiSecret",
    "accessToken",
    "accessTokenSecret",
    "enableRetweets",
    "scopes",
  ],
  instagram: [
    "clientID",
    "clientSecret",
    "accessToken",
    "enableTagging",
    "scopes",
  ],
  linkedin: ["clientID", "clientSecret", "accessToken", "scopes"],
};

Now we need to add some metadata to these fields, necessary for their rendering. We'll create a map where the field names serve as keys, and objects containing the field data act as values.

// fields.ts
export type FieldData = {
  label: string;
  type: string;
  validation?: {
    required?: boolean;
    message?: string;
  };
  allowCustomValue?: boolean;
  options?: string[];
  placeholder?: string;
};

export const fieldMap: Record<keyof SocialMediaIntegrationConfig, FieldData> = {
  appID: {
    label: "App ID",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  appSecret: {
    label: "App Secret",
    type: "password",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  pageAccessToken: {
    label: "Page Access Token",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  defaultPostPrivacy: {
    label: "Default Post Privacy",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  enableAnalytics: {
    label: "Enable Analytics",
    type: "checkbox",
  },
  scopes: {
    label: "Scopes",
    type: "select",
    options: ["team", "email"],
  },
  apiKey: {
    label: "API Key",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  apiSecret: {
    label: "API Secret",
    type: "password",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  accessToken: {
    label: "Access Token",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  accessTokenSecret: {
    label: "Access Token Secret",
    type: "password",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  enableRetweets: {
    label: "Enable Retweets",
    type: "checkbox",
  },
  enableTagging: {
    label: "Enable Tagging",
    type: "checkbox",
  },
  clientID: {
    label: "Client ID",
    type: "text",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
  clientSecret: {
    label: "Client Secret",
    type: "password",
    validation: {
      required: true,
      message: "This field is required",
    },
  },
};

At first glance, it may seem like a lot is happening, but the process is quite straightforward. We have a map where the field names serve as keys, and objects containing the field data act as values. The field data includes the label, type, validation options, and additional field-specific information. We'll utilize this map both to render the form fields and to validate them. The validation object should align with the validation object's API provided by React Hook Form.

The Form

With our data in place, we can proceed to construct the form. We'll create a Form component responsible for rendering the fields based on their type and managing form submissions. This component will include a renderField method to display each form field according to its designated type. Aside from that, the form's structure is relatively simple.

Before incorporating the Form component, we should abstract a portion of the rendering logic into a separate Field component. This component will be tasked with presenting the label, the error message, and the form field itself, based on the provided field data. Additionally, we'll include a helper function to extract the id prop from a child element, which will be useful for associating the label with the form field, improving accessibility.

// Field.tsx

import React from "react";

interface FieldProps {
  children: React.ReactElement;
  label?: string;
  htmlFor?: string;
  required?: boolean;
  error?: {
    message?: string;
  };
}
export const Field = ({
  children,
  label,
  error,
  htmlFor,
  required,
}: FieldProps) => {
  const id = htmlFor || getChildId(children);

  return (
    <div className="col-sm-12 mb-3 flex flex-col items-start">
      {label && (
        <label htmlFor={id} className="form-label">
          {label}
          {required && "*"}
        </label>
      )}
      {children}
      {error && <small className="error">{error.message}</small>}
    </div>
  );
};

// Get id prop from a child element
export const getChildId = (children: FieldProps["children"]) => {
  const child = React.Children.only(children);

  if ("id" in child?.props) {
    return child.props.id;
  }
};

Now we can create the Form component. We'll use the useForm hook from React Hook Form to handle the form state and validation. We'll also pass the provider name as a prop to the Form component. This prop will be used to determine which fields to render.

import { Controller, useForm } from "react-hook-form";
import { Provider, SocialMediaIntegrationConfig } from "./types";
import { FieldData, fieldMap, fields } from "./fields";
import { Field } from "./Field";

interface FormProps {
  provider: Provider;
}
export const Form = ({ provider }: FormProps) => {
  const {
    register,
    handleSubmit,
    control,
    formState: { errors },
  } = useForm<SocialMediaIntegrationConfig>();
  const providerFields = fields[provider];

  const onSubmit = async (data: SocialMediaIntegrationConfig) => {
    console.log("Saving data", data);
  };

  const renderField = (
    name: keyof SocialMediaIntegrationConfig,
    fieldData: FieldData,
  ) => {
    switch (fieldData.type) {
      case "text":
      case "password":
        return (
          <Field
            label={fieldData.label}
            required={!!fieldData.validation?.required}
            error={errors[name]}
            key={name}
          >
            <input
              {...register(name, {
                required: fieldData.validation?.message,
              })}
              type={fieldData.type}
              id={name}
              autoComplete={"off"}
            />
          </Field>
        );
      case "select":
        return (
          <Field
            label={fieldData.label}
            htmlFor={name}
            key={name}
            error={errors[name]}
          >
            <Controller
              rules={fieldData.validation}
              name={name}
              control={control}
              render={({
                field: { ref, value, onChange, ...fieldProps },
                fieldState: { invalid },
              }) => {
                return (
                  <select
                    {...fieldProps}
                    value={typeof value === "string" ? value : ""}
                  >
                    {fieldData.placeholder && (
                      <option value="" disabled>
                        {fieldData.placeholder}
                      </option>
                    )}
                    {(fieldData.options || []).map((option) => (
                      <option key={option} value={option}>
                        {option}
                      </option>
                    ))}
                  </select>
                );
              }}
            />
          </Field>
        );
      case "checkbox":
        return (
          <Field
            label={fieldData.label}
            htmlFor={name}
            key={name}
            error={errors[name]}
          >
            <input
              {...register(name, { required: fieldData.validation?.message })}
              type={fieldData.type}
              id={name}
              autoComplete={"off"}
            />
          </Field>
        );
      default:
        throw new Error(`Unknown field type: ${fieldData.type}`);
    }
  };

  return (
    <div style={{ padding: "24px" }}>
      <form onSubmit={handleSubmit(onSubmit)} style={{ maxWidth: "600px" }}>
        <>
          {providerFields.map((fieldName) => {
            const field = fieldMap[fieldName];
            return renderField(fieldName, field);
          })}
          <div>
            <Field>
              <button>{"Save"}</button>
            </Field>
          </div>
        </>
      </form>
    </div>
  );
};

Not much is happening in this component. The core of the form lies in the renderField method, which renders the form field based on its type. Since we have only four field types, the method is not overly large. While we could abstract the rendering logic for the Field, I believe it's acceptable to keep it here for now. Alternatively, we could extract the entire rendering logic into a separate component, but having it within the form component facilitates easier access to the useForm hook methods.

With these modifications, adding a new field to the form becomes simple – just define it in the fieldMap and add it to the appropriate fields array, and it will be rendered automatically. Extending the rendering logic is also straightforward in case new requirements arise.

Conclusion

In conclusion, the approach of building dynamic forms with React Hook Form offers a versatile and scalable solution for dealing with forms that need to cater to a variety of configurations. The power of this method is in its modularity and maintainability. By using an array of field names combined with a detailed map of field data, we can effortlessly render various form controls and implement validation without cluttering the codebase with redundant forms or entangled conditional logic.

The post demonstrates how to structure your types, define your fields and field metadata, and finally, construct a Form component that can be expanded or modified with ease. The use of React Hook Form simplifies state management and validation, ensuring a clean and understandable implementation. Whether developers are building forms for a handful of options or complex settings across numerous services, the principles outlined in this article will help them create a robust and adaptable form system. With this approach, tackling new requirements or making changes involves minimal hassle, illustrating the benefits of embracing React's compositional model alongside powerful libraries like React Hook Form for form management.

References and resources

Understanding and Implementing Type Guards in TypeScript

Alex K. — Mon, 11 Mar 2024 13:45:46 +0000

TypeScript, an open-source language developed and maintained by Microsoft, is a superset of JavaScript that adds static types to the language. It has grown to include such advanced features as generic types, conditional types, template literal types, tools for inferring types and mapped types, among others. While TypeScript's static typing system is a tremendous asset, it can sometimes be tricky to determine the type of an object at runtime, particularly when dealing with complex data structures or object-oriented programming constructs. This is where type guards come in.

Type guards are a powerful feature in TypeScript that allows you to narrow down the type of an object within a certain scope. With type guards, you can perform specific checks to determine the type of an object and then use that object in a way that is type-safe according to the TypeScript compiler.

For instance, if you have a variable that could be a string or a number, you can use a type guard to check if the variable is a string. If the type guard check passes, TypeScript will then allow you to use the variable as a string within the scope of the type guard check.

Understanding and effectively using type guards is an essential skill when programming in TypeScript. Not only can they help to prevent type-related bugs, but they also make code cleaner and easier to understand. In the following sections, we'll look into the concept of type guards, explore the different types of type guards that TypeScript offers, and learn how to use them in practical scenarios.

What are type guards

TypeScript is designed to help developers manage the types of their variables and function returns in a way that's more robust than regular JavaScript. When multiple types are possible, such as in union types, the compiler cannot safely predict the type without help. This is where type guards come into play. They are used to inform the compiler about the type of a variable inside a block of code, which allows the compiler to assume the correct type and expose the relevant properties and methods. This is crucial in TypeScript because it allows you to achieve more robust error handling and write safer code by ensuring that you're using variables according to their actual types.

For instance, let's say we have a variable that could either be a string or an array of strings. If we want to use a method that is specific to the array type, like push(), we would first need to ensure that the variable is indeed an array. We can achieve this using a type guard.

let variable: string | string[];

if (Array.isArray(variable)) {
  // Within this if block, TypeScript now knows that 'variable' is an array of strings
  variable.push("new item");
} else {
  // Here, TypeScript knows that 'variable' is a string
  console.log(variable.toUpperCase());
}

In this code, Array.isArray(variable) is the type guard. If this expression evaluates to true, TypeScript knows that variable is an array of strings within the following block. If it evaluates to false, TypeScript knows that variable is a string in the else block.

Type guards are essential for writing robust, bug-free TypeScript code. They provide a way to ensure that you're using variables correctly according to their types, and they help the TypeScript compiler understand the types of variables in different parts of your code.

Types of type guards in TypeScript and practical examples

TypeScript provides several mechanisms to implement type guards. Here, we'll discuss the most commonly used ones - typeof, instanceof, and user-defined type guards - and illustrate their usage with practical examples.

Using typeof for primitives

The typeof type guard is one of the simplest and most common ways to narrow down types in TypeScript. It checks whether a variable is of a certain primitive type, like string, number, boolean or symbol.

function processInput(input: string | number) {
  if (typeof input === "string") {
    return input.toUpperCase(); // TypeScript knows 'input' is a string here
  } else {
    return input.toFixed(2); // TypeScript knows 'input' is a number here
  }
}

In this function, input can either be a string or a number. The typeof type guard checks the type of input, and depending on the result, the function performs different operations.

Using instanceof for class instances

The instanceof type guard is used for narrowing down types when dealing with classes and their instances. It checks whether an object is an instance of a particular class. This is particularly useful when working with complex object-oriented patterns where an object could be an instance of one of several possible classes in a hierarchy.

class Dog {
  bark() {
    return "Woof!";
  }
}

class Cat {
  purr() {
    return "Meow!";
  }
}

function makeSound(animal: Dog | Cat) {
  if (animal instanceof Dog) {
    return animal.bark(); // TypeScript knows 'animal' is a Dog
  } else {
    return animal.purr(); // TypeScript knows 'animal' is a Cat
  }
}

In this example, animal could be an instance of either the Dog or Cat class. The instanceof type guard checks the class of animal, and the function calls the appropriate method based on the result.

User-defined type guards

TypeScript also allows you to define your own type guards. These are useful when you want to perform more complex type checks.

A user-defined type guard is a function that returns a type predicate (i.e., a boolean expression that is dependent on a type). Here's how you can define one, on the example of working with form event types:

interface ChangeEvent {
  type: "change";
  target: HTMLInputElement;
  value: string;
}

interface SubmitEvent {
  type: "submit";
  target: HTMLFormElement;
  fields: Record<string, string>;
}

// User-defined type guard to determine if the event is a ChangeEvent
function isChangeEvent(event: ChangeEvent | SubmitEvent): event is ChangeEvent {
  return event.type === "change";
}

// Function to handle form events, utilizing the user-defined type guard
function handleFormEvent(event: ChangeEvent | SubmitEvent) {
  if (isChangeEvent(event)) {
    // The TypeScript compiler now knows that 'event' is a ChangeEvent
    console.log(
      `Handling change event on field: ${event.target.name}, with value: ${event.value}`,
    );
  } else {
    // Since the event is not a ChangeEvent, it must be a SubmitEvent
    console.log("Handling form submit event with fields:", event.fields);
  }
}

In this example, isChangeEvent is a user-defined type guard that checks if an event is a ChangeEvent. The event is ChangeEvent syntax is a type predicate that tells TypeScript that the result of the function is a boolean expression that depends on the type of event. This allows TypeScript to narrow down the type of event within the handleFormEvent function based on the result of the type guard check.

Advanced usage

Type guards are a powerful feature in TypeScript that can be used in a variety of scenarios. In this section, we'll explore some advanced use cases for type guards, including working with union types and discriminated unions.

Narrowing and discriminated unions with type guards

Discriminated unions are a pattern in TypeScript that allows you to combine union types and literal types to create a type that can be a set of specific values. This is particularly useful in scenarios where you have a variable that could be one of several different shapes.

interface Circle {
  kind: "circle";
  radius: number;
}

interface Square {
  kind: "square";
  sideLength: number;
}

type Shape = Circle | Square;

In this case, the Shape type is a discriminated union of Circle and Square. The kind property acts as a discriminant, allowing you to differentiate between the possible types.

To narrow a discriminated union, you can use a type guard that checks the discriminant property:

function getArea(shape: Shape) {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
  }
}

In the getArea function, TypeScript can narrow down the type of shape within each case branch based on the kind property. This allows you to access the appropriate properties for each type without any type errors.

Using the "in" operator

The in operator is another way to create type guards in TypeScript. It can be particularly useful when working with objects and there's a need to check if they contain a certain property.

Let's extend our Shape example with a new Rectangle type:

interface Circle {
  kind: "circle";
  radius: number;
}

interface Square {
  kind: "square";
  sideLength: number;
}

interface Rectangle {
  kind: "rectangle";
  width: number;
  height: number;
}

type Shape = Circle | Square | Rectangle;

In our getArea function, we can now use the in operator as a type guard:

function getArea(shape: Shape) {
  if ("radius" in shape) {
    // shape is treated as Circle here
    return Math.PI * shape.radius ** 2;
  } else if ("sideLength" in shape) {
    // shape is treated as Square here
    return shape.sideLength ** 2;
  } else if ("width" in shape && "height" in shape) {
    // shape is treated as Rectangle here
    return shape.width * shape.height;
  }
}

In this example, the in operator checks whether specific properties (radius, sideLength, width, height) exist in the shape object. Depending on which check passes, TypeScript narrows the type of shape within that branch of the code, allowing us to access the appropriate properties of each shape without any type errors.

Type guards with mapped types

Mapped types in TypeScript create new types by transforming properties from an existing type, usually involving some operation on each property. When an object's shape is transformed using a mapped type, type guards help in verifying that the object still conforms to a specific structure.

// Original type
type OriginalPerson = {
  name: string;
  age: number;
  hasPet: boolean;
};

// Mapped type that makes all properties optional
type PartialPerson = {
  [P in keyof OriginalPerson]?: OriginalPerson[P];
};

// Type guard for PartialPerson
function isPartialPerson(person: any): person is PartialPerson {
  return (
    ("name" in person && typeof person.name === "string") ||
    ("age" in person && typeof person.age === "number") ||
    ("hasPet" in person && typeof person.hasPet === "boolean")
  );
}

// Function that takes an object and a mapped type as arguments
function processPerson<T extends PartialPerson>(person: T): void {
  if (isPartialPerson(person)) {
    // TypeScript safely infers 'person' to be 'PartialPerson' within this block
    console.log("Processed PartialPerson:", person);
  }
}

const maybePerson = {
  name: "Bob",
  age: 30,
};

processPerson(maybePerson); // OK, 'maybePerson' satisfies 'PartialPerson'

In the example above, isPartialPerson is a type guard that checks if the input person object matches the PartialPerson mapped type structure. If the check passes, TypeScript narrows the type of person within the processPerson function, allowing us to safely use it as a PartialPerson.

Common mistakes and best practices

Type guards in TypeScript are a powerful tool for ensuring type safety in your code. However, like any tool, they must be used correctly to be effective. In this chapter, we'll look at some common mistakes developers make when using type guards and discuss best practices for using them effectively.

Over-reliance on any type: One of the most common mistakes in TypeScript development is overusing the any type, which essentially bypasses TypeScript's type checking. Instead of relying on this catch-all type, when using type guards, always aim to use precise types.
Incorrect use of typeof and instanceof: These type guards are beneficial but should be used correctly. For instance, typeof is best suited for primitive types (like string, number, boolean), while instanceof is appropriate for custom classes. It's important to understand the correct usage of these type guards and apply them properly in your code.
Not considering all possible types in a union: When using type guards with union types, a common mistake is not handling all possible types within the union. This oversight could lead to runtime errors. To counter this, always handle all possible types in a union. One approach is to use exhaustive type checking, using a never type in a default case in a switch statement. This technique will cause TypeScript to throw an error if there are unhandled cases, helping to prevent bugs.
Missing out on user-defined type guards: TypeScript offers the ability to create custom type guards, but developers often overlook this feature. User-defined type guards are especially beneficial when working with complex types as they can encapsulate complicated type-checking logic, improving code readability and maintainability.
Not using discriminated unions for complex types: For complex types with shared fields, developers sometimes miss the opportunity to use discriminated unions. This misstep can lead to more complicated and error-prone type-checking code. Discriminated unions allow you to differentiate between types based on a common "tag" or "kind" field, making it easier to handle different types in a type-safe manner. Always consider using discriminated unions when dealing with complex types.

By avoiding common pitfalls and adhering to best practices, you can make effective use of type guards to improve the safety and reliability of your TypeScript code. It's well worth investing the time to understand and correctly use this powerful feature of the TypeScript language.

Conclusion

In this article, we've explored the importance and usage of type guards in TypeScript. From understanding what type guards are to diving into advanced topics like union types and discriminated unions, hopefully, you've gained a deeper understanding of this crucial aspect of TypeScript's type system.

Type guards are a powerful tool that can help you write safer, more reliable code. While they can seem complex at first, with practice and understanding, they become an invaluable part of your TypeScript toolkit.

By leveraging the power of type guards, you can take full advantage of TypeScript's static typing, leading to better, more predictable, and less error-prone code.

References and resources

Beyond console.log: Debugging Techniques in JavaScript

Alex K. — Mon, 04 Mar 2024 16:43:56 +0000

JavaScript is a versatile programming language serving as a foundational element in web development, driving everything from simple user interactions to complex applications. However, this versatility brings with it a degree of complexity, and inevitably, bugs.

Like it or not, bugs are an integral part of the software development lifecycle. They are as certain as death and taxes, and dealing with them is a skill every developer needs to master. Therefore, debugging — the process of identifying, analyzing, and resolving these bugs — is a critical skill for any developer. However, debugging can often feel like a time-consuming and frustrating process, especially when dealing with tricky bugs or complex codebases.

This blog post offers some alternatives to the frequently used console.log debugging strategy in JavaScript. While console.log is a valuable tool in a developer's arsenal, it's not always the most efficient or comprehensive method for identifying and resolving bugs in your code. Learning other techniques can significantly streamline your debugging process, making coding more efficient and enjoyable.

The importance of debugging

Before looking into the less-used debugging techniques, it's important to understand why debugging is so important.

Firstly, debugging is the key to ensuring the quality of code. Bugs are inevitable in any coding project, no matter the size or complexity. By identifying and resolving these bugs, we can ensure that our code is robust, reliable, and free from errors.

The cost of bugs can be considerable. According to a report by the Consortium for IT Software Quality, poor quality software costs businesses in the US alone up to $2.41 trillion in 2022. This cost includes not just the immediate cost of fixing bugs, but also indirect costs such as lost productivity, damage to reputation, and even potential legal liabilities.

Moreover, efficient debugging skills can make the difference between meeting a project deadline and missing it. The longer a bug goes undetected or unresolved, the more time and resources it will drain. By mastering debugging techniques, developers can significantly reduce the time spent on fixing bugs, leading to more efficient project delivery.

Below, we'll explore some alternative debugging techniques that can help you become a more efficient and effective developer.

Using console.table for more readable logging

One of the most common debugging techniques in JavaScript is console.log(). It's straightforward and lets you print the value of a variable or the state of your application at any given point. But when it comes to logging arrays or objects, console.log() can sometimes leave us with a less-than-ideal output.

Enter console.table(). This method displays tabular data as a table in the console, making it much easier to read complex data structures.

const people = [
  { name: "Alice", age: 25, job: "Engineer" },
  { name: "Bob", age: 30, job: "Designer" },
  { name: "Charlie", age: 35, job: "Teacher" },
];

console.table(people);

Running this code in a browser console will display a table, with columns for index, name, age, and job, and rows for each object in the array.

It's a simple trick, but it can make a big difference when trying to make sense of complex data.

Mastering breakpoints in Chrome DevTools

Breakpoints are a powerful tool in a developer's arsenal. They allow you to pause the execution of your code at a specific point, enabling you to inspect the current state of your application.

Chrome DevTools offers a range of options for setting breakpoints, including line-of-code breakpoints, conditional breakpoints, and DOM change breakpoints, to name a few. Mastering these different types of breakpoints can greatly improve your debugging efficiency. For example, you might use a conditional breakpoint to pause execution only when a certain condition is met, saving you from having to manually step through unrelated parts of your code.

Debugging with the JavaScript 'debugger' keyword

The debugger keyword in JavaScript is another handy tool for pausing code execution. When the browser encounters the 'debugger' statement and the DevTools are open, it will automatically pause execution, allowing you to inspect the current state of an application.

This can be particularly useful for tracking down elusive bugs that only occur under certain conditions. By strategically placing 'debugger' statements in your code, you can catch these bugs in the act and analyze their cause.

Using JSON.stringify for logging complex objects

JSON.stringify() is a method that converts a JavaScript object or value to a JSON string. While this method is often used for sending data to a server or saving data in a string format, or even removing duplicates from objects, it can also be a powerful debugging tool.

When you log an object to the console in JavaScript, it's logged by object reference, not by value. This means that if the object changes later in your code, the logged output will also change. However, by using JSON.stringify(), you can log the state of an object at a specific point in time, making it easier to track down bugs related to mutable data.

Profiling JavaScript performance with console.time

Performance bugs can be some of the trickiest to debug, but console.time() can help with those. This method starts a timer that you can use to track how long an operation takes.

To use console.time(), you simply call it with a unique label at the start of the operation you want to time, and then call console.timeEnd() with the same label when the operation has completed. This will log the time in milliseconds that elapsed between the two calls, helping identify any parts of your code that might be causing performance issues, like slow loops or inefficient sorting algorithms.

console.time("expensive-operation");

for (let i = 0; i < 1000000; i++) {
  // Operation being performed...
}

console.timeEnd("expensive-operation");

When the code above is executed, the console will output the time taken to complete the loop in milliseconds, which might look something like:

expensive-operation: 15.635ms

Monitoring all events with monitorEvents() in DevTools

Ever had a bug that only occurs when a certain sequence of events happens? The monitorEvents() function in Chrome DevTools can be a lifesaver in these situations. This function allows you to listen to all events dispatched to a specified object.

For example, if you want to monitor all events on a button with the ID 'myButton', you would run monitorEvents(document.getElementById('myButton')) in the console. This will then log all events dispatched to this button, helping you understand exactly what's happening and when.

Debugging promises with async/await

Promises are a powerful feature of modern JavaScript, enabling writing asynchronous code in a more manageable and readable way. However, debugging promises can sometimes be tricky, particularly when dealing with complex chains of them.

By using the async/await syntax, you can write your asynchronous code in a way that looks and behaves more like synchronous code, making it easier to understand and debug. For example, instead of using .then() to chain promises, you can simply use the await keyword to pause the execution of your function until the promise resolves, and then continue with the result of the promise.

Conclusion

In conclusion, debugging is an essential aspect of development that directly affects the quality, performance, and reliability of JavaScript applications. Given the complexities of modern web development and the high costs associated with software bugs, it is clear why having robust debugging techniques is indispensable to both the individual developer and the organization.

The best debugging is not merely about fixing what is broken; it’s about understanding the application and preemptively crafting a resilient and maintainable codebase. With the advancement of debugging tools and methods, developers now have the means to rapidly pinpoint problems and their root causes, administer fixes, and ensure a smooth user experience.

References and resources

Diacritic-insensitive string comparison in JavaScript

Alex K. — Wed, 28 Feb 2024 07:54:49 +0000

In the world of web development, managing and manipulating text data is a crucial task. Strings, which are the primary data type for textual content in programming languages like JavaScript and TypeScript, are equipped with an abundance of methods for effective text data processing. However, when it comes to handling Unicode characters that fall outside the ASCII range, this task can become significantly more challenging.

Unicode is a universal character encoding standard. It encompasses virtually every character from all the writing systems that are in use today. While this extensive representation is one of Unicode's strengths, it also introduces unique challenges for developers. For instance, different sequences of Unicode characters can represent the same visual character or set of characters. This variation can lead to potential inconsistencies and challenges in text processing within web applications.

One particular task where these challenges become evident is filtering an array of objects based on user input. In this article, we will delve into this specific scenario and explore how to perform diacritic-insensitive string comparisons in JavaScript.

While filtering an array of objects based on a string value might seem like a straightforward task at first glance, it can get quite complex, especially when dealing with Unicode characters and ensuring consistency across various writing systems. By the end of this article, you will have a better understanding of how to tackle these complexities in your JavaScript or TypeScript projects.

Filtering an array of objects in JavaScript

Let's consider a practical example where we have a list of airport options for a Select component in a web application. Our goal is to filter these options based on user input before populating the Select component.

const filter = "Cancun";
const airports = [
  {
    name: "Húsavík Airport",
    code: "HZK",
  },
  {
    name: "Cancún International Airport",
    code: "CUN",
  },
  {
    name: "Zürich Airport",
    code: "ZRH",
  },
  {
    name: "Kraków John Paul II International Airport",
    code: "KRK",
  },
  {
    name: "Málaga-Costa del Sol Airport",
    code: "AGP",
  },
  {
    name: "Côte d'Azur Airport",
    code: "NCE",
  },
  {
    name: "Fès-Saïs Airport",
    code: "FEZ",
  },
];

The initial approach to filtering the list of airports based on the filter string could be as follows:

const filteredOptions = airports.filter((option) => {
  return option.name.toLowerCase().includes(filter.toLowerCase());
});

However, when we run this code, we see that filteredOptions results in an empty array. This happens because the strings "Cancun" and "Cancún" are not regarded as equivalent due to their distinct character compositions. JavaScript carries out string comparisons based on Unicode character values, and it considers diacritics.

To address this issue, we need to use the String.prototype.normalize method.

Understanding the String.prototype.normalize method in JavaScript

The String.prototype.normalize method is a powerful tool for handling Unicode strings in JavaScript. It's an integral part of the ECMAScript Internationalization API specification (ECMA-402), which offers language-sensitive string comparison, number formatting, and date and time formatting.

The normalize method converts a string into a specific Unicode Normalization Form. The syntax for this method is str.normalize([form]), where form can take one of four values: "NFC", "NFD", "NFKC", or "NFKD".

But what do these forms signify? Unicode Normalization Forms establish standard equivalences among Unicode sequences. "NFC" is an acronym for Normalization Form C, denoting the canonical composition, while "NFD" stands for Normalization Form D, representing canonical decomposition. On the other hand, "NFKC" and "NFKD" embody compatibility composition and decomposition, respectively.

In simpler terms, these forms either combine or break apart characters that can be depicted in multiple manners in Unicode.

Let's illustrate this with an example. Take the character 'é'. Unicode can represent it as either a single character (U+00E9, or "é"), or as a combination of 'e' and an acute accent (U+0065 U+0301, or "é"). Although they are visually identical, these representations may create inconsistencies in string comparison and manipulation. The normalize method can convert these varied representations into a uniform form, ensuring more dependable string operations.

Implementing string normalization

Armed with an understanding of the String.prototype.normalize method, let’s see how we can integrate it into our function. This will enable us to perform diacritic-insensitive string comparisons effectively, taking into account characters with diacritics.

const normalizeString = (str) => {
  return str
    .normalize("NFD")
    .replace(/[\u0300-\u036f]/g, "")
    .toLowerCase();
};

const filteredOptions = airports.filter((option) => {
  return normalizeString(option.name).includes(normalizeString(filter));
});

The function starts by calling str.normalize('NFD'). This transforms the input string into its canonical decomposition form, "NFD". In this form, composed characters like 'é' are split into their base characters and their combining marks, 'e' and '´', respectively.

Next, the function uses .replace(/[\u0300-\u036f]/g, '') to remove all diacritic marks from the string. The regular expression /[\u0300-\u036f]/g matches all combining diacritical marks in the Unicode range from U+0300 to U+036f, which includes accents like the acute accent in 'é'. By replacing these marks with an empty string, the function effectively removes them.

Finally, the function calls .toLowerCase(), which transforms all uppercase characters in the string to their lowercase equivalents. This makes the function case-insensitive, meaning it will treat 'A' and 'a' as the same character.

Transforming strings into a consistent, case-insensitive, diacritic-free form enables more reliable string comparison and manipulation.

Now the filteredOptions will correctly contain the Cancún option. Another common use case for this functionality is handling user input in form fields. When a user inputs text, it's common to normalize the input before processing it to ensure consistency. This is especially useful in form fields that accept international input, where users might input text with a variety of diacritic marks. We could also apply a similar approach to sorting an array of objects.

Considerations and Limitations

While the String.prototype.normalize method and the normalizeString function are powerful tools, it's important to understand their limitations and potential performance impacts.

Firstly, the normalization process can have a significant performance impact if used excessively or on large strings. The normalize method transforms the entire string, which can be a costly operation for large strings or frequent calls. Therefore, it's important to use this method judiciously and only when necessary.

Additionally, not all Unicode characters are handled correctly by the normalize method. The Unicode standard continues to evolve, and there may be characters or combinations that do not normalize as expected. It's crucial to test and validate the normalization behavior with the specific Unicode characters used in your application.

Conclusion

Handling Unicode characters in JavaScript and TypeScript presents unique challenges, particularly when it comes to diacritic-insensitive string comparisons. The String.prototype.normalize method, along with the normalizeString function presented in this article, provide an effective approach to address these challenges. They transform strings into a consistent, case-insensitive, and diacritic-free form, enabling more dependable string comparison and manipulation. This is especially beneficial in tasks such as filtering elements in an array, which is a common requirement in many applications. However, developers must be mindful of the potential performance implications of string normalization and its limitations with certain Unicode characters. The removal of diacritic marks, while useful for comparisons, may not always be linguistically accurate or appropriate. As always, understanding the tools at your disposal and their possible limitations is key to writing robust and efficient code.

References and resources

TypeScript Template Literal Types: Practical Use-Cases for Improved Code Quality

Alex K. — Wed, 21 Feb 2024 07:39:03 +0000

In recent years, TypeScript has become an indispensable tool for many JavaScript developers, offering type safety, improved code maintainability, and enhanced developer experience with many advanced type features, like generic types, type guards and conditional types. One of the powerful features introduced in TypeScript 4.1 is template literal types which provide greater flexibility and control over string literal types.

In TypeScript, a string literal type is a type that represents a specific set of string values. For example, the type "red" | "green" | "blue" represents the set of three string values "red", "green", and "blue". Template literal types allow you to perform operations on these string literal types using the same syntax as template literal strings in JavaScript.

In this article, we will explore some effective and practical use cases for TypeScript template literal types, demonstrating how they can enhance code quality and productivity. From generating CSS class names to creating type-safe i18n keys, this post will show you how to harness the full potential of template literal types in your TypeScript projects.

Creating type-safe URL patterns

Creating type-safe URL patterns in TypeScript with template literals is an effective way to ensure the validity of your application's routing structure. This approach allows developers to define precise URL patterns, including parameters and dynamic segments, which can then be safely used throughout the application.

type RouteParams = {
  userId: number;
  postSlug: string;
};

type RoutePath<T extends keyof RouteParams> = T extends "userId"
  ? `/users/${RouteParams[T]}/posts`
  : T extends "postSlug"
    ? `/posts/${RouteParams[T]}`
    : never;

const userPostsPath: RoutePath<"userId"> = "/users/123/posts";
const postPath: RoutePath<"postSlug"> = "/posts/first-post";

// Type '"/posts/first-post"' is not assignable to type '`/users/${number}/posts`'
const wrongPostPath: RoutePath<"userId"> = "/posts/first-post";

Related to template literals is the concept of tagged templates in JavaScript.

Combining enum and string

This is a key use case that brings more flexibility and precision to TypeScript's strong typing capabilities. Enums are a way of giving more friendly names to sets of numeric values. In this case, by defining the Directions enum, we can use the ${Directions}_DIRECTION template literal to ensure that the type can only be one of the specific values: "North_DIRECTION", "South_DIRECTION", "East_DIRECTION", or "West_DIRECTION". This aids in keeping code more understandable and easier to debug, as it is clear what kind of value the variable holds and what the acceptable values are. Moreover, it helps to eliminate many potential errors by ensuring that only specific string patterns are accepted.

enum Directions {
  North = "North",
  South = "South",
  East = "East",
  West = "West",
}

type DirectionString = `${Directions}_DIRECTION`;

const go: DirectionString = "North_DIRECTION";

Generating CSS class names

Template literal types can also be used to generate CSS class names in TypeScript. By defining a type that represents a set of class names, you can use template literal types to create a type-safe way to generate class names based on some input variables. This can help avoid errors caused by typos or incorrect class names in your CSS files. For example, you could define a type for all the valid button sizes in your application, and use template literal types to generate a class name for a button based on its size.

type ButtonSize = "small" | "medium" | "large";

type ButtonClassNames<T extends ButtonSize> = `button-${T}`;

function getButtonClassName<T extends ButtonSize>(
  size: T,
): ButtonClassNames<T> {
  return `button-${size}`;
}

const smallButtonClassName = getButtonClassName("small"); // "button-small"
const mediumButtonClassName = getButtonClassName("medium"); // "button-medium"
const largeButtonClassName = getButtonClassName("large"); // "button-large"

Enforcing specific format

TypeScript's Template Literal Types can be used for enforcing specific string formats, such as a date format. Here, the DateFormat type is defined as ${number}-${number}-${number}, which forces the string to follow a 'YYYY-MM-DD' format. This allows developers to ensure that all date-related data in their codebase adhere to this specific format, minimizing errors that might arise from inconsistent date formatting. By doing so, it contributes to data integrity in the application, and the standardization eases data parsing and processing. Any attempt to assign a string not adhering to the 'YYYY-MM-DD' format to a variable of 1 type would result in a TypeScript error, preventing the code from compiling and instantly notifying developers of the mismatch.

type DateFormat = `${number}-${number}-${number}`; // 'YYYY-MM-DD'

const date: DateFormat = "2023-06-27";

Dynamically generating keys

Template literal types can be used to create new types with keys generated based on a pattern.

type Prefix = "prop";
type Index = "1" | "2" | "3";
type DynamicKey = `${Prefix}${Index}`;

type DynamicProps = {
  [K in DynamicKey]: string;
};

A more advanced example involves creating a type that adds a prefix to the keys of an object. This approach enables the creation of new types with keys adhering to a specific pattern, maintaining a consistent naming convention. Doing so helps prevent errors caused by typos or incorrect property names. TypeScript will generate a compile-time error if an incorrect key name is used, further enhancing code safety and maintainability.

type KeyPattern<T extends string, U extends Record<string, string | number>> = {
  [P in `${T}${Capitalize<Extract<keyof U, string>>}`]: U[P extends `${T}${Capitalize<infer K>}`
    ? K
    : never];
};

type User = {
  id: number;
  name: string;
  email: string;
};

type PrefixedUser = KeyPattern<"user", User>;

const user: PrefixedUser = {
  userId: 123,
  userName: "John",
  userEmail: "john@example.com",
};

Building complex type names

Complex type names can be created by combining multiple type parts. This is particularly useful when working with Redux action types.

type BaseType = "User";
type Action = "Create" | "Update" | "Delete";
type TypeName = `${Action}${BaseType}`;

const create: TypeName = "CreateUser";

// Type '"ModifyUser"' is not assignable to type '"CreateUser" | "UpdateUser" | "DeleteUser"'
const modify: TypeName = "ModifyUser";

The same approach can be used to build event names based on a prefix and event type.

type Prefix = "app";
type EventType = "init" | "update" | "destroy";
type EventName = `${Prefix}:${EventType}`;

const initEvent: EventName = "app:init";

Representing CSS values

To have more control over what kinds of values are available, template literal types can be used to build CSS length units.

type Unit = "px" | "rem";
type NumericValue = "1" | "2" | "3";
type CSSLength = `${NumericValue}${Unit}`;

const fontSize: CSSLength = "2rem";

This could be useful if you don't allow certain types of units, like em, in your design system.

Type-safe i18n keys

As a variation of the previous approach, template literal types can be used to generate i18n keys, ensuring that translations are accurately typed. This technique enhances the consistency and reliability of internationalized applications by enforcing type safety on translation keys.

type Section = "home" | "about";
type I18NKey = `translation.${Section}`;

const homeKey: I18NKey = "translation.home";

Type-safe attribute selectors

Template literal types can be used to create type-safe attribute selectors for DOM elements, ensuring that only valid attributes are used.

type Attribute = "id" | "class" | "data-test";
type AttributeSelector = `[${Attribute}]`;

function queryElementByAttribute<T extends HTMLElement>(
  selector: AttributeSelector,
): T[] {
  const elements = document.querySelectorAll<T>(selector);
  return Array.from(elements);
}

const idSelector: AttributeSelector = "[id]";
const elementsById = queryElementByAttribute<HTMLDivElement>(idSelector);

const dataTestSelector: AttributeSelector = "[data-test]";
const elementsByDataTest =
  queryElementByAttribute<HTMLButtonElement>(dataTestSelector);

In this example, we've created a utility function queryElementByAttribute that takes an AttributeSelector as a parameter. This ensures that only valid attribute selectors can be used when querying the DOM. On top of improved maintainability and readability, this code also enables better autocompletion support in code editors, as editors can suggest valid attribute selectors based on the defined types.

Conclusion

In conclusion, TypeScript's template literal types offer a fascinating way to work with string literal types, providing a blend of flexibility, precision, and control. They can be harnessed effectively to manage a wide array of tasks, from constructing type-safe URL patterns, creating dynamic keys, generating CSS class names, building complex type names, to enforcing type safety on translation keys. By offering increased code safety, better maintainability, and enhanced developer experience, template literal types undoubtedly position TypeScript as an indispensable tool in the JavaScript ecosystem. Remember, these examples are only the tip of the iceberg when it comes to the full potential of template literal types.

References and resources

Create an Interactive Table of Contents for a Next.js Blog with Remark

Alex K. — Fri, 21 Apr 2023 06:41:19 +0000

Originally published at https://claritydev.net.

A table of contents offers numerous benefits and is a valuable addition to websites, particularly blogs. A well-organized and easily navigable table of contents significantly enhances the user experience, simplifying for readers the process of finding the information they need. By incorporating a table of contents, you not only streamline the post's navigation but also improve the overall accessibility and usability of your content.

In this post, we'll go through the necessary steps to create an interactive table of contents for a Next.js blog using Remark, a powerful Markdown processor.

While some Remark plugins like Remark-toc provide this functionality, the generated table of contents is placed within the content itself, limiting its potential uses. For instance, on my blog, the table of contents is rendered outside the blog content, making it visible during post navigation. This is the type of table of contents we will build in this tutorial.

We'll start by briefly discussing the fundamentals of Remark, its plugins, and how it integrates with Next.js. Then, we'll dive into the practical steps of implementing a custom table of contents, and finally, we'll make it interactive so that clicking on a table of contents item will scroll the page to its corresponding section.

Remark and its plugins

Remark is an extensible Markdown processor that simplifies the process of converting Markdown files into HTML or other formats. The key aspect of Remark is its plugin-based architecture, which enables developers to extend and customize its functionality. These plugins can handle tasks like syntax highlighting, adding a table of contents, or parsing custom Markdown syntax. Integrating Remark with Next.js is straightforward — typically, it is used in conjunction with the getStaticProps function to process Markdown files during the build process. It can also process MDX files, making it a viable option for Next.js websites using the new "app" directory. Remark's powerful processing capabilities and seamless integration with Next.js make it an ideal choice for enhancing content and user experience in Next.js-based blogs and websites.

Getting started

Although we are building a custom table of contents, we won't have to write everything from scratch. To separate the Markdown/MDX content from the front matter, we'll use the Gray-matter package. It is optional in case you don't have front matter in your Markdown files. To process the Markdown itself, we'll use the Remark package. We'll also need the unist-util-visit package for traversing node trees and mdast-util-to-string for getting the text content of a node.

Let's install all these packages.

npm i remark mdast-util-to-string gray-matter unist-util-visit

If you're curious about setting up continuous deployment for your website with GitHub actions, you may find this article interesting: Automate Your Deployment Workflow: Continuously Deploying Next.js Website to DigitalOcean Using GitHub Actions.

Custom Remark plugin for extracting headings from the content

Before rendering the table of contents, we must extract all the headings from the Markdown file and organize them into an array of nodes. This process can be divided into several steps:

Parse the file contents to separate the front matter from the content.
Generate IDs for each of the heading elements. This will be necessary for implementing the scroll-to-section functionality later.
Parse the content, extracting the headings and their attributes.

For step 2, we could manually add the IDs as custom Markdown attributes, e.g., ## Heading 1 {#heading-id}, and then use a library like Remark-heading-id to render them into HTML. However, this approach requires manual work to add and maintain those headings. A more efficient method is to automatically generate the IDs from the heading text itself, so the heading Heading 1 will automatically receive an ID of heading-1 when transformed into HTML.

Additionally, we can combine steps 2 and 3 by creating a custom Remark plugin.

export function headingTree() {
  return (node, file) => {
    file.data.headings = getHeadings(node);
  };
}

function getHeadings(root) {
  const nodes = {};
  const output = [];
  const indexMap = {};
  visit(root, "heading", (node) => {
    addID(node, nodes);
    transformNode(node, output, indexMap);
  });

  return output;
}

Here, we have our custom Remark plugin - headingTree, which extracts the headings from the document and adds them as a headings attribute to the processed content.

The main component of the plugin is the getHeadings function, a visitor function that traverses a tree of nodes and manipulates them. For improved readability, the function is split into two parts.

The addID function iterates through the heading nodes in the document, replaces all their special characters, and outputs them as lowercase strings with spaces replaced by dashes. The IDs will be stored in the hProperties attribute of the heading.

/*
 * Add an "id" attribute to the heading elements based on their content
 */
function addID(node, nodes) {
  const id = node.children.map((c) => c.value).join("");
  nodes[id] = (nodes[id] || 0) + 1;
  node.data = node.data || {
    hProperties: {
      id: `${id}${nodes[id] > 1 ? ` ${nodes[id] - 1}` : ""}`
        .replace(/[^a-zA-Z\d\s-]/g, "")
        .split(" ")
        .join("-")
        .toLowerCase(),
    },
  };
}

Note that we use the nodes variable to track the number of occurrences of each heading. This is done so that we can prefix the headings that appear more than once in the document (e.g., some sections can have subheadings with the same text) with a number.

The transformNode function takes a node from the parsed Markdown Abstract Syntax Tree (AST) and transforms it into a more usable format for building a table of contents.

import { toString } from "mdast-util-to-string";

function transformNode(node, output, indexMap) {
  const transformedNode = {
    value: toString(node),
    depth: node.depth,
    data: node.data,
    children: [],
  };

  if (node.depth === 2) {
    output.push(transformedNode);
    indexMap[node.depth] = transformedNode;
  } else {
    const parent = indexMap[node.depth - 1];
    if (parent) {
      parent.children.push(transformedNode);
      indexMap[node.depth] = transformedNode;
    }
  }
}

The function checks if the node has a depth of 2 (## element in Markdown). If it does, the transformed node is added to the output array and is saved in the indexMap at the corresponding depth. This indicates that the transformed node is at the top level of the table of contents. We designate depth 2 as the top depth here because it will produce <h2> tags in the HTML output. We don't use depth 1 since having multiple <h1> elements on a page is not good for page accessibility and SEO.

If the node's depth is greater than 2 (e.g., ### or #### elements), the function identifies the parent node by looking up the indexMap at the depth level immediately above the current node (i.e., node.depth - 1). If a parent node is found, the transformed node is added to the children array of the parent node, and the indexMap is updated accordingly. This helps in building the nested structure of the table of contents, where deeper nodes become children of nodes at higher levels.

It's important to note that for this function to work, the table of contents should have a valid structure, e.g. there are no jumps from node depth 2 straight to depth 4.

Now we have everything we need to implement the getHeadings function.

import matter from "gray-matter";
import { remark } from "remark";

import { headingTree } from "./headings";

const postsDirectory = path.join(process.cwd(), "posts");

export async function getHeadings(id) {
  const fullPath = path.join(postsDirectory, `${id}.mdx`);
  const fileContents = fs.readFileSync(fullPath, "utf8");

  // Use gray-matter to parse the post metadata section
  const matterResult = matter(fileContents);

  // Use remark to convert Markdown into HTML string
  const processedContent = await remark()
    .use(headingTree)
    .process(matterResult.content);

  return processedContent.data.headings;
}

With this, we have an array of headings from a document, plus their data attributes. The array has the following structure.

[
  {
    value: "Heading 1",
    depth: 2,
    data: { hProperties: { id: "heading-1" } },
    children: [
      {
        value: "Heading 2",
        depth: 3,
        data: { hProperties: { id: "heading-2" } },
        children: [
          {
            value: "Heading 3",
            depth: 4,
            data: { hProperties: { id: "heading-3" } },
            children: [],
          },
        ],
      },
    ],
  },
  {
    value: "Heading 4",
    depth: 2,
    data: { hProperties: { id: "heading-4" } },
    children: [],
  },
];

Rendering the table of contents

Now that we have the heading data, we can use it to render the table of contents. To start, we'll create a TableOfContents component, which will be a wrapper for the table of contents rendering logic.

"use client";

export const TableOfContents = ({ nodes }) => {
  if (!nodes?.length) {
    return null;
  }

  return (
    <div className={"toc"}>
      <h3 className={"secondary-text"}>Table of contents</h3>
      {renderNodes(nodes)}
    </div>
  );
};

Note that if you're using the Next.js "app" directory, you need to use the "use client" directive to mark this component as a client-side one.

The actual rendering of the table of contents will be managed by the renderNodes function. We employ a separate function rather than defining it inside the component due to the rendering logic being recursive.

function renderNodes(nodes) {
  return (
    <ul>
      {nodes.map((node) => (
        <li key={node.data.hProperties.id}>
          <a href={`#${node.data.hProperties.id}`}>{node.value}</a>
          {node.children?.length > 0 && renderNodes(node.children)}
        </li>
      ))}
    </ul>
  );
}

Each of the table of contents elements is a link that points to the ID of the respective header via its href attribute.

Adding smooth scrolling when clicking a table of contents link

The basic table of contents is complete. Within the page where we render our post, we can obtain the headings by calling await getHeadings(postId) (or by doing this within getStaticProps if you're using the "pages" directory) and pass the data to the TableOfContents component. On the post page, when we click on a table of contents link, we should be navigated to the corresponding section of the page. However, instead of abruptly jumping to the header, we can enable smooth scrolling. As an additional enhancement, we can progressively decrease the sublink font size based on its depth.

To achieve this, we will introduce a TOCLink component responsible for both smooth scrolling and individual link styles, which we will then use within renderNodes.

function renderNodes(nodes) {
  return (
    <ul>
      {nodes.map((node) => (
        <li key={node.data.hProperties.id}>
          <TOCLink node={node} />
          {node.children?.length > 0 && renderNodes(node.children)}
        </li>
      ))}
    </ul>
  );
}

const TOCLink = ({ node }) => {
  const fontSizes = { 2: "base", 3: "sm", 4: "xs" };
  const id = node.data.hProperties.id;
  return (
    <a
      href={`#${id}`}
      className={`block text-${fontSizes[node.depth]} hover:accent-color py-1`}
      onClick={(e) => {
        e.preventDefault();
        document
          .getElementById(id)
          .scrollIntoView({ behavior: "smooth", block: "start" });
      }}
    >
      {node.value}
    </a>
  );
};

To smoothly scroll to a specific element on a webpage, we first locate the element using its ID and then apply the scrollIntoView method with the behavior: "smooth" option. For more information about this method, refer to the MDN website. The method boasts extensive browser support; however, the smooth option may not be compatible with some older browsers. By employing this approach, clicking on a table of contents link now results in a nice scrolling animation, as opposed to the previously abrupt transition.

If you need to add an offset to your heading elements when they are scrolled to (e.g., when the page has a fixed navbar), you can apply the scroll-margin-top CSS property to the heading elements.

Additionally, we can progressively decrease the font size of the table of contents links in relation to their depth using TailwindCSS and its text utility classes.

Highlighting active links

A final touch to enhance the table of contents navigation is highlighting the table of contents links when their corresponding headers are in view on the page.

To detect an element's visibility on the page, we will use the Intersection Observer API, which has good browser support with some minor caveats. Furthermore, we will transfer this functionality to a custom hook that returns a boolean indicating if a link is highlighted and provides a callback for setting the highlighted state manually. This hook will be utilized within the TOCLink component.

import { useEffect, useRef, useState } from "react";

function useHighlighted(id) {
  const observer = useRef();
  const [activeId, setActiveId] = useState("");

  useEffect(() => {
    const handleObserver = (entries) => {
      entries.forEach((entry) => {
        if (entry?.isIntersecting) {
          setActiveId(entry.target.id);
        }
      });
    };

    observer.current = new IntersectionObserver(handleObserver, {
      rootMargin: "0% 0% -35% 0px",
    });

    const elements = document.querySelectorAll("h2, h3, h4");
    elements.forEach((elem) => observer.current.observe(elem));
    return () => observer.current?.disconnect();
  }, []);

  return [activeId === id, setActiveId];
}

const TOCLink = ({ node }) => {
  const fontSizes = { 2: "base", 3: "sm", 4: "xs" };
  const id = node.data.hProperties.id;
  const [highlighted, setHighlighted] = useHighlighted(id);
  return (
    <a
      href={`#${id}`}
      className={`block text-${fontSizes[node.depth]} hover:accent-color py-1 ${
        highlighted && "accent-color"
      }`}
      onClick={(e) => {
        e.preventDefault();
        setHighlighted(id);
        document
          .getElementById(id)
          .scrollIntoView({ behavior: "smooth", block: "start" });
      }}
    >
      {node.value}
    </a>
  );
};

Within the hook, the handleObserver function serves as an Intersection Observer callback that processes the visibility changes of observed elements, accepting an array of entries as its argument.

The handleObserver function iterates through the entries, which include the h2, h3, and h4 elements, checking if the isIntersecting property is true — indicating that the element is visible in the viewport — and if so, updates the active section in the table of contents using setActiveId. When a link is clicked, we set it as highlighted via the setHighlighted callback.

Additionally, we store a new Intersection Observer instance inside a ref to preserve its identity during component renders.

You can see this table of contents in action on this page by scrolling through the page and observing how the active section of the table of contents updates as the corresponding section on the page is reached.

If you're curious about adding a "copy to clipboard" button to a Next.js site, you may find this article interesting: Copy to Clipboard Button In MDX with Next.js and Rehype Pretty Code.

Conclusion

In conclusion, creating a table of contents for your Next.js blog using Remark and a custom plugin can provide numerous benefits to your website's user experience and accessibility. With Remark, a powerful Markdown processor, and its extensive range of plugins, it's easy to extract headings from your Markdown files and convert them into an interactive and easily navigable table of contents.

By incorporating a table of contents, you can enhance the user experience on your Next.js blog, making it simpler for readers to find the information they need. Additionally, creating a custom table of contents plugin with Remark enables you to integrate the table of contents outside the content itself, which improves the usability and accessibility of your content. With the use of plugins such as mdast-util-to-string and unist-util-visit, you can extract the headings from your content, generate unique IDs, and parse them into a format suitable for building a table of contents.

This tutorial has guided you through the process of creating a custom table of contents with a nested structure, smooth scrolling, and active link highlighting. As a result, readers can now quickly find and navigate to the content they're interested in, enhancing the overall usability and value of your blog.

References and resources

I rebuilt my blog using Next.JS and Tailwind

Alex K. — Fri, 24 Mar 2023 07:54:24 +0000

I recently decided to rebuild my blog/portfolio website which previously ran on Django. This time, I opted to use Next.JS and Tailwind instead. Surprisingly, it was very easy to keep the Django admin running on the same droplet (I'm using DigitalOcean for hosting), and have it run only for certain URLs.

I would love to hear your opinions on the final result! You can check it out at claritydev.net.

Enzyme vs React Testing Library: A Migration Guide

Alex K. — Fri, 24 Mar 2023 07:42:30 +0000

This blog post provides a basic comparison of both libraries and presents a migration guide based on code samples from each library. We'll write tests for the Tic-Tac-Toe game from an earlier post using Enzyme and then transform them into React Testing Library tests.

Enzyme vs React Testing Library: A Migration Guide

Build a Tic-Tac-Toe Game with TypeScript, React and Minimax

Alex K. — Thu, 23 Mar 2023 14:32:17 +0000

In this tutorial we will build a Tic-Tac-Toe game with TypeScript, React, React Hooks, and style it using Styled Components library. Additionally, we'll use the Minimax algorithm to power the AI moves. The final code is available on both GitHub and CodeSandbox.

Build a Tic-Tac-Toe Game with TypeScript, React and Minimax.

Automate Your Deployment Workflow: Continuously Deploying Next.js Website to DigitalOcean Using GitHub Actions

Alex K. — Thu, 23 Mar 2023 11:13:41 +0000

In this post, we'll explore how to automate the deployment of a Next.js website to DigitalOcean using GitHub Actions. We'll discuss what GitHub Actions are and how they can be used to continuously deploy changes to a remote server, reducing the need for manual intervention and minimizing downtime. By the end of this post, you'll have a clear understanding of how to automate your deployment workflow and achieve faster, more reliable deployments with ease.

Automate Your Deployment Workflow: Continuously Deploying Next.js Website to DigitalOcean Using GitHub Actions

Add a Dynamic Sitemap to Next.js Website Using Pages or App Directory

Alex K. — Sat, 11 Mar 2023 14:21:29 +0000

In this post, we will explore how to add a dynamic sitemap to a Next.js website using the app directory. A sitemap is a file that lists all the pages of a website and helps search engines understand the structure of the site. By the end of this post, you will have a fully functional dynamic sitemap for your Next.js website.

The post is available on my blog.