Understanding the JavaScript Modulo Operator

When I was first learning to code, I remember finding the Modulo operator (%) extremely confusing. 😬

If you don't understand what it's doing, the values it produces seem completely random:

const what = 10 % 4; // 2
const the = 10 % 10; // 0
const heck = 4 % 10; // 4

# this is a Python comment not a heading

In this blog post, we're going to learn how this operator works by refining our mental model for division. We'll also cover a practical, every-day use case for this curious fella.

Rethinking division

Suppose we have the following bit of arithmetic:

12 ÷ 4

Division can often feel pretty abstract or theoretical, but there's a practical way to think about it: we want to divide a number into equally-sized groups.

Drag the slider to see how this operation can be visualized:

12 ÷ 4 evaluates to 3, because each group holds exactly 3 items. Essentially, we're figuring out how many items will be held inside each group.

In the example widget above, our divisor (the number to be divided) is 12. 12 is a remarkably clean number when it comes to division; it can be split neatly in lots of different ways.

Suppose we had the following equation instead:

11 ÷ 4

This equation evaluates to 2.75. Each group has 2 complete items, and then ¾ths of another item.

This works if we're dividing up pizzas or cakes… but what if the items are indestructible? What if we can't break each item up into smaller fractions?

In that case, we'd be able to fit 2 items into each group, and we'd be left with 3 additional items:

This is known as the remainder. It's what the modulo operator produces.

In cases where the number can be equally divided into groups (eg. 12 ÷ 4), there is nothing left over:

12 % 4; // 0

In situations where the divisor (the number to be divided) can't be split equally into groups, the modulo operator lets us know how much is left over:

11 % 4; // 3

A real-world use case

So, I'm not a mathematician, I'm a web developer. All of this math stuff is interesting, but let's talk about how the modulo operator can come in handy on the web.

Specifically, there's one sort of problem that I seem to run into a lot, where the modulo operator offers the perfect solution: circular arrays.

For example, suppose we have an array of 3 colors. Each second, we want to switch to the next color in the list. When we reach the end of the list, we want to jump back to the first item:

This is a surprisingly tricky problem. Suppose we have a variable called timeElapsed that starts at 0 and increments by 1 every second; we have to somehow map this ever-increasing value to an array with only 3 items.

Essentially, we need to write a function that produces the following results:

const COLORS = ["red", "yellow", "blue"];

getColor({ timeElapsed: 0 }); // 'red'
getColor({ timeElapsed: 1 }); // 'yellow'
getColor({ timeElapsed: 2 }); // 'blue'
getColor({ timeElapsed: 3 }); // 'red'
getColor({ timeElapsed: 4 }); // 'yellow'
getColor({ timeElapsed: 5 }); // 'blue'
getColor({ timeElapsed: 6 }); // 'red'
getColor({ timeElapsed: 7 }); // 'yellow'
getColor({ timeElapsed: 8 }); // 'blue'
// ...And so on, forever

Let's look at how the modulo operator can help us solve this problem:

const COLORS = ["red", "yellow", "blue"];

function getColor({ timeElapsed }) {
  const colorIndex = timeElapsed % COLORS.length;

  return COLORS[colorIndex];
}

Miraculously, this does exactly what we need! This method will always return one of the 3 colors, as long as timeElapsed is an integer. And it'll cycle through the 3 colors as timeElapsed increases.

COLORS.length is equal to 3, since there are 3 colors in our array. And so, as timeElapsed increments from 0 to 8, this function winds up performing the following sequence of calculations:

const colorIndex = 0 % 3; // 0
const colorIndex = 1 % 3; // 1
const colorIndex = 2 % 3; // 2
const colorIndex = 3 % 3; // 0
const colorIndex = 4 % 3; // 1
const colorIndex = 5 % 3; // 2
const colorIndex = 6 % 3; // 0
const colorIndex = 7 % 3; // 1
const colorIndex = 8 % 3; // 2

We can then use this colorIndex to look up the color from the COLORS array. It's guaranteed to always cycle within the range of available indexes for that array.

To understand why this works, it's worth remembering our new model for division: we're trying to divide timeElapsed into 3 equally-sized groups, without any fractional or decimal values. The remainder will always be either 0, 1, or 2. It will never be 3+, because if there was 3 left, we could fit 1 more in each group!

Essentially, it's as if we had the ability to create a “circular” array. No matter how large our underlying timeElapsed value grows, we can have it cycle indefinitely through the colors in the COLORS array.

Here is the code in a Code Playground for you to experiment with

import { Play, Pause, RotateCcw } from "react-feather";
import Card from "./Card";
import styles from "./App.module.css";
import { MotionConfig, motion } from "framer-motion";
import VisuallyHidden from "./VisuallyHidden";
import React from "react";
import clsx from "clsx";

const COLORS = [
  { label: "red", value: "hsl(348deg 100% 60%)" },
  { label: "yellow", value: "hsl(50deg 100% 55%)" },
  { label: "blue", value: "hsl(235deg 100% 65%)" },
];

export default function App() {
  const [timeElapsed, setTimeElapsed] = React.useState(0);
  const [isRunning, setIsRunning] = React.useState(false);

  React.useEffect(() => {
    if (!isRunning) return;

    const tid = setInterval(() => {
      setTimeElapsed((t) => t + 1);
    }, 1000);

    return () => {
      clearInterval(tid);
    };
  }, [isRunning]);
  // TODO: This value should cycle through the colors in the
  // COLORS array:
  const selectedColor = COLORS[timeElapsed % COLORS.length];

  return (
    <MotionConfig reducedMotion="user">
      <Card as="section" className={styles.wrapper}>
        <ul className={styles.colorsWrapper}>
          {COLORS.map((color, index) => {
            const isSelected = color.value === selectedColor.value;

            return (
              <li className={styles.color} key={index}>
                {isSelected && (
                  <motion.div
                    layoutId="outline"
                    className={styles.selectedColorOutline}
                  />
                )}
                <div
                  className={clsx(
                    styles.colorBox,
                    isSelected && styles.selectedColorBox
                  )}
                  style={{
                    backgroundColor: color.value,
                  }}
                >
                  <VisuallyHidden>{color.label}</VisuallyHidden>
                </div>
              </li>
            );
          })}
        </ul>

        <div className={styles.timeWrapper}>
          <dl className={styles.timeDisplay}>
            <dt>Time Elapsed</dt>
            <dd>{timeElapsed}</dd>
          </dl>
          <div className={styles.actions}>
            <button onClick={() => setIsRunning(!isRunning)}>
              {isRunning ? (
                <>
                  <Pause />
                  <VisuallyHidden>Pause</VisuallyHidden>
                </>
              ) : (
                <>
                  <Play />
                  <VisuallyHidden>Play</VisuallyHidden>
                </>
              )}
            </button>
            <button
              onClick={() => {
                setIsRunning(false);
                setTimeElapsed(0);
              }}
            >
              <RotateCcw />
              <VisuallyHidden>Reset</VisuallyHidden>
            </button>
          </div>
        </div>
      </Card>
    </MotionConfig>
  );
}

In my opinion, this trick alone makes the modulo operator worth learning! I've used this circular-array trick dozens of times over the years, and it's just one of several practical use cases for this handy operator.