DEV Community: Dmitry

Timeline portfolio map with React and D3.js | Part II

Dmitry — Thu, 24 Sep 2026 20:51:51 +0000

This is Part II of a two-part tutorial series where we create an interactive timeline-based portfolio project. The first part can be found linked in the dev.to series, or on my website.

Welcome back! This is the final part of the tutorial. We laid a solid foundation in the previous sections, and now all of our updates will be visual. We are going to proceed with toughest part first: distributing the items on the lanes/rows above and beneath the baseline; and then we'll be applying visual improvements and go through a small de-brief in the end.

Putting nodes on lanes
Drawing lines to nodes
Rich content cards
Animating resize
Wrap up

Putting nodes on lanes

Code for the section

Before we begin, let me ask you something: do you like greedy algorithms?

Oh, don't answer, I'm sure you love them as much as I do! And for distributing our nodes across the lanes, we're going to use a greedy approach in practice.

Most of our work will be in the src/lib/timeline/engine/lanes.ts. Let's add the helper interfaces and a stub for the function assignLanes that we are going to use inside the TimelineEngine.calculateLayout method:

import type { DisplaySide } from "./types";

export interface LaneAssignment {
  side: DisplaySide;
  laneIndex: number;
}

interface LaneInput {
  id: string;
  startMs: number;
  endMs: number;
  preferredSide?: DisplaySide;
}

function getOppositeSide(side: DisplaySide) {
  if (side === "above") {
    return "below";
  }

  return "above";
}

// Distributes the nodes over the lanes, with 0 being the first level from the baseline/axis
export function assignLanes(
  nodes: LaneInput[],
  requiredGapMs: number,
): Map<string, LaneAssignment> {
}

LaneAssignment is going to be the return type of our function. It will be then assigned to the node's side and laneIndex, and used for calculating the actual value of y.

The LaneInput might look a bit weird. Why milliseconds? Because we want to be precise, and our chart is a temporal chart, milliseconds would be a good measurement when reasoning about the positions, before they get scaled into the actual pixels. This is the same reason why the requiredGapMs parameter is also in milliseconds. That would be the gap used for detecting the collisions between the cards, and deciding whether or not we should add a new lane, or try and put the node above/below the baseline.

Buckle up, because now we need to add the body of the assignLanes. Please look into the comments, because in this case it's easier to explain what's going on right inside of the code:

// Distributes the nodes over the lanes, with 0 being the first level from the baseline/axis
export function assignLanes(
  nodes: LaneInput[],
  requiredGapMs: number,
): Map<string, LaneAssignment> {
  // Sort nodes from earliest to latest, so each lane only needs to track
  // the end time of its most recently assigned node.
  const sortedNodes = nodes.toSorted((a, b) => a.startMs - b.startMs);

  // For each side, store the end time of the last node occupying each lane.
  // The index in the `above` and `below` arrays is the lane number.
  const laneEnds: Record<DisplaySide, number[]> = {
    above: [],
    below: [],
  };

  const result = new Map<string, LaneAssignment>();

  for (const node of sortedNodes) {
    // When no side is preferred, we start with the side that currently has fewer lanes
    // This would keep the timeline map more balanced across the baseline/axis
    const lessUsedSide: DisplaySide =
      laneEnds.above.length <= laneEnds.below.length ? "above" : "below";

    // If a node has a preferred side, we try it first.
    // Otherwise, try the currently less-used side first.
    // In both cases, the opposite side is the fallback
    const sidesToTry: DisplaySide[] = node.preferredSide
      ? [node.preferredSide, getOppositeSide(node.preferredSide)]
      : [lessUsedSide, getOppositeSide(lessUsedSide)];

    let placed = false;

    for (const side of sidesToTry) {
      const lanes = laneEnds[side];

      // Find the first existing lane whose previous node leaves
      // enough horizontal space before this node starts.
      for (let i = 0; i < lanes.length; i++) {
        if (lanes[i] + requiredGapMs <= node.startMs) {
          lanes[i] = node.endMs;
          result.set(node.id, { side, laneIndex: i });
          placed = true;
          break;
        }
      }

      if (placed) {
        break;
      }
    }

    if (!placed) {
      // If we couldn't place a node, it means that none of the existing lanes would do,
      // because there will be a collision. Thus, we create a new lane on the first side from `sidesToTry`
      const side = sidesToTry[0];

      laneEnds[side].push(node.endMs);

      result.set(node.id, {
        side,
        laneIndex: laneEnds[side].length - 1,
      });
    }
  }

  return result;
}

Wow, collision detection is sure fun! But now that we have our assignLanes in place, we can finally use it inside the calculateLayout method of the TimelineEngine class. But before we do that, let's add a couple of new constants to the src/lib/timeline/engine/constants.ts:

...

// Width of the `NodeCard` in px
export const CARD_WIDTH_PX = 260;

// Timeline lanes' size - how far the items on the row/lane are from the baseline/axis
// Distance of lane 0 from the baseline axis
export const LANE_BASE_OFFSET_PX = 90;
// Additional distance per lane
export const LANE_GAP_PX = 110;

Maybe you're starting to guess where we are going with these! We are going to use the CARD_WIDTH_PX to build requiredGapMs for collision detection, and calculate the y based on the LANE_BASE_OFFSET_PX + (laneIndex * LANE_GAP_PX). Let's use those in the TimelineEngine:

...
private calculateLayout(axisY: number) {
  const domain = this.xScale.domain();
  const range = this.xScale.range();

  const msPerPx = (domain[1].getTime() - domain[0].getTime()) / (range[1] - range[0]);

  const cardWidthMs = CARD_WIDTH_PX * msPerPx;

  const lanes = assignLanes(
    this.timelineNodes.map((node) => ({
      id: node.id,
      startMs: new Date(node.date).getTime(),
      endMs: this.endOf(node).getTime(),
      preferredSide: node.preferredSide,
    })),
    cardWidthMs,
  );

  return new Map<string, NodeLayout>(
    this.timelineNodes.map((node) => {
      const startX = this.xScale(new Date(node.date));
      const endX = this.xScale(this.endOf(node));

      const { side, laneIndex } = lanes.get(node.id)!;
      const direction = side === "above" ? -1 : 1;

      return [
        node.id,
        {
          x: (startX + endX) / 2,
          y: axisY + direction * (LANE_BASE_OFFSET_PX + laneIndex * LANE_GAP_PX),
          startX,
          endX: node.endDate || node.ongoing ? endX : undefined,
          side,
          laneIndex,
        },
      ];
    }),
  );
}
...

I believe the code we've just created is relatively self-explanatory. One thing to point out is the direction part:

const direction = side === "above" ? -1 : 1;

Don't forget that in the coordinate system going up means negative value, and going down is positive!

One final touch, let's fix the NodeCard's width using our constant and add a formatted date under the node.id (the formatNodeTime can be found in the utils directory):

import { CARD_WIDTH_PX } from "../../engine/constants";
...
const NodeCard: React.FC<Props> = ({ node }) => {
  return (
    <div
      style={{
        ...
        width: `${CARD_WIDTH_PX}px`,
      }}
    >
      {node.id}
      <br />
      {formatNodeTime(node)}
    </div>
  );
};

With these figured out, now we're talking! Notice how the items adapt to different screen sizes:

Interactive demo

Now it's time to connect them to the baseline with some SVG paths.

Drawing lines to nodes

Code for the section

In this section, most of our work will be inside the src/lib/timeline/engine/paths.ts, building functions that return the string value for the d attribute of a <path /> element.

Let's handle the most basic case first: a one-shot project:

// Simple vertical connector for a `project` node
export function stemPath(x: number, laneY: number, axisY: number): string {
  return `
    M ${x} ${axisY} 
    L ${x} ${laneY}
  `;
}

Here, we take the x of the NodeCard, y of its lane, and the baseline's y position. Then we M move the imaginary pen to the point on the baseline where the node is located, and L draw a line upwards or downwards.

Let's use it in the TimelineMap right away. Inside the <svg /> element, add the following code:

{/* Paths to the nodes */}
{nodes.map((node) => {
  let pathData: string = "";

  pathData = stemPath(node.startX, node.y, axisY);

  return (
    <path
      key={node.id}
      className={cx(styles["connector"], {
        commitment: node.type === "commitment",
        project: node.type === "project",
      })}
      d={pathData}
      fill="none"
    />
  );
})}

and add some CSS to the src/lib/timeline/components/TimelineMap/styles.module.scss:

.scroll-wrapper {
  ...
  .inner-content {
    ...
    .connector {
      stroke-width: 3;
      opacity: 0.5;

      &.commitment {
        stroke: var(--color-commitment);
      }
      &.project {
        stroke: var(--color-project);
      }
    }
  }
}

Now, the projects should have a blue-ish line pointing to them. Nice!

But we need to also handle commitments, which are a bit more complex. Add another function to the paths.ts:

// Builds a simple square bridge between the start and the end of a `commitment` node
export function bridgePathSimple(
  startX: number,
  endX: number,
  laneY: number,
  axisY: number,
  options: { openEnded?: boolean } = {},
): string {
  const { openEnded = false } = options;

  // Move the starting point, draw a line from the axis to the lane
  const rise = `
    M ${startX} ${axisY} 
    L ${startX} ${laneY}
  `;

  // `ongoing` is `true`: rise once, and then simply draw a line towards the end, i.e. the end of the domain in this case
  if (openEnded) {
    return `
      ${rise} 
      L ${endX} ${laneY}
    `;
  }

  // Draw a line to the `endX` along the lane and then draw a line back to the axis
  return `
    ${rise} 
    L ${endX} ${laneY}
    L ${endX} ${axisY}
  `;
}

The idea here is the same: M move the pen to the x on the baseline, draw a simple stem first, and then either L draw a line towards the end of the chart for ongoing commitments, or return it back to the baseline.

Let's use it inside TimelineMap:

...
{/* Paths to the nodes */}
{nodes.map((node) => {
  let pathData: string;

  if (node.endX !== undefined) {
    pathData = bridgePathSimple(node.startX, node.endX, node.y, axisY, {
      openEnded: node.ongoing,
    });
  } else {
    pathData = stemPath(node.startX, node.y, axisY);
  }

  return (
    <path
      key={node.id}
      className={cx(styles["connector"], {
        commitment: node.type === "commitment",
        project: node.type === "project",
      })}
      d={pathData}
      fill="none"
    />
  );
})}
...

Note: because of our endOf method, the node.endX is never undefined for the ongoing commitments, it's set to the end of the domain.

That's not too bad, but we probably want something smoother, rather than just these square-ish shapes. Let's make the corners rounded via Q, the Quadratic Bézier curve command:

// Builds a smooth bridge between the start and the end of a `commitment` node
export function bridgePathCurved(
  startX: number,
  endX: number,
  laneY: number,
  axisY: number,
  options: { curve?: number; openEnded?: boolean } = {},
): string {
  const { curve = 70, openEnded = false } = options;

  // The control point of the rise, pulling the line in its direction to create the curve.
  const riseQuadraticBezierControlPoint = `${startX} ${laneY}`;

  // Half of the distance between the start and the end of the x
  const span = (endX - startX) / 2;
  // If the passed-in curve is larger than the span, we get weird shapes, so we take the min value between the two
  const _curve = Math.min(curve, span);
  // The larger the `riseEndX` value in this case, the smoother will be the curve
  const riseEndX = startX + _curve;
  // Then end point, where the curve ends on the lanes
  const riseQuandraticBezierEndPoint = `${riseEndX} ${laneY}`;

  const rise = `
    M ${startX} ${axisY} 
    Q ${riseQuadraticBezierControlPoint}, ${riseQuandraticBezierEndPoint}
  `;

  // `ongoing` is `true`: rise once, and then simply draw a line towards the end, i.e. the end of the domain in this case
  if (openEnded) {
    return `${rise} L ${endX} ${laneY}`;
  }

  // Since we have a curve here, the `endX` needs to be adjusted by subtracting the value we assigned to `_curve`
  // The smaller this value, the smoother will be the curve
  const fallStartX = endX - _curve;

  // The control point of the fall, pulling the line in its direction to create the curve.
  const fallQuadraticBezierControlPoint = `${endX} ${laneY}`;
  // Then end point, where the curve ends on the baseline/axis
  const fallQuandraticBezierEndPoint = `${endX} ${axisY}`;

  return `
    ${rise} 
    L ${fallStartX} ${laneY} 
    Q ${fallQuadraticBezierControlPoint}, ${fallQuandraticBezierEndPoint}
  `;
}

and use it:

...
let pathData: string;

if (node.endX !== undefined) {
  pathData = bridgePathCurved(node.startX, node.endX, node.y, axisY, {
    openEnded: node.ongoing,
  });
} else {
  pathData = stemPath(node.startX, node.y, axisY);
}
...

Please refer to the detailed explanations in the code comments, and play around with the default curve value to see how the corner of the bridge changes. Comprehending the Q command has its twists and curves at first, and I also can refer you to an amazing article by the unmatched guru of front-end, Josh Comeau.

The current result of our work should look something like this:

Interactive demo

But I think we can help Jane Doe to have an even better portfolio, given how many images and copy she has prepared! Let's make the NodeCard component nice.

Rich content cards

Code for the section

Most of our work in this section will be inside the src/lib/timeline/components/NodeCard directory. We will also add a new event handler passed from the App.tsx down to the card, and a new constant CARD_CLOSED_HEIGHT_PX that we'll use to make sure the hovered/touched cards open downwards.

src/lib/timeline/engine/constants.ts

...
// Height of the `NodeCard` in its initial state
export const CARD_CLOSED_HEIGHT_PX = 68;

src/App.tsx

...
function App() {
  const handleOnNodeExpand = (node: TimelineNode) => {
    alert(
      `
Triggered expand for node with id "${node.id}"
______________

Here you would put the logic for the most interesting parts: opening the modal, handling a programmatic redirect, etc. 
You could also extend the function to pass the DomRect of the card, or a ref to the element itself to implement visual effects and animations.
      `,
    );
  };

  return (
    <>
      <main className="main">
        <TimelineMap data={data} onNodeExpand={handleOnNodeExpand} />
      </main>
    </>
  );
}
...

src/lib/timeline/components/TimelineMap/index.tsx

...
type Props = {
  data: TimelineNodeData[];
  onNodeExpand: (node: TimelineNode) => void;
};
...
const TimelineMap: React.FC<Props> = ({ data, onNodeExpand }) => {
  ...
  {/* Node cards */}
  {nodes.map((node) => {
    return <NodeCard key={node.id} node={node} onExpand={onNodeExpand} />;
  })}
  ...
}

src/lib/timeline/components/NodeCard/index.tsx

import { Fragment, useEffect, useRef, useState } from "react";
import styles from "./styles.module.scss";
import classNames from "classnames/bind";
import { CARD_CLOSED_HEIGHT_PX, CARD_WIDTH_PX } from "../../engine/constants";
import { type TimelineNode } from "../../engine/types";
import formatNodeTime from "../../../utils/formatNodeTime";

const cx = classNames.bind(styles);

type Props = {
  node: TimelineNode;
  onExpand: (node: TimelineNode) => void;
};

const NodeCard: React.FC<Props> = ({ node, onExpand }) => {
  const cardButtonRef = useRef<HTMLButtonElement>(null);
  const [previewOpen, setPreviewOpen] = useState(false);

  const handlePointerEnter = (e: React.PointerEvent<HTMLButtonElement>) => {
    if (e.pointerType === "mouse") {
      setPreviewOpen(true);
    }
  };
  const handlePointerLeave = (e: React.PointerEvent<HTMLButtonElement>) => {
    if (e.pointerType === "mouse") {
      setPreviewOpen(false);
    }
  };

  const expand = () => {
    onExpand(node);
  };

  const handleClick = () => {
    if (!previewOpen) {
      setPreviewOpen(true);
      return;
    }
    expand();
  };

  useEffect(() => {
    if (!previewOpen || !cardButtonRef.current) {
      return;
    }

    const onDocPointerDown = (e: PointerEvent) => {
      if (!cardButtonRef.current?.contains(e.target as HTMLElement)) {
        setPreviewOpen(false);
      }
    };

    document.addEventListener("pointerdown", onDocPointerDown);
    return () => {
      document.removeEventListener("pointerdown", onDocPointerDown);
    };
  }, [previewOpen]);

  return (
    <div
      className={cx(styles["wrapper"], {
        open: previewOpen,
      })}
      style={{
        left: `${node.x}px`,
        // Makes sure that the card is centered vertically
        // we avoid transform(-50%, -50%) for both x and y to make sure the card always opens downwards
        top: `calc(${node.y}px - ${CARD_CLOSED_HEIGHT_PX / 2}px)`,
      }}
    >
      <button
        ref={cardButtonRef}
        type="button"
        className={cx(styles["card-button"], {
          commitment: node.type === "commitment",
          project: node.type === "project",
          open: previewOpen,
        })}
        style={
          {
            "--card-width": `${CARD_WIDTH_PX}px`,
          } as React.CSSProperties
        }
        onPointerEnter={handlePointerEnter}
        onPointerLeave={handlePointerLeave}
        onClick={handleClick}
        aria-expanded={previewOpen}
      >
        <div className={styles["content"]}>
          {node.thumbnailUrl ? (
            <div
              className={cx(styles["thumbnail-wrapper"], {
                hidden: !previewOpen,
                visible: previewOpen,
              })}
            >
              <img alt={node.title} src={node.thumbnailUrl} />
            </div>
          ) : null}
          <div className={styles["title"]}>{node.title}</div>

          <div className={styles["organization"]}>
            {node.organizationLogoUrl ? (
              <img
                alt={node.organization}
                className={styles["logo"]}
                width={24}
                height={24}
                src={node.organizationLogoUrl}
              />
            ) : null}
            <span className={styles["name"]}>{node.organization}</span>
          </div>
          {previewOpen ? (
            <Fragment>
              <div className={styles["date"]}>{formatNodeTime(node)}</div>
              <div className={styles["summary"]}>{node.summary}</div>
              <div className={styles["hint"]}>Click to expand</div>
            </Fragment>
          ) : null}
        </div>
      </button>
    </div>
  );
};

export default NodeCard;

src/lib/timeline/components/NodeCard/styles.module.scss

.wrapper {
  position: absolute;
  transform: translateX(-50%);
  z-index: 1;

  flex-shrink: 0;

  &.open {
    z-index: 2;
  }

  .card-button {
    display: flex;
    flex-direction: column;
    align-items: center;
    padding: 10px 14px;

    background-color: var(--node-card-color-background);
    border: 1px solid var(--node-card-color-border);
    border-radius: 10px;

    cursor: pointer;

    width: var(--card-width, 260px);

    transition: all 0.5s ease;

    &.commitment {
      border-top: 3px solid var(--color-commitment);
    }

    &.project {
      border-top: 3px solid var(--color-project);
    }

    &:focus,
    &:hover {
      outline: none;
      box-shadow: var(--node-card-shadow);
      border-bottom-color: var(--node-card-color-border--focus);
      border-left-color: var(--node-card-color-border--focus);
      border-right-color: var(--node-card-color-border--focus);
    }

    &.open {
      transform: scale(1.03);
    }

    .content {
      .thumbnail-wrapper {
        overflow: hidden;

        display: flex;
        justify-content: center;

        margin-bottom: 0.25rem;

        height: 0px;

        &.hidden {
          display: none;
        }

        &.visible {
          animation: 0.6s expand ease forwards;
        }

        img {
          width: 100%;
          border-radius: 8px;
          object-fit: cover;
        }

        @keyframes expand {
          from {
            height: 0px;
          }
          to {
            height: 120px;
          }
        }
      }

      .title {
        font-weight: 600;
        font-size: 0.7rem;
        color: var(--node-card-text-primary);
        line-height: 1.3;
        margin-bottom: 0.15rem;

        font-family: var(--mono);
      }

      .organization {
        display: flex;
        flex-direction: row;
        align-items: center;
        justify-content: center;
        gap: 0.4rem;

        .logo {
          width: 18px;
          object-fit: contain;
        }

        .name {
          color: var(--node-card-text-secondary);
        }
      }

      .date {
        font-size: 0.5rem;
        color: var(--node-card-text-secondary);
        text-align: center;
        margin-bottom: 0.2rem;
      }

      .summary {
        font-size: 0.72rem;
        color: var(--node-card-text-secondary);
        margin: 0;
        line-height: 1.3;
        text-align: justify;
        text-wrap: pretty;
        hyphens: auto;
        margin-bottom: 0.2rem;
      }

      .hint {
        font-size: 0.65rem;
        color: var(--color-accent);
      }
    }
  }
}

Most of the code here is pretty standard React with SCSS modules and classnames/bind library. The only bit worth mentioning, is this part:

...
style={
  {
    "--card-width": `${CARD_WIDTH_PX}px`,
  } as React.CSSProperties
}
...

Which is a nice way to pass a CSS variable value to a component, which can be useful, especially in pure client-side apps with a lot of animations.

The cards now look real nice, and help to build up an engaging visual story!

Interactive demo

The only problem is, now when we resize the screen, abrupt jumping of the cards over the lanes becomes an eyesore. Let's make the movement smooth and on par with the cards' aesthetics!

Animating resize

Code for the section

If you made it to this part, you are a champ! Before we wrap up, let's add a final touch to Jane Doe's portfolio (or yours, if you decided to use your own data right away): make the screen resizing smooth.

There's a ton of ways to implement animations on the web, GSAP, Motion, to name a few. But in our case, we already have a powerful tool inside of our codebase: the dr-ease module and the interpolateNumber(a, b) function.

Let's import them in src/lib/timeline/engine/index.ts, where we'll do the majority of the work for this final section.

...
import { easeCubicInOut, interpolateNumber, timeFormat, timeMonth, timeYear } from "d3";
...

For our animation, we're going to use the browser API native requestAnimationFrame. Instead of simply calling this.applyLayout inside of the resize method, we're going to implement a new private method animateTo, and pass our targetLayout to it. We will also have a new property animationFrame for cancelling the animation, and a new public method destroy, that we're going to add to the cleanup function in the TimelineMap.

Let's lay the foundation first:

src/lib/timeline/engine/index.ts

...
export class TimelineEngine {
  ...
  private animationFrame: number | undefined;
  ...
  resize(newWidth: number, newAxisY: number) {
    ...
    const targetLayout = this.calculateLayout(newAxisY);

    this.animateTo(targetLayout);
  }

  // Now we also have a destroy function, to avoid memory leaks if the `TimelineMap` unmounts during the animation
  destroy() {
    if (this.animationFrame !== undefined) {
      cancelAnimationFrame(this.animationFrame);
    }
  }
  ...
  private animateTo(targetLayout: Map<string, NodeLayout>) {
  }
}

src/lib/timeline/components/TimelineMap/index.tsx

...
const TimelineMap: React.FC<Props> = ({ data, onNodeExpand }) => {
  ...
  useEffect(() => {
    return () => {
      timelineEngineInstanceRef.current?.destroy();
    };
  }, []);
  ...
};

Let's get to business, and implement animateTo. Refer to the explanations in the comments, as they are knit pretty tight to the code:

private animateTo(targetLayout: Map<string, NodeLayout>) {
  // This cancels the next frame, in case the user resizes the window again while the current animation is still running
  // `resize` will calculate a new target layout and start a new animation from the nodes' current positions
  if (this.animationFrame !== undefined) {
    cancelAnimationFrame(this.animationFrame);
  }

  const startTime = performance.now();
  const duration = 400;

  // Create interpolation functions from each node's current position
  // to its target position and store them in a Map.
  // The created functions are equivalent to
  // (t) => a * (1 - t) + b * t
  // and will be evaluated on each animation frame
  const interpolatedLayout = new Map(
    this.timelineNodes.map((node) => [
      node.id,
      {
        x: interpolateNumber(node.x, targetLayout.get(node.id)!.x),
        y: interpolateNumber(node.y, targetLayout.get(node.id)!.y),
        startX: interpolateNumber(node.startX, targetLayout.get(node.id)!.startX),
        endX:
          node.endX !== undefined && targetLayout.get(node.id)!.endX !== undefined
            ? interpolateNumber(node.endX, targetLayout.get(node.id)!.endX!)
            : undefined,
      },
    ]),
  );

  // Callback function passed to `requestAnimationFrame`, that will run on each frame
  // and update nodes' positions, will run until the target layout is reached
  const animationStep = (now: number) => {
    // Calculate the animation progress as a value between 0 and 1, where
    // 0 is the start, and 1 is the end
    const progress = (now - startTime) / duration;
    // `d3-ease` functions expect a normalized value in the [0, 1] range
    // https://d3js.org/d3-ease
    const progressNormalized = Math.min(progress, 1);

    // A cubic ease-in-out, so the animation starts and ends smoothly
    const t = easeCubicInOut(progressNormalized);

    // Iterate over the nodes to evaluate the interpolation for the current frame
    // and apply new coordinates to the node
    for (const node of this.timelineNodes) {
      const interpolation = interpolatedLayout.get(node.id)!;

      node.x = interpolation.x(t);
      node.y = interpolation.y(t);
      node.startX = interpolation.startX(t);

      // `.endX` can be undefined, so interpolate only if present
      if (interpolation.endX) {
        node.endX = interpolation.endX(t);
      }

      // Once the transition finishes, update the side and the lane
      // These are not coordinates, but discrete layout properties, so we don't need to interpolate them
      if (progress === 1) {
        const target = targetLayout.get(node.id)!;
        node.side = target.side;
        node.laneIndex = target.laneIndex;
      }
    }

    // Update the stateful values in the `TimelineMap`, re-rendering the UI with the new positions
    this.syncLayout();

    // Continue the animation loop while the transition is in progress.
    // If we haven't reached 1 yet, call `requestAnimationFrame`
    if (progress < 1) {
      this.animationFrame = requestAnimationFrame(animationStep);
    } else {
      // If we did, don't call `requestAnimationFrame`, and set the `animationFrame` to `undefined`
      this.animationFrame = undefined;
    }
  };

  // Start the animation loop
  this.animationFrame = requestAnimationFrame(animationStep);
}

Usually the most confusing part about animation frames is starting and ending the loop. In this case, the essential part is, we call requestAnimationFrame with the next step while the progress value is still less than 1, and we don't call it, if progress has reached 1.

...
  {
    ...
    // Continue the animation loop while the transition is in progress.
    // If we haven't reached 1 yet, call `requestAnimationFrame`
    if (progress < 1) {
      this.animationFrame = requestAnimationFrame(animationStep);
    } else {
      // If we did, don't call `requestAnimationFrame`, and set the `animationFrame` to `undefined`
      this.animationFrame = undefined;
    }
  };

  // Start the animation loop
  this.animationFrame = requestAnimationFrame(animationStep);
...

It's not a conventional while loop, and can take a few re-reads to wrap your head around it, but it opens up a ton of possibilities!

Now the resizing looks smooth and fluid:

Interactive demo

Wrap up

Congratulations, you made it to the finish line! 🎉 And, hopefully, learned a bit more about React, D3.js, and requestAnimationFrame.

When it comes to D3, we barely scratched the surface, using only the fraction of its power, but I'm sure exploring the immense capabilities of it will now feel less like embarking into a terra incognita (with a torch in form of scaleTime and interpolateNumber that we used!)

We certainly can make the initial project better, adding more features and visual effects. Some ideas for you to consider, from easier to harder level of challenge:

Actual card expand behavior: right now it's just a placeholder alert, but you probably want to direct the user to a full article about the item. It could be a modal, a new page in a separate tab, or a combination of both!
Inverted vertical layout on mobile: sure, our responsive layout is not bad for a tablet or resizing a desktop display for one half of the screen, but many people would like to see your work on mobile, as well. I would address it with a vertical and years-inverted layout. For this, you'd need to add a couple of new properties and methods to the TimelineEngine class (or maybe go full OOP and make two version of the class for horizontal and vertical layouts!), tweak the paths.ts, lanes.ts, and add a couple of constants for vertical layout.
Ticks and baseline entrance animation: in my original project, I used Svelte's built-in transitions. In React, I think a good approach could be to use something like Motion to wrap the NodeCard, baseline and paths with the special animatable components.
Twists and turns for the nodes' connectors: who told us that they should be straight lines?! (Okay, I did, but let's skip that part) You can try and make the connector lines follow a path around other cards, avoiding collisions, and connecting from different sides. Might be tricky, and I can imagine paths.ts and lanes.ts would need to know a bit more about each other.
Let the user drag the cards around: make it a real map! This is probably going to be the most intense, and I imagine that TimelineEngine class would become driven by a forceSimulation, with a custom collision detection for bounding boxes (note that the original forceSimulation is originally aimed at circle nodes with a radius property!)

And, of course, share the results of your work on the socials, the comments for this post, or the issues in the repository! Don't hesitate to reach out in the comments, via email or LinkedIn.

That would be it for this tutorial! If you liked it, please like, share and bookmark it here and on the socials. I hope it helps you to build a great portfolio to showcase your awesome achievements, or sparks an idea for another project.

Have a good one!

Timeline portfolio map with React and D3.js | Part I

Dmitry — Thu, 24 Sep 2026 20:51:35 +0000

Hi there! In this tutorial, we are going to build a fun project that you can use as a foundation for your interactive portfolio.

Some time ago, when I decided to update my portfolio and started looking for inspiration, I ran into an issue: there are a lot of bombastic examples out there, but most of them, if not all, are a better fit for visuals-heavy careers: designers of all types, architects, artists. As a software developer, even if you do a lot of front-end, sometimes it's hard to turn a great project you worked on into a great visual story. Moreover, if you want to showcase different types of data, career milestones, academic track, events, awards, it doesn't become better. An idea came to me: what if a portfolio could be in the form of a "map", spread across a timeline?

The outcome was my current portfolio, built with SvelteKit and D3.js. My friends and former colleagues liked it, and suggested turning it into a tutorial, so here we are! However, because React is a far more popular library than Svelte, I decided to make it a React tutorial. If you didn't plan to use React in the portfolio of your own - no worries, the fundamental parts will transfer to other popular front-end libraries.

We are going to use the power of D3.js for calculating the layout, and React for rendering the UI.

This is going to be a two-part series, and the end result of our work would look something like this:

Interactive demo

If you want to build something similar and use it in your own project, let's dive in!

All of the code is available in the dedicated GitHub repository, with the folders inside the src/ directory containing the code for the corresponding sections. Feel free to clone/fork or simply open it as a read-along while working through the tutorial.

This post is also available in Spanish on my website.

Prerequisites, tech stack and scope
Initial setup and structure
Data models and sample data
Responsive timeline map
Putting nodes on timeline

Prerequisites, tech stack and scope

We are going to go through the project step by step; however, it is going to be more of an intermediate tutorial. To feel comfortable throughout the sections, my recommendation would be to:

Be familiar with TypeScript; we're not going super-fancy, but there'll be some generics here and there
Know your way around React.js; finished the official docs or went through a bootcamp would be a good milestone
Be acquainted with SVG structure and main parts; no need to be an Adobe Illustrator or Inkscape guru, but recognizing core parts of an SVG image would help
Understand CSS/SCSS modules; we're not going to use Tailwind or CSS-in-JS, going with a more "neutral" option, while still having the benefit of scoped styles

Of course, if you don't check all the boxes, and I still encourage you to dare and try, but be ready for your browser tabs panel go VROOOM as you look up the additional materials.

When it comes to tech stack, we're going to use a standard Vite project initializer with TypeScript template, Eslint and Prettier for code linting and formatting, and a few additional libraries:

D3.js - for calculating the layout positions, and, further in the tutorial, easings and interpolations for the resize animation
sass-embedded - for using .scss modules; full counterpart of the sass package, but compatible with the recent versions of:
vite-plugin-sass-dts - a plugin for Vite that generates types for scss modules on the fly
classnames - a library for dynamic styles
react-use - a toolbox of React hooks; here we'll use it for measuring elements' dimensions.

Another note, to keep this tutorial just enormous, and not gargantuan, we're going to skip some of the features from my original project, including:

Entrance animations
Switching to inverted vertical layout on mobile
Actual behavior on expanding the card

Those are all interesting topics, but I'm sure that after going through the tutorial, you'd be able to implement them on your own, and bring more creativity to it!

Initial setup and structure

Code for the section

Take a look at the repository linked above, you can clone or open it as a reference. It is a basic Vite+React application: it has some basic global CSS defined in the index.css, the entry point is main.tsx, and in vite.config.ts we have the sassDts plugin that will generate TypeScript types for SCSS modules.

The interesting folder is /lib - here lives the code we're going to work on. But before we jump into the code, let's think for a moment about what we're about to build.

To formulate our key requirements in a few sentences:

We are going to build a React component that will take career stages' and projects' data as props, render a responsive timeline, and distribute the data items/nodes in a temporal manner over the X-axis in the form of cards, putting items on different lanes below and above baseline to avoid collisions. The calculations of the items' positions are going to be delegated to a separate module. An item can be a single date project (e.g. conference talk), or a long-term commitment that can either be a range or to be open-ended (e.g. a full-time position in a company). Items will be connected to the central axis with lines, and different lines will represent different temporal options: simple straight stem for a project, and a bridge or a continuous arc for a commitment.

Now, let's get back to the /lib folder. Here, we have the scaffold of the structure we've just discussed:

src/lib/timeline/data - this will hold the sample data: a history of education, career milestones and projects. In a real-life, this data would likely come from an API or from the filesystem in a more sophisticated manner, but for our purposes, a simple exported JS array of objects would do
src/lib/timeline/components - contains React Components TimelineMap and NodeCard
- src/lib/timeline/components/TimelineMap - this will be our "main" component for rendering the timeline. It will take the data as props, pass it to the processing engine, and then render the data over the x and y axes
- src/lib/timeline/components/NodeCard - this will take the data for an item as props, and then render it as a card
src/lib/timeline/engine - contains the core parts of the module handling calculations for the month and year ticks, and the nodes' positions
- src/lib/timeline/engine/constants.ts - a place where we'll define some shared constants
- src/lib/timeline/engine/types.ts - here, the shared interfaces and types will live
- src/lib/timeline/engine/lanes.ts - will contain the logic for distributing the nodes over the lanes and avoiding collisions
- src/lib/timeline/engine/paths.ts - will contain the logic for drawing SVG paths to the nodes from the baseline
- src/lib/timeline/engine/index.ts - will export the TimelineEngine class, responsible for the calculations

Glancing through this structure, you might ask:

Hey, is all of this stuff in the /engine folder really necessary? 🤔 Couldn't we simply put both the rendering, and the calculations inside the TimelineMap component?

That's a good question! In this great video, Cory Cone provides a great overview on three possible ways of using D3.js with React: D3-driven chart, scoped D3 chart, and React-owned chart. In our case, we're going with the third approach: React-owned rendering, with D3 handling the "math". Ideally, TimelineMap is not going to know anything (or, at least, very little) about the underlying engine's inner shenanigans. It will pass the state updating handlers to the engine and be busy rendering the state to the screen. The code related to the calculations is going to be rather large, and dissecting it further into the modules will help us keep the code readable and clean.

Copy the stub files to your editor (if you've started from scratch), and let's start modelling the data!

Data models and sample data

Code for the section

First, let us define the interface that will shape the input data. I'd start with the primitives. We know that we're going to have two types of items - one-shot project and long-term commitment, let's add them to the src/lib/engine/types.ts

export type NodeType = "commitment" | "project";

We also know that some of the items will be above, and some below the baseline. However, we probably want some space for a manual override, in case we want a specific node to always be above or below:

export type DisplaySide = "above" | "below";

Now, we're ready for the interface for the data itself. I would call it TimelineNodeData. It will have an id, title, type, preferredSide and some other metadata necessary to render a nice-looking card.

export interface TimelineNodeData {
  id: string;
  type: NodeType;
  title: string; // Position at a company or name of the project/event
  organization?: string; // Could be a company or a school
  organizationLogoUrl?: string;
  thumbnailUrl?: string;
  summary: string;
  date: string;
  endDate?: string; // Used only for `commitment`
  ongoing?: boolean; // Additional boolean flag for convenience; Used only for `commitment`
  preferredSide?: DisplaySide;
}

But this lacks any information about the coordinates! Let's extend our interface with the layout-related fields, and call it TimelineNode, as it will represent the actual node on the timeline:

export interface TimelineNode extends TimelineNodeData {
  x: number; // x-axis position for the `NodeCard`
  y: number; // y-axis position for the `NodeCard`, i.e. y of its lane

  side: DisplaySide;
  startX: number; // point on the baseline/axis where the bridge/stem originates
  endX?: number; // point on the baseline/axis where the bridge returns back (only for `commitment` with endDate)
  laneIndex: number; // index of the lane from 0 to N
}

Last but not least, in our TimelineMap, we will draw some month and year ticks, and having an interface for them would be handy. Let's call it TimelineTick, and it will have the date, position x, and a label - month or year:

export interface TimelineTick {
  date: Date;
  x: number;
  label: string;
}

These few interfaces will be the glue of our application. Now we can finally define some sample data in the /lib/timeline/data.index.ts:

import type { TimelineNodeData } from "../engine/types";

export const data: TimelineNodeData[] = [
// Commitments - education and long-running positions
{
  id: "university-undergraduate-degree",
  type: "commitment",
  date: "2017-09-01",
  endDate: "2021-07-01",
  title: "Bachelor of Science",
  organization: "University of Applied Technology",
  organizationLogoUrl: "/logos/university.svg",
  thumbnailUrl:
    "https://images.unsplash.com/photo-1531482615713-2afd69097998?auto=format&fit=crop&w=1200&q=80",
  summary:
    "Completed a Bachelor of Science focused on technology, engineering, and applied problem solving.",
  preferredSide: "below",
  },
...
];

I've prepared some sample data in the corresponding folder for a character (let's call her Jane Doe) with an epic education and employment history. Feel free to use it, or fill it in with your own data right away. Please note that the logos' URLs are relative and point to the /public folder.

Finally, we can show something on the screen! Modify the src/App.tsx and src/lib/timeline/components/TimelineMap/index.tsx to show the stringified data:

App.tsx

import "./App.css";
import { data } from "./lib/timeline/data";
import TimelineMap from "./lib/timeline/components/TimelineMap";

function App() {
  return (
    <>
      <main className="main">
        <TimelineMap data={data} />
      </main>
    </>
  );
}

export default App;

TimelineMap/index.tsx

import type { TimelineNodeData } from "../../engine/types";
import styles from "./styles.module.scss";
import classNames from "classnames/bind";

const cx = classNames.bind(styles);

type Props = {
  data: TimelineNodeData[];
};

const TimelineMap: React.FC<Props> = ({ data }) => {
  return <>{JSON.stringify(data)}</>;
};

export default TimelineMap;

Interactive demo

Not much at the moment, but we'll be getting there!

Responsive timeline map

Code for the section

Our next step is to render the timeline map's foundation: a responsive SVG with baseline and year and month ticks. We'll be working on our engine class TimelineEngine located in src/lib/timeline/engine/index.ts and the TimelineMap React component in src/lib/timeline/components/TimelineMap/index.tsx.

Let's start with the engine. Essentially, it's going to be a TypeScript class that takes the input data, dates range, information about screen size and a few handlers from the TimelineMap component. It will calculate the layout, and then use the passed-in handlers to update the stateful values and trigger the UI re-render. It will expose a single method resize that will run when the dimensions change.

Based on this, we can define the constructor parameters for the class:

src/lib/timeline/engine/index.ts

type ConstructorParameters = {
  data: TimelineNodeData[];
  width: number;
  domainStart: Date;
  domainEnd: Date;
  onUpdateTicks: (yearTicks: TimelineTick[], monthTicks: TimelineTick[]) => void;
};

Wait a second! What the heck is a domain though?

That's a good question! Here we're going to use some of the D3's terminology. For creating a responsive temporal layout, we're going to use the scaleTime function from the d3-scale package. The function takes two parameters: domain and range. The former is a very fancy (and math-y!) name for an array of numbers that are going to be scaled, in our case, that would be the start and the end date of our timeline. The latter is basically a range of pixels into which we're going to squeeze our dates.

Let's add some private properties and a constructor to the TimelineEngine class:

import { scaleTime, type ScaleTime } from "d3-scale";
...
export class TimelineEngine {
  private xScale: ScaleTime<number, number>;
  private domainStart: Date;
  private domainEnd: Date;
  private onUpdateTicks: (yearTicks: TimelineTick[], monthTicks: TimelineTick[]) => void;

  constructor({
    width,
    domainStart = new Date(2017, 0, 1),
    domainEnd = new Date(),
    onUpdateTicks,
  }: ConstructorParameters) {
    this.domainStart = domainStart;
    this.domainEnd = domainEnd;
    this.onUpdateTicks = onUpdateTicks;
  }
}

Since Jane Doe's portfolio in the sample data starts in ~2017, it makes sense to make 2017 the start of our timeline, and to make the present date the end of the domain.

So far so good! However, what is xScale? Why haven't we used the width parameter yet?

We're about to! The xScale will be an instance of ScaleTime that we will use to get the coordinates of the ticks for years and months. Let's initialize it:

...
export class TimelineEngine {
  ...
  constructor({
    width,
    domainStart = new Date(2017, 0, 1),
    domainEnd = new Date(),
    onUpdateTicks,
  }: ConstructorParameters) {
    ...

    this.xScale = scaleTime()
      // The earliest and latest dates on the timeline
      .domain([this.domainStart, this.domainEnd])
      // The range of px from the left-most side to the right-most side
      .range([
        0,
        width,
      ]);
  }
}

Now, we have what we need to calculate the positions of the ticks and create the TimelineTick[] array! We'll need to import some helper methods from d3 and initialize a couple of formatters:

...
import { timeFormat, timeMonth, timeYear } from "d3";

const formatYear = timeFormat("%Y");
const formatMonth = timeFormat("%b");
...

We can now implement a private helper method for getting the ticks, called updateTicks. Place it below the constructor:

...
export class TimelineEngine {
  ...
  constructor({
    ...
  })

  ...
  private updateTicks() {
    const yearTicks: TimelineTick[] = timeYear
      .range(this.domainStart, this.domainEnd)
      .map((date) => ({
        date,
        x: this.xScale(date),
        label: formatYear(date),
      }));

    const monthTicks: TimelineTick[] = timeMonth
      .range(this.domainStart, this.domainEnd)
      .filter((date) => date.getMonth() !== 0) // Skip January, as it matches the positions of `yearTicks`
      .map((date) => ({
        date,
        x: this.xScale(date),
        label: formatMonth(date),
      }));

    this.onUpdateTicks(yearTicks, monthTicks);
  }
}

Inside the method, we use the .range() method of timeYear and timeMonth, which returns an array of Dates Date[]. Then, we chain a JS Array.map() to iterate over the ranges and return arrays that hold objects in the shape of TimelineTick. And then we store the result in the variables yearTicks and monthTicks.

A-ha, but what about the this.onUpdateTicks(yearTicks, monthTicks) call?

That's the most interesting part of the method! Here, we're actually updating the UI. The onUpdateTicks parameter is a function that would come from the "React world", and it is our bridge (a very restricted one, so as not to break React's rendering!) from the calculated values inside TimelineEngine into the UI itself. We will run this function on mount, and during resizing, to support a responsive design.

However, instead of calling it directly at the end of the constructor, let's add another private helper method for synchronizing the layout. Add it below the constructor and call at the bottom of the constructor:

...
export class TimelineEngine {
  ...
  constructor({
    ...

    this.syncLayout();
  })

  ...
  private syncLayout() {
    this.updateTicks();
  }
  ...
}

Now, we're ready to start updating the UI! Open up the TimelineMap component, and let's add the following code to it:

import React, { Fragment, useCallback, useEffect, useRef, useState } from "react";
import styles from "./styles.module.scss";
import classNames from "classnames/bind";
import type { TimelineNodeData, TimelineTick } from "../../engine/types";
import { TimelineEngine } from "../../engine";

const cx = classNames.bind(styles);

type Props = {
  data: TimelineNodeData[];
};

const domainStart = new Date(2017, 0, 1);
const domainEnd = new Date();

const TimelineMap: React.FC<Props> = ({ data }) => {
  const timelineEngineInstanceRef = useRef<TimelineEngine>(null);

  const [yearTicks, setYearTicks] = useState<TimelineTick[]>([]);
  const [monthTicks, setMonthTicks] = useState<TimelineTick[]>([]);

  const handleUpdateTicks = useCallback((yearTicks: TimelineTick[], monthTicks: TimelineTick[]) => {
    setYearTicks(yearTicks);
    setMonthTicks(monthTicks);
  }, []);

  useEffect(() => {
    if (!timelineEngineInstanceRef.current) {
      // Instantiate the TimelineEngine if not present
      timelineEngineInstanceRef.current = new TimelineEngine({
        data,
        domainStart: new Date(2017, 0, 1),
        domainEnd: new Date(),
        width: window.innerWidth,
        onUpdateTicks: handleUpdateTicks,
      });
    }
  }, [data, handleUpdateTicks]);

  return (
    <div className={styles["scroll-wrapper"]}>
      {!window.innerWidth ? null : (
        <div className={styles["inner-content"]} style={{ width: window.innerWidth }}>
          <svg
            className={styles["svg-map"]}
            style={{
              width: window.innerWidth,
              height: window.innerHeight,
            }}
            aria-hidden={true}
          >
            {/* Baseline */}
            <line className={styles["baseline"]} x1={0} x2={contentWidth} y1={axisY} y2={axisY} />

            {/* Month ticks */}
            {monthTicks.map((tick, i) => {
              return (
                <line
                  key={i}
                  className={cx(styles["month-tick"])}
                  x1={tick.x}
                  x2={tick.x}
                  y1={axisY - 8 / 2}
                  y2={axisY + 8 / 2}
                />
              );
            })}

            {/* Year ticks */}
            {yearTicks.map((tick, i) => {
              return (
                <Fragment key={i}>
                  <text className={styles["year-label"]} x={tick.x} y={18}>
                    {tick.label}
                  </text>
                  <line
                    className={styles["year-tick"]}
                    x1={tick.x}
                    x2={tick.x}
                    y1={0}
                    y2={window.innerHeight}
                  />
                  <text
                    className={styles["year-label"]}
                    x={tick.x}
                    y={window.innerHeight - 12}
                  >
                    {tick.label}
                  </text>
                </Fragment>
              );
            })}
          </svg>
        </div>
      )}
    </div>
  );
}

Wow! A lot is going on here. Let's dissect the key parts.

First, we declare module variables for the start and end date, which we're going to pass to the TimelineEngine. They are declared outside of the TimelineMap's body and would be re-initialized on every render, so they are not needed in the hooks' dependencies arrays.

const domainStart = new Date(2017, 0, 1);
const domainEnd = new Date();

Then, we declare a ref that will hold an instance of TimelineEngine, initially being null (Notice how having TimelineEngine as a class gives us a convenient interface right away to be used in the useRef<INTERFACE>() generic).

const timelineEngineInstanceRef = useRef<TimelineEngine>(null);

After that, we declare state variables yearTicks and monthTicks, and a unified handler handleUpdateTicks that combines updating them.

const [yearTicks, setYearTicks] = useState<TimelineTick[]>([]);
const [monthTicks, setMonthTicks] = useState<TimelineTick[]>([]);

const handleUpdateTicks = useCallback((yearTicks: TimelineTick[], monthTicks: TimelineTick[]) => {
  setYearTicks(yearTicks);
  setMonthTicks(monthTicks);
}, []);

Inside the useEffect, we instantiate the TimelineEngine if it's not there yet, and store it inside the timelineEngineInstanceRef.current. We pass the previously declared domainStart and domainEnd, data, the handleUpdateTicks handler, and for the width we pass the current window.innerWidth (We're in the client-side browser world, and this is relatively safe).

useEffect(() => {
  if (!timelineEngineInstanceRef.current) {
    // Instantiate the TimelineEngine if not present
    timelineEngineInstanceRef.current = new TimelineEngine({
      data,
      domainStart: domainStart,
      domainEnd: domainEnd,
      width: window.innerWidth,
      onUpdateTicks: handleUpdateTicks,
    });
  }
}, [data, handleUpdateTicks]);

Finally, we render the actual UI. We have a couple of <div /> wrappers, an <svg /> that will contain our graphics, and inside of it we draw the baseline right in the middle of the screen by diving the screen height in half

<line
  className={styles["baseline"]}
  x1={0}
  x2={window.innerWidth}
  y1={window.innerHeight / 2}
  y2={window.innerHeight / 2}
/>

and then we map over the stateful yearTicks and monthTicks to render longer screen-height lines for years, and shorter ticks across the baseline.

If you're working from scratch, the linter is likely all red right now, because it cannot find the required CSS classes. Add the following SCSS code to src/lib/timeline/components/TimelineMap/styles.module.scss:

.scroll-wrapper {
  position: relative;
  width: 100%;
  height: 100%;
  min-height: 420px;
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
  touch-action: pan-x pan-y;
  overscroll-behavior-x: contain;
  scrollbar-width: thin;

  .inner-content {
    position: relative;
    height: 100%;
    min-height: 420px;
    margin-inline: auto;

    .svg-map {
      position: absolute;
      inset: 0;
      pointer-events: none;
    }

    .baseline {
      stroke: var(--timeline-map-color-stroke);
      stroke-width: 1;
    }

    .month-tick {
      stroke: var(--timeline-map-color-stroke);
      stroke-width: 1;
      opacity: 1;
    }

    .year-tick {
      stroke: var(--timeline-map-color-stroke);
      stroke-width: 1;
      opacity: 0.65;
    }

    .year-label {
      fill: var(--timeline-map-color-text-label);
      font-size: 0.75rem;
      text-anchor: middle;
      font-variant-numeric: tabular-nums;
    }
  }
}

Oof, that was a lot of code! If you take a look at the screen right now, you should see a chart with a baseline and month ticks over it, year ticks with labels. Yes, we finally got something interesting on the screen, but before we proceed with the nodes, we could do better.

Our current approach is kinda "naive", and has some obvious flaws:

We have a lot of "magic numbers", especially around month ticks and year ticks' offsets. Right now, we may remember that 8 in y1={window.innerHeight / 2 - 8 / 2} is actually a height of a month tick, but we will forget it in an hour.
The way we find the width and height is very fragile. In a real-life application, our portfolio is likely going to be a part of a larger layout, with navbars, footers, elements below, above, and aside from the chart. We need to make the width and height scoped to the area we render our chart in.
Our layout is not responsive. Like, at all! We probably want to have a certain min and max width of the space between two year ticks, to squeeze the layout on smaller screens down to a certain point, and stretch it up a bit on larger screens.
The year ticks labels are cut-off, especially on the left side. We want to add some "air" to our chart and let it breath a bit 🧘

Let's address those one by one!

First, time to add some constants to the src/lib/timeline/engine/constants.ts:

// Month and year ticks dimensions
export const MONTH_TICK_HEIGHT_PX = 8;
export const YEAR_LABEL_TOP_OFFSET_PX = 18;
export const YEAR_LABEL_BOTTOM_OFFSET_PX = 12;

And use them where appropriate:

...
{/* Month ticks */}
{monthTicks.map((tick, i) => {
  return (
    <line
      key={i}
      className={cx(styles["month-tick"])}
      x1={tick.x}
      x2={tick.x}
      y1={window.innerHeight / 2 - MONTH_TICK_HEIGHT_PX / 2}
      y2={window.innerHeight / 2 + MONTH_TICK_HEIGHT_PX / 2}
    />
  );
})}
...
<text className={styles["year-label"]} x={tick.x} y={YEAR_LABEL_TOP_OFFSET_PX}>
  {tick.label}
</text>
...
<text
  className={styles["year-label"]}
  x={tick.x}
  y={window.innerHeight / 2 - YEAR_LABEL_BOTTOM_OFFSET_PX}
>
  {tick.label}
</text>

Now, let's say goodbye to the elephant in the room: window.innerHeight / 2 and the like. We're going to measure not the window, but the scroll element container with a handy hook from react-use:

...
const [scrollElementRef, { width: scrollWrapperWidth, height: scrollWrapperHeight }] =
  useMeasure<HTMLDivElement>();
...
  return (
    <div className={styles["scroll-wrapper"]} ref={scrollElementRef}>
  ...
  )
...

We can now get rid of window.innerHeight and window.innerHeight / 2, and introduce a derived variable axisY:

// Position of the baseline
const axisY = useMemo(() => scrollWrapperHeight / 2, [scrollWrapperHeight]);

and then update all of the instances of window.innerHeight / 2:

...
{/* Baseline */}
<line className={styles["baseline"]} x1={0} x2={contentWidth} y1={axisY} y2={axisY} />
...
{/* Month ticks */}
{monthTicks.map((tick, i) => {
  return (
    <line
      key={i}
      className={cx(styles["month-tick"])}
      x1={tick.x}
      x2={tick.x}
      y1={axisY - MONTH_TICK_HEIGHT_PX / 2}
      y2={axisY + MONTH_TICK_HEIGHT_PX / 2}
    />
  );
})}

Ok, and then to the responsive layout. We want to have a min and max value for the horizontal space between two year ticks, which will help us find the minContentWidth and maxContentWidth, and then actually calculate the contentWidth that we want. Let's add the new constants to src/lib/timeline/engine/constants.ts:

// Timeline horizontal space between years
// Below this density, we scroll instead of squeezing further
export const MIN_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX = 70;
// Above this density, we stop stretching and center instead
export const MAX_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX = 180;

And then, just above TimelineMap (once again, avoiding re-initialization on every render), add minContentWidth and maxContentWidth as a multiplication of the value by the number of years on the timeline:

...
const domainStart = new Date(2017, 0, 1);
const domainEnd = new Date();
const domainYears = domainEnd.getFullYear() - domainStart.getFullYear();
const minContentWidth =
  MIN_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX * domainYears;
const maxContentWidth =
  MAX_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX * domainYears;

const TimelineMap: React.FC<Props> = ({ data }) => {
  ...
}

With those in place, we can define a derived variable contentWidth. We don't want to exceed the maxContentWidth constant, but choose the largest between the width of the scroll wrapper and minContentWidth:

const TimelineMap: React.FC<Props> = ({ data }) => {
  ...
  const contentWidth = useMemo(() => {
    return Math.min(Math.max(scrollWrapperWidth, minContentWidth), maxContentWidth);
  }, [scrollWrapperWidth]);
  ...
}

And then use it instead of the window.innerWidth in all of the cases:

...
useEffect(() => {
  if (!contentWidth) {
    return;
  }

  if (!timelineEngineInstanceRef.current) {
    // Instantiate the TimelineEngine if not present
    timelineEngineInstanceRef.current = new TimelineEngine({
      data,
      domainStart: domainStart,
      domainEnd: domainEnd,
      width: contentWidth,
      onUpdateTicks: handleUpdateTicks,
    });
  }
}, [contentWidth, data, handleUpdateTicks]);
...
return (
  <div className={styles["scroll-wrapper"]} ref={scrollElementRef}>
    {contentWidth === 0 || scrollWrapperHeight === 0 ? null : (
      <div className={styles["inner-content"]} style={{ width: contentWidth }}>
        <svg
          className={styles["svg-map"]}
          style={{
            width: contentWidth,
            height: scrollWrapperHeight,
          }}
          aria-hidden={true}
        >
          {/* Baseline */}
          <line className={styles["baseline"]} x1={0} x2={contentWidth} y1={axisY} y2={axisY} />
          ...
        </svg>
      </div>
    )}
  )

That's now better! Now we can make our layout responsive, by implementing a public resize method in the TimelineEngine:

...
export class TimelineEngine {
  ...
  constructor({
    ...
  }: ConstructorParameters) {
    ...
  }

  resize(newWidth: number) {
    this.xScale = scaleTime()
      .domain([this.domainStart, this.domainEnd])
      .range([0, newWidth]);

    this.syncLayout();
  }
  ...
}

And use the resize method inside the useEffect in TimelineMap. Essentially, the only value here that is going to update is contentWidth, so if the timelineEngineInstanceRef.current already has been initialized we run the resizing logic:

...
useEffect(() => {
  if (!contentWidth) {
    return;
  }

  if (!timelineEngineInstanceRef.current) {
    // Instantiate the TimelineEngine if not present
    timelineEngineInstanceRef.current = new TimelineEngine({
      data,
      domainStart: domainStart,
      domainEnd: domainEnd,
      width: contentWidth,
      onUpdateTicks: handleUpdateTicks,
    });
  } else {
    // Run `resize` method on change
    timelineEngineInstanceRef.current.resize(contentWidth);
  }
}, [contentWidth, data, handleUpdateTicks]);
...

And finally, we can address the horizontal bleeds of the timeline map. Let's add a new variable to the src/lib/timeline/engine/constants.ts:

// Horizontal space on both ends of the timeline content area
export const TIMELINE_HORIZONTAL_PADDING_PX = 80;

And incorporate it in both TimelineMap:

...
const minContentWidth =
  MIN_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX * domainYears + TIMELINE_HORIZONTAL_PADDING_PX * 2;
const maxContentWidth =
  MAX_TIMELINE_HORIZONTAL_SPACE_PER_YEAR_PX * domainYears + TIMELINE_HORIZONTAL_PADDING_PX * 2;
...

and in TimelineEngine:

...
export class TimelineEngine {
  ...

  constructor({
    width,
    ...
  }: ConstructorParameters) {
    ...

    this.xScale = scaleTime()
      .domain([this.domainStart, this.domainEnd])
      .range([
        TIMELINE_HORIZONTAL_PADDING_PX,
        Math.max(width - TIMELINE_HORIZONTAL_PADDING_PX, TIMELINE_HORIZONTAL_PADDING_PX),
      ]);

    this.syncLayout();
  }

  resize(newWidth: number) {
    this.xScale.range([
      TIMELINE_HORIZONTAL_PADDING_PX,
      Math.max(newWidth - TIMELINE_HORIZONTAL_PADDING_PX, TIMELINE_HORIZONTAL_PADDING_PX),
    ]);

    this.syncLayout();
  }
  ...
}

We should have a nice responsive chart, that looks something like this:

Interactive demo

Putting nodes on timeline

Code for the section

Things are about to get interesting! For a breath of fresh air, let's work for a bit in another file. Open the src/lib/timeline/components/NodeCard/index.tsx, and instead of the scaffold code, add the following:

import type { TimelineNode } from "../../engine/types";
import styles from "./styles.module.scss";
import classNames from "classnames/bind";

const cx = classNames.bind(styles);

type Props = {
  node: TimelineNode;
};

const NodeCard: React.FC<Props> = ({ node }) => {
  return (
    <div
      style={{
        position: "absolute",
        left: `${node.x}px`,
        top: `${node.y}px`,
        transform: "translate(-50%, -50%)",
        background: "gray",
        color: "white",
        padding: "4px 6px",
      }}
    >
      {node.id}
    </div>
  );
};

export default NodeCard;

Don't mind the inline styles, we're going to address it later. For now, we just want to render a gray box with the node.id, and place it based on the node.x and node.y. We want to center it, so we apply a transform trick: transform: "translate(-50%, -50%)". This way, we'll simplify the coordinate calculations a bit.

Now, let's get back to the TimelineEngine. add the following new code to the ConstructorParameters, constructor, and the class' body:

...
type ConstructorParameters = {
  ...
  axisY: number; // the y of the baseline/axis, content height / 2
  onUpdateNodes: (nodes: TimelineNode[]) => void;
};

export class TimelineEngine {
  ...
  private timelineNodes: TimelineNode[];
  private onUpdateNodes: (nodes: TimelineNode[]) => void;

  constructor({
    ...
    axisY,
    onUpdateNodes,
  }: ConstructorParameters) {
    ...
    this.onUpdateNodes = onUpdateNodes;

    ...

    // Initialize the nodes
    this.timelineNodes = data.map((d) => ({
      ...d,
      x: 0,
      y: axisY,
      startX: 0,
      endX: undefined,
      side: "above", // placeholder for now
      laneIndex: 0, // placeholder for now
    }));

    ...
  }

  resize(newWidth: number, newAxisY: number) {
    ...
  }
  ...
}

Here, we've finally added the timelineNodes property, as well as the handler onUpdateNodes (will work the same as the onUpdateTicks), and a simple initialization logic. We also now provide the y position of the baseline as the axisY.

To get something on the screen, let's modify the TimelineMap:

...
const TimelineMap: React.FC<Props> = ({ data }) => {
  ...
  const [nodes, setNodes] = useState<TimelineNode[]>([]);
  const handleSetNodes = useCallback((updatedNodes: TimelineNode[]) => {
    setNodes(updatedNodes);
  }, []);
  ...
  useEffect(() => {
    if (!contentWidth || !axisY) {
      return;
    }

    if (!timelineEngineInstanceRef.current) {
      // Instantiate the TimelineEngine if not present
      timelineEngineInstanceRef.current = new TimelineEngine({
        data,
        domainStart: domainStart,
        domainEnd: domainEnd,
        width: contentWidth,
        axisY,
        onUpdateNodes: handleSetNodes,
        onUpdateTicks: handleUpdateTicks,
      });
    } else {
      // Run `resize` method on change
      timelineEngineInstanceRef.current.resize(contentWidth, axisY);
    }
  }, [contentWidth, axisY, data, handleSetNodes, handleUpdateTicks]);
  ...
  return (
    <div className={styles["scroll-wrapper"]} ref={scrollElementRef}>
      {contentWidth === 0 || scrollWrapperHeight === 0 ? null : (
        <div className={styles["inner-content"]} style={{ width: contentWidth }}>
          <svg...>
          </svg>
          {/* Node cards */}
          {nodes.map((node) => {
            return <NodeCard key={node.id} node={node} />;
          })}
        </div>
      )}
    </div>
  );
};

Same as with the yearTicks and monthTicks, we now have a stateful value nodes and a handler handleSetNodes for updating them. We then pass the new handler and the now-required axisY to the new TimelineEngine(), and iterate over the nodes inside the <div className={styles["inner-content"]}/> (but outside of the <svg/> element!)

Now the nodes will be squished at the beginning of the baseline. Let's distribute them across the x axis. Back to the TimelineEngine, we'll define a new ad-hoc NodeLayout interface, and couple of new private methods:

...
// Local helper type that holds only data for the coordinates
type NodeLayout = Pick<TimelineNode, "x" | "y" | "startX" | "endX" | "side" | "laneIndex">;
...
export class TimelineEngine {
  ...
  private syncLayout() {
    this.onUpdateNodes([...this.timelineNodes]);
    this.updateTicks();
  }

  // Helper function to determine the end date of a node
  private endOf(d: TimelineNodeData): Date {
    if (d.endDate) {
      return new Date(d.endDate);
    } else if (d.ongoing) {
      return this.domainEnd;
    } else {
      return new Date(d.date);
    }
  }

  private calculateLayout(axisY: number) {
    return new Map<string, NodeLayout>(
      this.timelineNodes.map((node) => {
        const startX = this.xScale(new Date(node.date));
        const endX = this.xScale(this.endOf(node));

        return [
          node.id,
          {
            // Since `endOf` returns the same date for a `project` we don't need any `if...else`'s here:
            // (x + x) / 2 = x
            x: (startX + endX) / 2,
            y: axisY,
            startX,
            endX: node.endDate || node.ongoing ? endX : undefined,
            side: "above", // placeholder for now
            laneIndex: 0, // placeholder for now
          },
        ];
      }),
    );
  }

  private applyLayout(layout: Map<string, NodeLayout>) {
    for (const node of this.timelineNodes) {
      const target = layout.get(node.id)!;

      node.x = target.x;
      node.y = target.y;
      node.startX = target.startX;
      node.endX = target.endX;
      node.side = target.side;
      node.laneIndex = target.laneIndex;
    }
    this.syncLayout();
  }
}

The core update here is the calculateLayout method, whose only parameter is the axisY. Its purpose is to calculate the appropriate x and y positions for the nodes, and store them in a Map. We added a tiny helper function endOf that helps to find the end date of the node (as you remember, we have three cases: one-shot project, terminated commitment, and ongoing commitment). In the applyLayout method we iterate over the timelineNodes property array, and look up the coordinates. We've also updated the syncLayout method to update both the ticks, and the nodes.

Then, let's use the new methods:

  constructor({
    ...
  }: ConstructorParameters) {
    ...

    const targetLayout = this.calculateLayout(axisY);

    this.applyLayout(targetLayout);
  }

  resize(newWidth: number, newAxisY: number) {
    const targetLayout = this.calculateLayout(newAxisY);

    this.applyLayout(targetLayout);
  }

The code we've just worked out might seem a bit over-complicated at first (Why the heck do we need a separate calculateLayout?!), but this is going to pay off really well in the final section 😉

Now, we should see something like this, a responsive mess squished on the baseline:

Interactive demo

If you got to this point, you're awesome! 💪 (and I hope you didn't do it all in one go!) But now please take a break before you proceed, because Part II will start with a tough task: we are going to distribute the nodes over the lanes. After that, it will be significantly more chill: we will be drawing some SVGs, tweaking the visuals, and implementing animations.

See you in the next part!

Let's Build Animated Pagination with React!

Dmitry — Sun, 15 Nov 2020 19:47:05 +0000

Hello there! In this tutorial, we are going to build a universal "smart" (i.e. stateful) pagination React functional Component with transition effect, suitable for listing out dynamic on-page data that doesn’t need a separate URL: users, comments, products, etc. This can be a useful feature in administration panels and comment sections of your projects, when you have a relatively long list of data that you might need to filter, search, and change dynamically.

The final goal

If you need to have a URL for each page, I would suggest getting the best from your client-side routing library of choice, for instance react-router, @reach-router, or, in-case of static-site generators, you can look up a Gatsby or Next.js-specific solution.

Besides that, we are going to touch upon (pun intended) the browser touch events to flip our pages on mobile and tablet devices, examine one of the solutions for zero-dependency replayable animations in React, and see some use cases of refs, as well as stopPropagation() method of the React SyntheticEvent.

For convenience, I’ve created a small NPM module react-animated-pagination as well as a demo website for it that you can refer to and customize in your projects.

Prerequisites: intermediate JavaScript knowledge, a solid understanding of React and React Hooks. This post is aimed at fellow Reacters who are already familiar with the library's key features and might have already built some amazing projects, but want to see more examples on parts not so extensively covered in the official docs, like usage of refs and event propagation.

Problem and Objective Overview

In a React application, a typical use case for pagination is listing a set of items stored in the application's (or component’s) state. Usually, we need to iterate over an Array of JavaScript Objects, and create a React Component for each Object with a defined key prop and some itemName prop specific for the Component (post for PostComponent, user for UserCard, etc).

For instance, let's say we have fetched some posts from our API, and want display them as PostComponents that take specific handler methods as props:

const ContainerComponent = ({ posts, handleRemoveFromFeed, ... }) => {
...
  return (
    <div className="mainContainerDiv">
...
  {
    posts && posts.map(post => (
      <PostComponent>
        key={post.uniqueId}
        post={post}
        handleRemoveFromFeed={handleRemoveFromFeed}
        handleUpvote={handleUpvote}
        handleDownvote={handleDownvote}
        handleAddComment={handleAddComment}
      </PostComponent>
    ))
  }
...

Now, our posts Array is listed alright, with all the handlers working correctly. We defined the key prop, so that the React Diffing Algorithm knows about the rendered elements (in case some of them gets removed from the state, with the handleRemoveFromFeed handler, for example), the value of the post prop is the value of the item in the current iteration of the Array.

But turns out, we got hundreds of posts we need to display! We'd better present them neatly in a "page-like" format. Adding basic pagination is not that complex, we can simply add some logic to our parent component with the useState and useEffect Hooks:

// This snippet is not a fully working example, 
// just an overview of one of the solutions
import React, { useState, useEffect } from "react";

const ContainerComponent = ({ posts, handleRemoveFromFeed, ... }) => {
...
  // The number of items to display
  const itemsPerPage = 5;
  // The Array of subarrays with posts divided according to the value of itemsPerPage
  const [pages, setPages] = useState([]);
  // The index of pages Array - this will be the current visible page
  const [currentPage, setCurrentPage] = useState(0);

  // A handler for changing the page
  const handlePageChange = (pageNo) => {
    setCurrentPage(pageNo);
  };

  // In the first useEffect Hook, we assemble and re-assemble
  // pages Array that contains several subArrays of our passed-in
  // posts Array, every time the posts prop changes 
  // (e.g. on post being removed)
  useEffect(() => {
    let workingPages = [];
    let workingPagesCurrentIndex = 0;

    if (posts) {
      posts.forEach(post => {
        if (
          workingPages[workingPagesCurrentIndex] &&
          workingPages[workingPagesCurrentIndex].length === itemsPerPage
        )
          workingPagesCurrentIndex++;

        if (workingPages[workingPagesCurrentIndex] === undefined)
          workingPages[workingPagesCurrentIndex] = [];

        workingPages[workingPagesCurrentIndex].push(item);
      });
    }

    setPages([...workingPages]);
  }, [posts, setPages]);

  // This Hooks runs every time when currentPage index changes 
  // withhandlePageChange() or when the number of pages changes
  // (for instance, when we delete an item)
  useEffect(() => {
    if (!pages[currentPage]) {
      setCurrentPage(currentPage - 1 > -1 ? currentPage - 1 : 0);
    }
  }, [currentPage, pages]);

  return (
    <div className="mainContainerDiv">
  ...
  {
  /*
  Buttons for handling changing the page
  */
  }
  <button 
    onClick={() => handlePageChange(currentPage - 1)}
    disabled={currentPage === 0 ? true : false}
  >
    Previous
  </button>
  <button 
    onClick={() => handlePageChange(currentPage + 1)}
    disabled={currentPage === pages.length - 1 ? true : false}
  >
    Next
  <button>
  {
  /*
  Iterate over the current subarray of posts to display them
  */
  }
  {
    pages.length && pages[currentPage] && pages[currentPage].map(post => (
      <PostComponent>
        key={post.uniqueId}
        post={post}
        handleRemoveFromFeed={handleRemoveFromFeed}
        handleUpvote={handleUpvote}
        handleDownvote={handleDownvote}
        handleComment={handleComment}
      </PostComponent>
    ))
  }
  ...
  );
}

This logic provides us with a basic pagination solution: to divide our Array-to-iterate state into an Array of subarrays called pages, with a state (currentPage) that indicates the currently visible section of the Array.

Defined inside the ContainerComponent, even this crude solution looks pretty huge, and let's not forget that we have some much to add! We need to create buttons that indicate the current page and other available pages to navigate the pagination, and we'd also better to have both top and bottom navigation for convenience. We definitely need to create a separate Pagination Component in order to avoid a total mess!

Extracting this logic in a separate stateful Component is not hard: it will take the posts to iterate over as props, and will contain all the buttons, navigation and styles, easy! However, here comes the catch: how do we pass all the handlers and universal data our paginated components might require? Of course, if we use Redux, MobX, or some other State Management library, this is not a big deal: our Post Components can receive all their handlers and required data from the Application's main state. But not all the projects (even relatively large ones) need Redux, and even not all Redux-based projects have all their state lifted up to Redux. Moreover, our Pagination right now is tailored exclusively for rendering PostComponents, and what if we need to paginate some, say, UserCards or CommentComponents? Do they need to have a special version of the PaginationUserCard or PaginationCommentComponent? Definitely not.

We need to create a universal Pagination Component suitable for the majority of cases. It will take the React Component to render (UserCard, PostComponent, etc.) as props, as well as some parameters, like, how many items are allowed per page, and whether we need to show bottom and top navigation.

We will build a small TODO-ish application that fetches JSON data - an Array of posts - from the jsonplaceholder API, converts it into an array of JavaScript Objects to be stored in the component’s state, iterates through the array and displays each item as a React component, which can be deleted on double click. Instead of making an immense list, the items will be neatly paginated with a special Pagination component we’re going to implement, the number of pages will be dynamic, changing when we delete items. Going back and forth between pages will be visually emphasized with a transition effect and support swipes. We will also add a universal prop totalLikes required by all the paginated items.

Basic Setup

At this step, we will create the base of our application, that will be able to fetch an array of posts from the jsonplaceholder API, store it in the component’s state, display them on the page by creating instances of Post component, handle click on a Posts "like button", and delete a post on double click.

Create a new React project

npx create-react-app pagination-example

And inside the src folder create a new file Post.js. Add the following code:

import React from "react";

const Post = ({ 
post, handleDelete, handleLikePost, totalLikes
}) => {

  return (
    <div
      className={`post`}
      // delete post with double-click on the post's container div
      onDoubleClick={(e) => {
        handleDelete(post.id);
      }}
    >
      <h3>{post.title}</h3>
      <p>{post.body}</p>
      {/* Show how many likes the post has */}
      <div>
        Likes: {post.likes ? post.likes : 0}{" "}
        {post.likes && totalLikes ? `out of ${totalLikes}` : ""}
      </div>
      <button
        className="post__likeBtn"
        // Like post on click
        onClick={(e) => {
          handleLikePost(post.id);
        }}
        // Avoid propagating the double click on the button 
        // so the post won't get deleted accidently 
        onDoubleClick={(e) => {
          e.stopPropagation();
        }}
      >
        <span role="img" aria-label="like button">
          💖
        </span>
      </button>
    </div>
  );
};

export default Post;

The structure of the above component is typical: it’s a “dumb” stateless component that takes all the data it needs to display from the post prop and the actual handler for deleting the post is passed through the handleDelete prop.

The only unusual part might be this handler:

onDoubleClick={(e) => {
  e.stopPropagation();
}}

Here we evoke a special method of React's synthetic event e.stopPropagation(), to avoid firing double-click event on the button's parent element. You've probably already encountered the e.preventDefault() method, usually implemented when submitting React-controlled forms with AJAX request, this one does roughly the same: overrides the default browser behavior. We will return to this method once we implement touch events in our Pagination.

Please note: here we use onDoubleClick event to handle delete logic for a mere demonstration and learning purpose. Putting something unobvious like this on double-click or double-tap might result in a horrifying user experience.

Let’s see our brand-new component in action. Open App.js file, delete all the initial code, and add the following:

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

import Post from "./Post";

export default function App() {
  // Loading indicator state
  const [isLoading, setIsLoading] = useState(false);
  // Posts state
  const [posts, setPosts] = useState([]);
  // Likes state
  const [totalLikes, setTotalLikes] = useState(0);

  // Handle delete post using Array.filter() higher order function
  const handleDelete = (id) => {

    // In a real-world application we would probably track the changing
    // number of likes with useEffect() Hook, but since we are in full
    // control over the data, we can directly set totalLikes here for simplicity
    let postTodelete = posts.find((p) => p.id === id);
    if (postTodelete.likes && totalLikes) {
      setTotalLikes((totalLikes) => totalLikes - postTodelete.likes);
    }

    // Note that we don't mutate the original state
    let postsFiltered = [...posts.filter((p) => p.id !== id)];

    setPosts((posts) => [...postsFiltered]);
  };

  // Once again, here we simplify the "liking logic" greatly
  const handleLikePost = (id) => {
    let workingPosts = [...posts];

    workingPosts.find((p) => p.id === id).likes
      ? workingPosts.find((p) => p.id === id).likes++
      : (workingPosts.find((p) => p.id === id).likes = 1);

    setPosts((posts) => [...workingPosts]);
    setTotalLikes((totalLikes) => totalLikes + 1);
  };

  // Fetch the data from API on the first render of the App
  useEffect(() => {
    const fetchPosts = async () => {
      try {
        setIsLoading(true);

        const posts = await fetch(
          "https://jsonplaceholder.typicode.com/posts",
          {
            method: "GET"
          }
        ).then((res) => res.json());

        setPosts([...posts]);
        setIsLoading(false);
      } catch (err) {
        console.log(err);
        setIsLoading(false);
      }
    };

    fetchPosts();
  }, []);

  // As soon is isLoading is equal to false and posts.length !== 0
  // we iterate over the huge Array of Objects to render Post components
  // on each iteration
  return (
    <div className="App">
      <h1>React Simple Pagination</h1>
      <h2>Basic setup</h2>
      <h3>Total Likes: {totalLikes ? totalLikes : 0}</h3>
      {isLoading && posts.length === 0 ? (
        <div>Loading...</div>
      ) : (
        posts &&
        posts.map((post) => (
          <Post
            key={post.id}
            post={post}
            handleDelete={handleDelete}
            handleLikePost={handleLikePost}
            totalLikes={totalLikes}
          />
        ))
      )}
    </div>
  );
}

We defined a stateful App component, with the state being a posts Array, isLoading boolean, and totalLikes number. We defined a handler for deleting a post from the state array via the Array.filter() and also a handler for "liking" a post. Inside useEffect (with an empty array [] as the second parameter to run it only on the initial render), we defined and invoked asynchronous function fetchPosts() that sets the isLoading to true when the loading process starts, sets it to false when it finishes, and sets the posts to the response of the request. The function code is wrapped into a try...catch block. If you need a reference to fetching data with React Hooks, please, check out this wonderful article by Robin Wieruch.

In the return part we first check if our load has started, and display a “Loading...” message to the screen. Once isLoading is set to false, we iterate through the state array of posts with .map() method and "return" a Post component for each item of the array, passing the item itself as the post prop, .id property for its key, handleDelete and handleLikePost handlers for the respective prop.

Launch the project, and open the browser tab. Run the application with npm start, the result should look something like this:

Try and double click some posts to see them disappear, check if the "liking" logic functions correctly.

Everything’s working, but our page is inappropriately huge! Let’s fix this by implementing the Pagination component.

Building Pagination component

Create a new file called Pagination.js that will export the Pagination component, and the pagination.css file containing all the styles needed by the Pagination.

In Pagination.js add the following code:

import React, { useState, useEffect, Fragment } from "react";

import "./pagination.css";

const Pagination = ({
  items,
  itemsOnPage,
  entryProp,
  children
}) => {
  // This will be our state for handling paginated items
  const [pages, setPages] = useState([]);
  // This will hold the currently visible part of the paginated items
  const [currentPage, setCurrentPage] = useState(0);

  // A simple handler for setting the currently visible page
  const handlePageChange = (pageNo) => {
    setCurrentPage(pageNo);
  };

  // Here we re-assembly the pages state on the first render and 
  // every the length of items array or itemsOnPage number change
  useEffect(() => {
    let itemsPerPage = itemsOnPage ? itemsOnPage : 5;
    let workingPages = [];
    let workingPagesCurrentIndex = 0;

    if (items) {
      items.forEach((item) => {
        if (
          workingPages[workingPagesCurrentIndex] &&
          workingPages[workingPagesCurrentIndex].length === itemsPerPage
        )
          workingPagesCurrentIndex++;

        if (workingPages[workingPagesCurrentIndex] === undefined)
          workingPages[workingPagesCurrentIndex] = [];

        workingPages[workingPagesCurrentIndex].push(item);
      });
    }

    setPages([...workingPages]);
  }, [items, itemsOnPage, setPages]);

  // If we were on a page that no longer exists,
  // "redirect" to the previous page
  useEffect(() => {
    if (!pages[currentPage]) {
      setCurrentPage(currentPage - 1 > -1 ? currentPage - 1 : 0);
    }
  }, [currentPage, pages]);

  return (
    <div className="pagintaion__paginationContainer">
    </div>
  );
}

export default Pagination;

Before we jump into the return part, let's recap the code above: basically, it is the same logic we've discussed in the "Problem and Objective" part. We have some state that will hold paginated data, it's pretty dynamic since it is re-assembled in useEffect(), the handlePageChange() handler's logic is pretty straightforward, as well.

What makes it different, is the entryPropin the Component's arguments' list. This one will allow us to make the component universal and suitable for many use cases. Let's have a look at how it works!

In the Pagination's return statement add the following code:

<div className="pagintaion__paginationContainer">
  {/* 
    Here we define basic controls for our pagination: first amd previous buttons,
    the numbered buttons with active classname, and next and last buttons.
    You can use any icons 
    */}
  <div className="paginationContainer__topNavControls paginationControls">
      <button
        className="paginationControls__arrowBtn"
        onClick={() => handlePageChange(0)}
        disabled={currentPage === 0 ? true : false}
      >
      First
      </button>
      <button
        className="paginationControls__arrowBtn"
        onClick={() => handlePageChange(currentPage - 1)}
        disabled={currentPage === 0 ? true : false}
      >
      Prev
      </button>
      {/* 
        Here we iterate over the pages to render the numbered buttons
        The logic is pretty straightforward, here we use string literals
        and inidices to enumerate the buttons and also to hide some buttons
        if there are too many of them
      */}
      {pages &&
        pages.map((page, index) => (
          <button
            className={`paginationContols__pageNoBtn
                    ${
                      index === currentPage
                        ? "paginationContols__pageNoBtn--active"
                        : ""
                    }
                    ${
                      pages.length > 10 &&
                      index !== 0 &&
                      index !== pages.length - 1 &&
                      (currentPage > index
                        ? currentPage - index > 3
                        : index - currentPage > 3)
                        ? "paginationContols__pageNoBtn--hidden"
                        : ""
                    }
                    ${
                      pages.length > 10 &&
                      index !== 0 &&
                      index !== pages.length - 1 &&
                      currentPage > index &&
                      currentPage - index === 3
                        ? "paginationContols__pageNoBtn--dotsBefore"
                        : ""
                    }
                    ${
                      pages.length > 10 &&
                      index !== 0 &&
                      index !== pages.length - 1 &&
                      index > currentPage &&
                      index - currentPage === 3
                        ? "paginationContols__pageNoBtn--dotsAfter"
                        : ""
                    }
                    `}
            key={index}
            onClick={() => handlePageChange(index)}
            disabled={index === currentPage}
          >
            {index + 1}
          </button>
        ))}
      <button
        className="paginationControls__arrowBtn"
        onClick={() => handlePageChange(currentPage + 1)}
        disabled={currentPage === pages.length - 1 ? true : false}
      >
        Next
      </button>
      <button
        className="paginationControls__arrowBtn"
        onClick={() => handlePageChange(pages.length - 1)}
        disabled={currentPage === pages.length - 1 ? true : false}
      >
        Last
      </button>
    </div>
  {/* 
    Here comes the main catch for making our component universal:
    instead of directly passing the children Component to render, 
    we *clone* it with handler props passed from the Parent, while
    the actual "meat" of the component is passed here
  */}
  <div className={`paginationContainer__currentPageDiv`}>
    {pages.length &&
      pages[currentPage] &&
      pages[currentPage].map((item, index) => {
        let objectToClone = {};
        objectToClone[entryProp] = item;
        return (
          <Fragment key={item.id ? item.id : index}>
            {React.cloneElement(children, objectToClone)}
          </Fragment>
        );
      })}
  </div>
</div>

In the code above, we iterate through the pages and render control buttons, as well as the paginationContainer__currentPageDiv div. Here our component becomes universal: we use a special React method React.cloneElement() that allows us to merge the passed-in Children Component (e.g. our Post component) with the current Object in iteration, in which we assign one of the properties to the value of item in iteration. We can name this Object's property with the required prop name using the bracket notation property accessor to which we pass the entryProp string.

objectToClone[entryProp] = item;

This little technique allows the Pagination Component to be used with virtually any Component, if it has an "entry point", hence the entryProp name.

Let's add some styling to the pagination.css

.paginationControls {
  display: flex;
  flex-direction: row;

  flex-wrap: wrap;

  margin-left: auto;
  margin-right: auto;
  justify-content: center;
}

.paginationContols__pageNoBtn {
  display: block;

  background: transparent;
  border: transparent;

  min-width: 2em;

  cursor: pointer;
}
.paginationContols__pageNoBtn--active {
  border: 1px blue solid;
}
.paginationContols__pageNoBtn--hidden {
  display: none;
}
.paginationContols__pageNoBtn--dotsAfter::after {
  content: " ... ";
  color: black;
}
.paginationContols__pageNoBtn--dotsBefore::before {
  content: " ... ";
  color: black;
}

.paginationControls__arrowBtn {
  display: block;

  background: transparent;
  border: transparent;

  cursor: pointer;
}

and implement our Pagination in the App Component. Rewrite the App.js in the following way:

...
import Pagination from "./Pagination";
...
export default function App() {
...
  return (
    <div className="App">
      <h1>React Simple Pagination</h1>
      <h2>This pagination is dynamic</h2>
      <h3>Total Likes: {totalLikes ? totalLikes : 0}</h3>
      {
      isLoading && posts.length === 0 
      ? (
        <div>Loading...</div>
      ) 
      : (
        <Pagination
          itemsOnPage={5}
          items={posts}
          entryProp="post"
          children={
            <Post
              handleDelete={handleDelete}
              handleLikePost={handleLikePost}
              totalLikes={totalLikes}
            />
          }
        />
      )
      }
    </div>
  );
}

Instead of iterating over the posts Array, we pass it to our brand-new Pagination Component. The entryProp is "post", and we pass Post as the children prop with all other props directly passed here, except for the entry one.

Let's test our pagination! The result should be something like this:

Hey-ya! It works, but looks slightly dull. Give us some action!

Adding Page Transitions

Jokes aside, animations can be a really important part of the UX. Not only it helps developers to flex their front-end skills, but it is also an important tool for telling the end-user what is going on. Without any transitions, our Pagination might provoke some headaches instead of providing convenience.

There is a ton of ways to make animations with React, and many of them rely heavily on external libraries. But for something as simple as making some page transitions, it is definitely not a must. Let's add some transitions with the help of CSS3 Animations, React refs and Animation events.

Add the following code to the pagination.css file, those are some really basic transition animations:

@keyframes nextPage {
  0% {
    opacity: 0;
    transform: translate(10em, 0);
  }

  100% {
    opacity: 1;
    transform: translate(0, 0);
  }
}

@keyframes prevPage {
  0% {
    opacity: 0;
    transform: translate(-10em, 0);
  }

  100% {
    opacity: 1;
    transform: translate(0, 0);
  }
}

Now, let's return to the Pagination.js. Import useRef Hook

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

Refs are sometimes called an "escape hatch" in React applications. The "React way" of building software is declarative: the library abstracts a huge portion of written code when developing complex applications, and gives us an opportunity to reason about different parts of it in a component-scoped way, without the need to write lines and lines of document.createElement(...)'s. In order to make the application work predictably, direct DOM tree manipulation should be avoided. However, sometimes we still need to access an HTML element directly, imperatively. Here come the ref that help us to avoid an absolute mess with random attempts to document.getElementById().

In the Pagination component, add the following code and rewrite the handlePageChange handler as follows:

const Pagination = ({...}) =>
...
  let currentPageRef = useRef(null);

  const handlePageChange = (pageNo) => {
    if (currentPage > pageNo) {
      currentPageRef.current.style.animation = "prevPage .5s forwards";
    } else {
      currentPageRef.current.style.animation = "nextPage .5s forwards";
    }
    setCurrentPage(pageNo);
  };
...
      <div
        className={`paginationContainer__currentPageDiv`}
        ref={currentPageRef}
...

We created a new ref called currentPageRef, and made it a ref of the paginationContainer__currentPageDiv div, the actual element will now be available at currentPageRef.current property. We added some logic to the handler, so we can add our animation from the stylesheet in different cases.

However, if we try this code out right now, it will disappoint us: the animation runs only once when flipping through several next or previous pages. We need a way to "unplug" the animation and then add it once again.

There are several ways to re-run CSS3 animations with React, some of them might be a little hacky and not so reliable (like, for instance, using myRef.current.dashOffset statement to signal React that something has changed), so it might be better to use one of the React's animation events: onAnimationEnd() that will fire as soon as the element's animation finishes.

Add the following handler to the paginationContainer__currentPageDiv:

...
      <div
        className={`paginationContainer__currentPageDiv`}
        ref={currentPageRef}
        onAnimationEnd={() => {
          if (currentPageRef.current) {
            currentPageRef.current.style.animation = "";
          }
        }}
...

And test our application once again. The result should be:

Now we're talking! Please also note that I've added some Bootstrap SVG icons for the pagination control buttons. You can add these icons to your project, just copy and paste them from the sandbox, or you can make some of your own!

Swipe It!

In the mobile-first age, our Pagination definitely better have some touch support! Let's make it swipeable with Touch events.

In the Pagination component's body add the following code:

  // Touch event handling
  // This will signal that the page is being swiped
  const [isDragging, setIsDragging] = useState(false);
  // This will be the point of the initial touch
  const [initialTouch, setInitialTouch] = useState(0);
  // These positions are needed to determine whether to move the page or not,
  // as well as to decide of the page should be flipped
  const [posLeft, setPosLeft] = useState(0);
  const [prevLeft, setPrevLeft] = useState(0);

  // This object will hold the current page container's style
  const divStyle = {
    position: isDragging ? "relative" : "static",
    left: isDragging ? posLeft : 0
  };

  // onTouchStart we signal our container to become position: relative, so that
  // the left property affects its position
  // We also set the initialTouch state and the prevLeft state
  const _onTouchStart = (event) => {
    setIsDragging(true);
    setInitialTouch(event.nativeEvent.touches[0].clientX);

    const { left } = extractPositionDelta(event.nativeEvent.touches[0]);

    if (posLeft + left <= 0) {
      setPosLeft(posLeft + left);
    }
  };

  // Here we decide if the page should be moved, 30 might be a good balance 
  // between too stiff and too sensitive
  const _onTouchMove = (event) => {
    if (!isDragging) {
      return;
    }
    const { left } = extractPositionDelta(event.nativeEvent.touches[0]);

    if (Math.abs(posLeft) + Math.abs(left) > 30) {
      setPosLeft(posLeft + left);
    }
  };

  // When the use removes finger from the screen, we need to determine if 
  // his or her intention was to flip the page; once again, 30 works well
  // In the end we set our state to the initial values
  const _onTouchEnd = (event) => {
    setIsDragging(false);

    let delta = Math.abs(prevLeft) - Math.abs(posLeft);

    if (delta < -30 && posLeft < initialTouch) {
      if (pages[currentPage + 1]) handlePageChange(currentPage + 1);
    } else if (delta > 30 && posLeft > initialTouch) {
      if (pages[currentPage - 1]) handlePageChange(currentPage - 1);
    }

    setPosLeft(0);
    setPrevLeft(0);
    setInitialTouch(0);
  };

  const extractPositionDelta = (event) => {
    const left = event.clientX;

    const delta = {
      left: left - prevLeft
    };

    setPrevLeft(left);

    return delta;
  };

Here are our handlers for Touch events. Let's add them to the container div:

      <div
        ref={currentPageRef}
        className={`paginationContainer__currentPageDiv`}
        onAnimationEnd={() => {
          if (currentPageRef.current) {
            currentPageRef.current.style.animation = "";
          }
        }}
        style={divStyle}
        onTouchStart={_onTouchStart}
        onTouchMove={_onTouchMove}
        onTouchEnd={_onTouchEnd}
        onTouchCancel={_onTouchEnd}
      >

Now our Pagination can be swiped! Try it out on a mobile screen or in the developer tools simulation.

Our Pagination is all fancy, but our Post is kinda lame. Moreover, deleting a post behaves weirdly on a touch screen now! As a little bonus, let's cheer it up, and add some animations to a Post leaving the state!

Crate a file post.css and add the following code:

.post {
  transition: 0.3s ease-in-out;
}
.post__likeBtn {
  display: block;
  margin-left: auto;
  margin-right: auto;
  margin-top: 0.5em;

  height: 3em;
  width: 3em;

  cursor: pointer;
}

.post--deleting--left {
  animation: postDeletedLeft 0.5s forwards;
}

@keyframes postDeletedLeft {
  0% {
    opacity: 1;
    transform: translate(0, 0);
  }
  100% {
    opacity: 0;
    transform: translate(-10em, 0);
    display: none;
  }
}

Here we defined some basic animation for our post being deleted. Now, rewrite Post.js in the following way:

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

// import CSS
import "./post.css";

const Post = ({ post, handleDelete, handleLikePost, totalLikes }) => {
  // Now, onClick we will signal the post that it is being deleted,
  // instead of invoking handleDelete() directly
  const [isDeleting, setIsDeleting] = useState(false);

  // We will need a ref to a timeout so that our component works correctly
  let timeoutRef = useRef(null);

  // This will be the handler on the double-click
  const deletePost = () => {
    setIsDeleting(true);
  };

  // This will be the handler on touch screens
  // We use e.stopPropagation(); to avoid messing app the pagination's
  // Touch event logic
  // Delete on double tap
  const [firstTap, setFirstTap] = useState("");
  let touchRef = useRef(null);

  const _onTouchEnd = (e) => {
    if (!firstTap) {
      setFirstTap(new Date().getTime());
      timeoutRef.current = setTimeout(() => {
        setFirstTap("");
      }, 200);
      return;
    } else if (firstTap && timeoutRef.current) {
      e.stopPropagation();
      setFirstTap("");
      setIsDeleting(true);
    }
  };

  // Here we use the timeoutRef to delete the post after the animation runs
  useEffect(() => {
    if (isDeleting) {
      timeoutRef.current = setTimeout(() => handleDelete(post.id), 500);
    }
  }, [isDeleting]);

  // Unmount cleanup to avoid memory leaks
  useEffect(() => () => clearTimeout(timeoutRef.current), []);

  useEffect(() => clearTimeout(touchRef.current), []);

  return (
    <div
      // xchange the className to run the animation
      className={`post ${isDeleting ? `post--deleting--left` : ""}`}
      // this one for mouse double-click
      onDoubleClick={() => {
        deletePost();
      }}
      // this one for touch screen double-tap
      onTouchEnd={(e) => _onTouchEnd(e)}
    >
      <h3>{post.title}</h3>
      <p>{post.body}</p>
      <div>
        Likes: {post.likes ? post.likes : 0}{" "}
        {post.likes && totalLikes ? `out of ${totalLikes}` : ""}
      </div>
      <button
        className="post__likeBtn"
        onClick={(e) => {
          handleLikePost(post.id);
        }}
        // run e.stopPropagation(); to avoid firing delete event
        onDoubleClick={(e) => {
          e.stopPropagation();
        }}
        onTouchEnd={(e) => {
          e.stopPropagation();
        }}
      >
        <span role="img" aria-label="like button">
          💖
        </span>
      </button>
    </div>
  );
};

export default Post;

Now check out the browser, it should be something like this:

Excellent! Our pagination is working! You can also check out some additional parameters in the sandbox, like topNav and bottomNav that determine top and bottom controls respectively.

Conclusion

Great! It certainly was not a short tutorial, but I hope it was productive: we've touched upon several React techniques which are not that widely covered, but can be quite useful in the real-world applications. We've seen Touch events in React in action, learned one of the usages of the onAnimationEnd(), and saw how refs can help us to escape the declarative React code to achieve some cool effects. And, the last but not least, we've built a dynamic pagination component that you can use in your projects.

If you need inspiration, you can check out some pagination examples I've made for the NPM module, all of them have their source code in the example directory in the GitHub repo.

Hope you've enjoyed this tutorial, would really appreciate hearing from you!

Have a good one!

No-headache Asynchronous JavaScript for Beginners

Dmitry — Thu, 05 Nov 2020 11:36:16 +0000

This post was originally published on my website and is also available in RU and ZH. Check it out!

JavaScript is an amazing language that can be used anywhere - it runs natively in the browser, can power up mighty server, mobile, and desktop applications. Regular updates approved by the ECMA make its syntax and built-in functionality even more pleasant to work with. Being an extremely beginner-friendly programming language (with the power of just hitting Ctrl + Shift + J in a browser window to start a sick coding sesh), JavaScript, however, brings some twists to the table that may be mind-boggling and repelling. Some of these "tricky" hard-to-grasp parts can be just memorized and copypasted, but at some point (e.g. when learning a new library or implementing a certain feature) they can backfire and backfire hard. Asynchrony is certainly one of those concepts.

If you’ve tried hard for some time to tame the asynchronous beast, run across dozens of "setTimeout" examples but feel like you haven't moved an inch forward: worry not, you will certainly nail it. I hope, this post might be one of those "clicks" that make previously impossible crystal clear.

Some useful links just in case:

This post is aimed primarily at the beginners, who have struggled with asynchronous JS for a while, but maybe some of the more advanced readers might find it useful.

Prerequisites: understanding the basic syntax of JavaScript, Node.js installed. In this tutorial, we are going to use some modern JavaScript syntax, but if you’ve been learning JavaScript so far with a little bit dated material (which can still be perfectly relevant), don't worry - there won't be much. Just in case - a quick introduction to some modern JS features by Flavio Copes and let and const keywords tutorial by Victoria Crawford.

A step back

Before we begin, there’s a certain point I’d like to clarify: even though there are a lot of amazing JavaScript tutorials and articles, some of them can be harsh on a beginner. Since JavaScript is the first choice for many people starting their journey into web- and software development, many tutorials are eager to jump into the action and teach how to manipulate the web-page. Not being bad on its own, this can evoke some problems in the long run: copying and pasting code snippets can take us far, but only so far.

When it comes to the majority of tutorials covering asynchronous JavaScript, there are usually two points at which they’re lacking, making the whole topic overly-vague: fully clarifying the whole purpose for asynchronous code in the first place (apart from really dry definitions), and providing easy-to-read examples that can be understood by a beginner (and this is vital since reading code that jumps up and down can be quite an experience).

Asynchrony is by no means easy, it can be frustrating, especially for someone relatively new to web development. You feel like everything else is perfectly tackled down: you've got your HTML and CSS knowledge in check, JS variables and data types are no big deal, adding and removing elements from the DOM seems easy, but all of the sudden, you get stuck. It may be a good idea to take a little step back in order to make a big step forward.

First, we’re going to talk about data in applications to understand the need for, and purpose of the asynchronous code, and then we’re going to jump into some code to see how it can be implemented in JavaScript using callbacks.

Data in a program

Computer programs do not exist in a vacuum. Well, most of the more useful computer programs don’t. Without getting too formal, we can assume that any application or program is, basically, an abstraction over receiving some data as an input and bringing it to the output.

Data can come in all forms and shapes, and from the data-source point of view, we can roughly divide all the data our application needs into two categories: “internal” data that is “hardcoded” and immediately available the moment out program starts, and “external” data that has to be loaded in the application’s memory during the execution process.

The fundamental difference between these two “types” of data is speed. The already-in-memory data is extremely fast, however, getting the external data is much, much slower. But at the same time, external data is much more interesting for us.

A hardcoded array of names will be loaded blazing fast, but it won’t preserve any changes: as soon as our program terminates, all of our changes will be lost. However, an array of names received from a local database, a file system, or some external data source via the Internet is much more exciting and useful to work with. But in comparison, this process is much slower.

"Slow" always sounds bad when it comes to software development. No one wants to use a slow mobile app or to browse a slow website. Generally, there are two approaches that are used in programming (sometimes combined) to solve this “slow data problem” - multithreading and asynchrony.

Multithreading has been one of the most widespread approaches to dealing with “slow” data and operations, used in languages like Java. In multithreading, we launch a separate process (a “thread”) to execute a “slow” operation in the “background” without making our application freeze. For example, in an Android application, our “main thread” would usually track down touches to the screen, and if some operation after touching a button is “slow” (i.e. it involves accessing some external data source or a heavy computation) this operation will be executed on a separate thread. Updating a feed in a social network app, or calculating the velocity of an enemy after an impact in a mobile game - all these operations would usually run on a separate thread in an Android application.

Launching separate threads is not a stranger to JavaScript applications either: service workers for example, can help us take our web-applications to another level. However, this technique is fairly advanced and can be an overkill for most of the “slow” operations a web-application would usually face. In the JavaScript world, using asynchronous programming is much more common.

Asynchrony is aimed at roughly the same task: execute some time-consuming operation without blocking the user interface. When we upload an image on a website or hit a submit button to post a comment, an asynchronous operation happens, and if done correctly, our webpage stays active and responsive during the operation - we can scroll up and down, in some cases visit other pages of the application and interact with other buttons. However, even though multithreading and asynchrony might be used for the same kind of operations, they are fundamentally different at the implementation level.

In asynchronous programming, we have a single thread that runs constantly during the whole execution time of the program, “waiting” for the events, user input for example. To put it roughly, this process constitutes a “loop” of “events”, an event-loop. On each cycle or iteration of the loop, it “catches” and starts executing commands, i.e. our code directives. What makes it special, is that if a certain line of code takes a long time to execute and return some value, the operation depending on it can be “postponed” to the next iteration of the loop.

For instance, we want to load a list of users from the server via HTTP request and display them on our screen. At large, this operation consists of two steps, one being reasonably slow and one being blazing fast:
1) Make a request to the server, get some value in the response (usually in JSON, a special data format), convert the received value into something our application can work with (usually, an array of JavaScript Objects);
2) Iterate through the array of Objects, create an HTML element on each iteration and append it to the webpage.

Between these two operations, there would be at least one iteration of the event-loop. On the first one, the “get-data-from-the-server” function would be invoked, on the second one - “display-data-to-the-screen” function would be called with the received data.

The same principle can be applied to the Node.js JavaScript applications that live outside the browser. Node.js is a runtime that makes it possible to run JavaScript programs on a machine outside the browser, and one of the major tools for the development of powerful JS applications. A Node.js application typically has access to the part of the local file system it is put into (usually, the application folder), and it can read and write different types of files, thus it’s capable of sending different types of files to the client, and getting them from the client, as well: when we upload an image to such a server, it has to write it to the file system via asynchronous operation.

When we open a JavaScript web-application in the browser, an event-loop starts. When we launch our Node.js server-side application, an event-loop starts. And as a rule of thumb, any calculation-heavy or utilizing external data source operation should be made asynchronous. On-page HTTP requests should be asynchronous. Connecting to the database should be made asynchronous. Writing to and reading from the file system should be made asynchronous.
The implementation of asynchronous operations in JavaScript, that’s where we need to refresh our understanding of the language syntax and structure, especially seemingly easy concepts like function declaration and invocation.

Function declaration and invocation

“In JavaScript, functions are the first-class citizens”. Wait, wait, wait. If you were ready to hit the display with something heavy or, even worse, end all this asynchrono-whatever mumbo-jumbo right now, wait a little bit, I do feel you on this one. This phrase has been totally abused by dozens of tutorials you’ve probably read so far, and yes, it hardly clarifies anything by itself.

What it means in practice, is that in JavaScript we can pass functions as arguments to other functions. And this can be really hard to spot at first, even if you’ve gazed at some code snippets for hours.

The actual problem for understanding is, the majority of functions that deal with time-consuming operations (e.g. window.fetch() or fs.readFile()) are already built into the browser API and Node.js standard library, so it is really hard to understand how they work. We will write an asynchronous function of our own and pass another function as an argument to it. We will manually postpone the invocation of the latter function to the next iteration (or tick) of the event loop using .nextTick() method of the process object (that literally stands for the process our program is running on).

With Node.js installed on your system, open your text editor or IDE of choice (I prefer VSCode), create a new file called “pseudoAsyncFunction.js”, and let’s start some coding!

// Declare a function
function slowFunction(a, b, fastFunction) {
    console.log("Time-consuming operation started");
    let c = a + b;

    process.nextTick(function() {
        console.log("...calling fastFunction in the next iteration of the event loop");
        fastFunction(c);
    });
}

We declared a function called slowFunction that takes three parameters: a, b and a mysterious fastFunction, that is going to be called inside the slowFunction.
We start a "time-consuming" operation (a totally fake one, here we simply get the sum of a and b) and store its result in a variable c that, in its own turn, is being passed to the fastFunction as an argument.

In the next line, we call process.nextTick() method, in which we pass and define an anonymous function, in whose body we finally call our fastFunction with c passed as a parameter.

Already at this point things might start to get a little messy (what’s up with this .nextTick?!), but worry not. Unfortunately, asynchronous programming is hard to illustrate with an example without asynchronous programming. A vicious cycle.

Let’s try and call our brand new slowFunction and see what it’s capable of! Under the previous lines of code add the following:

console.log("Program started");

// Call our slowFunction with parameters: 1, 2, 
// and define actual "fast function" to be called with the result c 
// as its parameter
slowFunction(1, 2, function actualFastFunction(c) {
    console.log("The result of the time-consuming operation is:");
    console.log(c);
    console.log("Program terminated");
});

console.log("This function is being called after the slowFunction");

Open the terminal (Ctrl + Shift + ~ in VSCode) and from the folder containing our working file run the following command:

node pseudoAsyncFunction.js

The output of our program would be:

Program started
...Time-consuming operation started
This function is being called after the slowFunction
...calling fastFunction in the next iteration of the event loop
The result of the time-consuming operation is:
3
Program terminated

The important piece is, our actualFastFunction was called after the line of code:

console.log("This function is being called after the slowFunction");

Synchronous code is being executed from top to down, and we would expect the line of code above to run last, but asynchronous code behaves differently. The line:

This function is being called after the slowFunction

Is being printed to the console output on the FIRST iteration, or tick, of the event-loop, while the lines:

...calling fastFunction in the next iteration of the event loop
The result of the time consuming operation is:
3
Program terminated

are being printed on the second iteration, since they were postponed with process.nextTick().

Take a look at our code once again. Let’s analyze what we did here:

We declared the slowFunction that takes 3 arguments, one of which we called fastFunction
We directed fastFunction to be called in the very end of the slowFunction, postponed its execution by placing it inside process.nextTick() and passed variable c that contains the value of the “time-consuming operation” as its parameter;
We called our slowFunction with 1 and 2 as the first two arguments, and defined a new function called actualFastFunction inside the parenthesis. And this function is the one that would be called after the “time-consuming” operation has finished.

What’s important to note here, is that in the invocation of our slowFunction, we did not call actualFastFunction, we defined it knowing the shape this function should take. We know it takes a single parameter, so we designed it to take one. This could be any other function that would take one argument (c) and do something with it as soon as the operation to get the c completes.

We could call our slowFunction like this, naming its parameter differently:

slowFunction(1, 2, function anotherActualFastFunction(resultOfSlowFunction) {
    console.log("The result of the time consuming operation is: " + resultOfSlowFunction);
    console.log("Program terminated");
});

or use an anonymous function:

slowFunction(1, 2, function (c) {
    console.log("An anonymous function reporting!");
    console.log("The result of the time-consuming operation is: " + c);
    console.log("Program terminated");
});

or use a fancy arrow-function and some newer JS syntax:

slowFunction(1, 2, (c) => {
    console.log(`Here’s the value of c - ${c}. Sincerely yours, fancy arrow function`);
    console.log("Program terminated");
});

or we can pre-define our fastFunction and then pass it to the slowFunction:

function separatelyDefinedFastFunction(c) {
    console.log("Hey, I am defined separately!");
    console.log("The result of the time consuming operation is: " + c);
    console.log("Program terminated");
}

slowFunction(1, 2, separatelyDefinedFastFunction);

Please note that we don’t put parentheses after our separatelyDefinedFastFunction in the braces when invoking the slowFunction - we are not calling it yet, it is going to be called inside the slowFunction. Otherwise, this would give us an unexpected result: in the strict mode, separatelyDefinedFastFunction would be called with non-existing yet variable c as its parameter and throw an error, in the non-strict mode, it would be called with c being undefined, and it would return no value, making the slowFunction throw an error: it expected to have a function to call, but now it received nothing.

Now, try to tweak our code a little bit on your own! Maybe fastFunction can do some calculations with the received value? Or, at some point, will it take some function as a parameter itself? Try to make some changes, get a couple of successes and errors (which is certainly not the thing to be afraid of), and move on to the next section, we’re going to talk about callbacks.

Call me maybe!

The technique we’ve just seen above is the so-called callbacks that you've probably already encountered before. Callback functions literally stand for their name: they are "called back" by the outer function ("the slow function") when the time-consuming operation has finished.

In this case, our fastFunction and its variations are all callback functions - functions that are passed as parameters to other functions and called somewhere inside them. This is what the gear-grinding phrase about “first-class citizens” basically means.

Callback functions are one of the first techniques used in JavaScript for asynchronous operations; however, they are not used for just this. Many built-in methods in JavaScript, for instance, JS Array higher-order functions, rely heavily on callbacks: when we invoke myArray.map() or myArray.forEach() these methods require a function as a parameter - a callback function to be called on each iteration of the higher-order function. If you’re not familiar with higher-order functions yet or you’ve been using them without much understanding of how they actually work, I strongly recommend taking a look at them after finishing this tutorial (for instance, check out this video by amazing Brad Traversy).

What’s important to understand, is that callbacks are not part of some external library or a special jitsu: they are just one of the natural ways of writing code in JavaScript, along with closures and other techniques wrongly accused of being “mysterious”.

Actually, you've probably already seen some articles claiming that using callbacks for asynchronous operations is obsolete, and now we all should use Promises and async/await for asynchronous operations. That’s partly true - in relatively complicated operations, these two are much more readable and pleasant to work with, but here’s the catch:

Both of them are based on callbacks (even though syntax looks completely different).

Promises can be called “callbacks on steroids” and async/await is a sort of “syntactic sugar” above Promises. Without understanding callbacks, their benefits and drawbacks, it’s easy to find oneself in a situation when you get a nice power drill and use it as a manual screwdriver, never pushing the button. Definitely not so productive.

Callbacks are an integral part of organizing code in JavaScript. From a certain point of view, many JavaScript applications are a huge flow of functions inside other functions. This is a rough interpretation, but some frameworks like Express (a de-facto standard tool for building server-side applications in Node.js) are literally based on functions sitting inside other functions. Understanding this so-called “middleware” (which are literally functions-in-the-middle) architecture depends on getting the best of callbacks.

In the section above, we mentioned having a possible error in our function: what if some part of the input is wrong? An unhandled error would break our program. In order to avoid passing wrong values to the functions, some useful conventions for writing asynchronous functions and functions with callbacks have evolved, first starting with the Node.js applications and later on applied to JavaScript programming in general. They are:

A callback usually comes last, after all other parameters in a function;
The first argument of a callback is err, standing for a possible error, and the second argument is the expected value;

Let’s rewrite our slowFunction to fit these conventions, add some error checks, and rename our fastFunction to callback:

function slowFunction(a, b, callback) {
    // declaring our variables
    let error = null;
    let c = null;

    console.log('...time consuming operation started');

    // check if there's a callback
    if (!callback || !(callback instanceof Function)) {
        throw new Error('A problem with callback!');
    }

    // check a and b for an error
    if (!a || !b || !Number.isInteger(a) || !Number.isInteger(b)) {
        error = new Error('Wrong input!');
    } else {
        c = a + b;
    }

    process.nextTick(function() {
        console.log('...calling fastFunction in the next iteration of the event loop');
        callback(error, c);
    });
}

Here we’ve tweaked our function a little bit: now we have two variables we are going to invoke our callback function with: error and c, both of them initially null. We’ve added two simple checks for an error using logical || (or) operator. First, we check, if the callback exists and whether it is a function. If it is not, we throw an error, terminating the function execution. Then, we check a and b for an error: if there’s no a, or there’s no b, or a is not an Integer, or b is not an Integer, we create a new JS Error Object, pass a String 'Wrong input' as its .message attribute, and assign it to the variable error, while our variable c stays null. Otherwise, if the input is correct, the error variable remains null, while c is assigned to the value of a + b. We call our callback function and pass error and c as its parameters at the next iteration of the event-loop.

Now, if we can call our slowFunction like this:

slowFunction(1, 2, function actualCallback(err, c) {
    if (err) {
        console.log(err.message);
    } else {
        console.log(`The result is: ${c}`);
    }
});

Here we pass parameters 1 and 2, and define the callback function to call: our actualCallback function (which, as we remember, could have been defined anywhere and passed here as a parameter without parenthesis). Our actualCallback function tekes two arguments: a possible error and the return value of the “time-consuming” operation. In the function body, we first check for an error, and if the error is not null (i.e. the error is present) we output the value of its .message property to the console. Otherwise, if the error is null, it means that c holds something meaningful and we output it to the console (once again, note the fancy string interpolation: this is a very nice technique to have in your arsenal).

Let’s try and call our slowFunction with some erroneous parameters:

slowFunction(1, "Some silly string", function actualCallback(err, c) {
    if (err) {
        console.log(err.message);
    } else {
        console.log(`The result is: ${c}`);
    }
});

This time our output will be:

Wrong input!

Since the err parameter is now an Error object with the .message of "Wrong input" and the c is null.

This convention is really handy and used in many built-in and external JavaScript libraries. However, it has a considerable drawback: as our operations grow and become more complex, with callbacks passed inside callbacks (which is much more common than it may seem - asynchronous operations rarely come alone) so does the number of error checks, leading to the so-called callback hell problem. The above-mentioned Promises and async/await are one of the tools that are here to make our code more readable and maintainable, but for now, we need to see the full potential of callbacks in action.

Most of the time, we don’t need to write our own asynchronous functions and manually postpone the invocation of our callbacks with process.nextTick(). The majority of the functions we would need are pre-defined for us: fs.writeFile(), fs.readFile(), window.fetch(), and many others. Documentation (and handy IDE snippets) will help us understand what arguments, including the passed-in functions, are expected from us.

Now we’re going to take a look at some server-side and client-side “real-world” examples: one involving the filesystem (fs) module of Node.js and another using the methods of the XMLHttpRequest Object available in the browser.

Server-side example

For a relatively long time, JavaScript has been the language of the browsers, however, the idea of writing the same language both client- and server-side has been in the air for a while, when in 2009 Node.js, a runtime for JavaScript, was launched. Since then, JavaScript has gone through tremendous changes, becoming an extremely versatile and powerful language with lots of wonderful libraries and frameworks for the development of client, server, desktop, and mobile applications. It is safe to say that Node.js and NPM played a huge part.

Even though in 2020 we have new competitors to Node.js (for instance, Deno - a system developed by one of the Node.js original creators), it remains one of the major tools for JavaScript applications development with immense capabilities.

One of the most common use cases for Node.js are server-side applications. Roughly speaking, a server-side application should be able to:
1) receive and handle an HTTP request;
2) get some data from the local machine according to the request;
3) send the data in HTTP response.

The source of data on the local machine might be a database or simply the part of the file system available for the application. Once again, working with these data sources should be made asynchronous.

Let’s start with a simple example: display some data from the file system to the console output. Afterwards, we will create a simple HTTP-server and serve the contents of our file to the client. In the process, we will meet a lot of callbacks!

Create a new folder called “server-side-example”, move to it using the following command in your terminal:

cd server-side-example

and inside this directory create two files: readFile.js and text.txt.

In the text.txt file add a line of text, for example, Hello there!, and open up the readFile.js.

In readFile.js add the following code:

const fs = require("fs");
const path = require("path");

fs.readFile(path.join(__dirname, "text.txt"),
 { encoding: "utf-8" }, function (err, data) {
  if (err) {
    console.log(err);
  } else {
    console.log(data);
  }
});

In the code above we do the following:

First, we import two modules from the Node.js standard library: the fs ("file system") module that contains methods for working with various files, and the path module that is needed to precisely resolve directories to the files we need.

Then, we use .readFile() method of the fs object. This method asynchronously reads data from the file and takes three arguments: the path to the file to read (in this case, we use path.join() method to concatenate the current directory (__dirname) with the name of the file (text.txt)), configuration object (in this case, just encoding), and a callback function.

According to the convention we've met above, the callback function takes two arguments: a possible error (err) and the data (data) from the file we want to read. In this case, we simply check for an error first, and output it the console if there was a problem (e.g. file does not exist). Otherwise, if there was no error, it means that we have some data, so we output it with console.log(data).

Let's launch our program with

node readFile.js

The output should be:

Hello there!

So far so good! Try and change the contents of text.txt and restart the program. How about a wrong path for the fs.readFile() to generate an error? Give some tweaks a shot.

Outputting to the console is great, but what about showing the contents of our fancy file via the Internet? Let’s make a super simple local HTTP server, and make it send some information from the file system to the client (i.e. the browser).

In the same folder, create a file server.js, and open it in the editor. Add the following code:

const fs = require("fs");
const path = require("path");
const http = require("http");

const server = http.createServer(function (request, response) {
  fs.readFile(
    path.join(__dirname, "text.txt"),
    { encoding: "utf-8" },
    function (err, data) {
      if (err) {
        response.write(`<h1>An error occurred!</h1>`);
        response.end();
      } else {
        response.write(
          `<h1>The following text is from the file system:</h1><p>${data}</p>`
        );
        response.end();
      }
    }
  );
});

server.listen(8080, function () {
  console.log("Server started on 8080");
});

Here we first import the two already familiar modules, fs and path, and a new module - http that we will use to create our server using its .createServer() method.

Let's talk about the structure of our server as a whole. We declare a variable server and assign it to the value of http.createServer(). This method takes a callback function as an argument, and this callback function is going to handle requests to our server. We will return to it in a second.

Then, we call the .listen() method of our server object to start listening for requests on one of our machine's ports. This method takes a port to listen on as the first argument, and an optional callback function: here we use it just to show that the server started successfully.

Returning back to the callback of our .createServer(). This function takes two arguments: HTTP request and HTTP response objects, named conventionally request and response. An important note here: once again, we are defining a function to be called, not invoking it here. This function will be icalled, when our server receives an HTTP request (e.g. when we visit localhost:8080 in our browser after the server has started). In this function, we might have called request and response parameters any way we wanted: req and res, httpRequest and httpResponse, etc.

The request object contains various information about the request we've received: HTTP method and URL, request headers, possible request body, and many others. If we needed to handle requests to different URLs or different types of requests (GET, POST, PUT, DELETE) we would run conditionals statements against the request object to decide what to do with it. For simplicity, in our case, any HTTP request to our server will result in the same response.

The response object contains different methods and properties that define, how to respond to the client-side request: what data and in what way to send back to the client. In this case, we will use only two methods: .write() and .end().

response.write() takes the data to write to the client in the response as the parameter. Here we can directly write HTML, and it will be interpreted as such by the browser. Using the already familiar string interpolation, we can use backticks  \ and hardcode the 'static' parts of our string, and use curly braces with the $ sign ${} to add some dynamic data to it. Here we use ${} to insert the data from the text.txt in our response.

response.end() terminates the request-response cycle and signals the client-side that our response ends here.

We use these two neat methods in the callback of the fs.readFile(). If the data has been read successfully, we send it to the client in the response, if there was an error while reading the file, we respond with an error message.

Thus, our .createServer() works as following:

The server receives a request, calls its handler callback;
The handler callback calls fs.readFile() that asynchronously reads a file from the file system;
The callback passed to fs.readFile() responds to the client with response.write() and response.end() once the asynchronous operation completes.

Let’s see this in action! In the terminal run:

node server.js

to launch the server and check that you got

Server started on 8080

in the terminal window. Open localhost:8080 in the browser. You’re likely to see something like this:

Nice!
We've just created an HTTP server that sends dynamic data to the client. Try and change the contents of text.txt and refresh the page. How about giving fs.readFile() a wrong path? Don't forget to save the file and restart the server after adding changes.

Of course, in a real-world application, our code would be much more sophisticated. We would be more likely to use some sort of server-side framework within Node.js (e.g. Express.js) to handle requests to different routes, and the whole architecture would be much more complex. However, the very base of the application would be the same. And, just as we saw, it would be heavily based on callbacks.

Now let’s take a look at how we can use callbacks for asynchronous operations on the client-side. Frontend, here we go!

Client-side example

On the client-side, the role of asynchronous programming is huge. It is the base of the AJAX technology, Asynchronous JavaScript And XML (even though the name is a bit obsolete since XML is not as common as it used to be). AJAX is the major tool for creating highly dynamic client-side applications that send and receive data from the server without refreshing the whole page.

Nowadays, there are several ways to implement AJAX, including XMLHttpRequest, window.fetch() and external libraries like axios. With XMLHttpRequest being the oldest one, it is a good idea to get acquainted with it first, before moving to more modern approaches.

An XMLHttpRequest is a JavaScript Object with several built-in methods and properties aimed at fetching some data with an on-page HTTP request to the own server or some 3d party Rest API. In a typical use case, we would usually create a function that takes different configuration options as parameters, initializes a new instance of XMLHttpRequest with these parameters inside this function, and sends the request to the specified URL with the specified HTTP method and data (if needed). What we have to do while the data is loading (e.g. show a nice loading spinner), has loaded (e.g. display it to the screen and hide the spinner), or an error occurred (e.g. hide the spinner and show an error message) is all handled by callbacks we define. XMLHttpRequest has a lot of parameters and interesting features apart from the ones we are going to briefly touch upon, and I would strongly recommend checking out MDN documentation and playing with some data after this tutorial.

In this example, we are going to create a web-page that loads some posts from an API on a button click, shows a loading spinner once the request started, and displays the posts to the page or shows an error message if something goes wrong. For the data source, we will use jsonplaceholder - a great tool for learning AJAX and HTTP requests in general. It contains various sets of data that imitate a typical response from a server in JSON format - blogposts, comments, users, etc. Whether you need to take a good grasp on basic frontend concepts or learn a new library (e.g. React or Vue.js) jsonplaceholder certainly worth bookmarking.

Create a new file in our folder and call it client-side-example.html. For simplicity, we will keep our CSS, HTML, and JavaScript in the same file.

Inside our new file within the body tags add the following code:

</main>
  <h1>Browser example</h1>
  <h2>Posts</h2>
  <button 
    id="fetchPostsBtn"
  >
    Fetch Posts
  </button>
  <div id="spinner" style="display: none;">
    Loading...
  </div>
  <div id="postsDiv">
  </div>
</main>
<script>
</script>

Here we created a <main> container for our application with three elements with the defined id attribute that we will use in our JavaScript code: a <button>, a <div> that will become a spinner (but for now just says "Loading..."), and container <div> for our posts. Within the <script> </script> tags we will place the code to manipulate the web-page content.

Next, between the <script> </script> tags add the following code:

let postsDiv = document.querySelector('#postsDiv');
let fetchPostsBtn = document.querySelector('#fetchPostsBtn');
let spinner = document.querySelector('#spinner');

We use the document.querySelector() to find the elements we need by id and create three variables that point at these elements.

Now, we will declare a function fetchPosts() and pass it as the callback function of the .addEventListener() method of the fetchPostsBtn:

function fetchPosts () {
  console.log('Posts fetched!');
}

fetchPostsBtn.addEventListener('click', fetchPosts);

Right now, it does do much: it simply outputs "Posts fetched!" to the console in our browser's developer tools. Open the file client-side-example.html with a browser, open developer tools (Ctrl + Shift + J in most cases), and click our button a couple of times to check if it's working.

What is worth noticing here, is that the .addEventListener() method of our button takes two parameters: the type of event to add a function to ('click', in this case) and a callback function to invoke when the event takes place. Here we defined our fetchPosts() function separately, so we pass it as the second parameter without parentheses.

Next, we will make our fetchPosts() function actually fetch posts from the data source. Let's fill the body of the function:

function fetchPosts () {
  let xhr = new XMLHttpRequest();

  xhr.onload = function() {
    console.log(xhr.response);
  }

  xhr.onerror = function() {
    console.log('An error occurred!');
  }

  xhr.open('GET', 'https://jsonplaceholder.typicode.com/posts');
  xhr.responseType = 'json';
  xhr.send();
}

Here, we first create a new instance of XMLHttpRequest Object: we call the constructor method of XMLHttpRequest with the new keyword and assign it to the variable xhr. Now, xhr is a separate instance of XMLHttpRequest Object that has the attributes and methods we need to make a request.

First, let's take a look at the xhr.open() and xhr.send().

xhr.open() is the method responsible for the main configurations of the request, it takes the HTTP method as the first parameter ('GET' in this case) and the URL to make a request to ('https://jsonplaceholder.typicode.com/posts').

xhr.responseType property defines, what type of data we expect in the response from the server. We expect JSON, so we assign it to 'json'.

xhr.send() method actually sends the request. After the request is sent, events within the request start happening: loadstart, loadend, error, and others. On each of these events, we can define a function to invoke. Let's start with xhr.onload and xhr.onerror.

xhr.onload property should be a function to invoke when the response has been successful. In this case, the response data is accessible via the xhr.response property, that we display to the console.

xhr.onerror function is invoked when some sort of error happens. We can define error handling logic in this function. For the sake of simplicity, we just console.log() an error message.

Let's test our simple function. Save the file, refresh the page in the web browser, and click the button. Within a few seconds, we should see a huge array of objects in our console: this is the data we are going to display. Take a minute and have a good look at the structure of the data we've just received. What properties does each object have? Try to change the URL parameter in the xhr.open() to some wrong URL, what will the console display now when we click the button?

Change the URL back to 'https://jsonplaceholder.typicode.com/posts' and let's move on to displaying our data on the page.

function fetchPosts () {
  let xhr = new XMLHttpRequest();

  xhr.onload = function() {
    let posts = xhr.response;

    posts.forEach(function (post) {
      let postDiv = document.createElement('div');
      postDiv.className = 'postsDiv__postDiv';

      let postHeader = document.createElement('h3');
      postHeader.textContent = post.title;
      postHeader.className = 'postsDiv__postDiv__postHeader';

      let postBody = document.createElement('p');
      postBody.textContent = post.body;
      postBody.className = 'postsDiv__postDiv__postBody';


      postDiv.appendChild(postHeader);
      postDiv.appendChild(postBody);

      postsDiv.appendChild(postDiv);
    });

    fetchPostsBtn.disabled = true;
  }

  xhr.onerror = function() {
    alert('An error occurred!');
  }

  xhr.onloadstart = function() {
    spinner.style.display = 'block';
  }

  xhr.onloadend = function() {
    spinner.style.display = 'none';
  }

  xhr.open('GET', 'https://jsonplaceholder.typicode.com/posts');
  xhr.responseType = 'json';
  xhr.send();
}

Here we added logic to the xhr.onload and xhr.onerror methods, and added two new methods: xhr.onloadstart and xhr.onloadend.

In the xhr.onload method, we first declare a variable posts and assign it the value of xhr.response, making it an array of objects. Then, we use Array.forEach() method of the posts variable, to iterate over each post in our array. In the callback function for each item in the array, we create a new HTML <div> element, with the class of 'postsDiv__postDiv'. This will be the container for the post. After that, we create HTML elements for the post header and body (h3 and p, respectively), and assign their .textContent property to the value of the respective properties of the post: post.title and post.body. At the end of the iteration, we append the postHeader and postBody to their container postDiv, and append our postDiv to the postsDiv to add the newly-created element to the DOM tree. After all the iterations, we disable the fetchPostsBtn by assigning its .disabled property to true.

In the xhr.onerror method, we simply instruct the code to show a standard browser alert pop-up with a message 'An error occurred!'.

Finally, in the xhr.onloadstart and xhr.onloadend we show and hide the spinner by setting its .style.display property to 'block' when the request starts, and hiding it from the screen with .style.display set to 'none' when the request finishes (successfully or not).

Now it is time to test our app! Save the file and refresh the tab in the browser. Click the button to load the posts. We should see something like this:

Try and change the URL to something wrong once again: after a while, a pop-up alert should tell you that some error occurred.

Nice! Our application works as intended: we asynchronously fetch posts on button click without freezing the browser and let our user know if something is going on by showing the 'Loading...' message and alerting the user if a problem took place.

As a little bonus, let's style our app a little bit, to have a fancy moving spinner and neatly-looking posts.

Change the spinner div in the following way:

<main>
  <h1>Browser example</h1>
  <h2>Posts</h2>
  <button 
    id="fetchPostsBtn"
  >
    Fetch Posts
  </button>
  <div id="spinner" style="display: none;">
    <div></div>
    <div></div>
    <div></div>
    <div></div>
  </div>
  <div id="postsDiv">
  </div>
</main>

These new divs are needed to create the spinner effect.

And in the head between style tags add the following CSS code:

/* Styling the heading */
h1 {
    text-align: center;
}

h2 {
    text-align: center;
}

#fetchPostsBtn {
    display: block;
    margin-left: auto;
    margin-right: auto;
}

/* Styling the posts */

#postsDiv {
    display: flex;
    flex-direction: row;
    justify-content: center;
    flex-wrap: wrap;
}

.postsDiv__postDiv {
    width: 15em;
    min-height: 10em;
    margin: 0.3em;
    animation: postEnter 0.5s forwards;
}

.postDiv__postHeader {
    text-align: center;
}

.postDiv__postBody {
    text-align: justify;
}

@keyframes postEnter {
    from {
        opacity: 0;
        transform: translate(0, 10em);
    }
    to {
        opacity: 1;
        transform: translate(0, 0);
    }
}

/* Styling the spinner */

#spinner {
    display: block;
    position: fixed;
    top: 30vh;
    left: calc(50% - 20px);
    width: 40px;
    height: 40px;
}

#spinner div {
    box-sizing: border-box;
    display: block;
    position: absolute;
    width: 32px;
    height: 32px;
    margin: 4px;
    border: 4px solid rgb(30, 191, 255);
    border-radius: 50%;
    animation: spinnerAnimation 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite;
    border-color: rgb(30, 191, 255) transparent transparent transparent;
}

#spinner div:nth-child(1) {
    animation-delay: -0.45s;
}

#spinner div:nth-child(2) {
    animation-delay: -0.3s;
}

#spinner div:nth-child(3) {
    animation-delay: -0.15s;
}

@keyframes spinnerAnimation {
    0% {
        transform: rotate(0deg);
    }
    100% {
        transform: rotate(360deg);
    }
}

Here we used some CSS animations and :nth-child() CSS-pseudoclass to create the moving spinner effect, added an animation effect for the posts. By making the postsDiv a flexbox with flex-wrap: wrap; property and setting the width of the postsDiv__postDiv class we will now have a nice grid of posts.

Save the file and refresh the tab with client-side-example.html. We will see something like this:

Looks much more interesting! Check the code in the sandbox for reference. Try and change some CSS: maybe you want to have a different look on the button and posts? Or a fancier spinner? Check out this great resource for free pure-CSS spinners you can tweak and use in your projects.

Conclusion

Phew! It was quite a ride! Today we’ve learned a lot about asynchronous programming in JavaScript. We saw why we need asynchronous code in the first place, what kind of problems it solves, re-introduced ourselves to function declaration and invocation in JavaScript, wrote an asynchronous function of our own, and implemented server- and client-side examples of asynchronous code using callbacks.

I really hope some of the asynchronous stuff “clicked” on you after this little tutorial. If not, don’t be afraid: callbacks can be really hard to wrap your head around. Review the code you’ve just written, draw some lines and arrows in your head or on the paper: where’s the function’s declaration? where it gets called?

If you feel a runner’s high (or coder’s high?) after this tutorial: nice! Take a little break, and then open up some documentation or articles that seemed useless before, tweak our examples a little bit or write some of your own: add some new features, read the API reference of the XmlHttpRequest and Node.js fs module. There’s a lot of amazing stuff ahead like Promises and async/await. The journey is long, but you’ve just made a huge leap forward!

As a small bonus, a book I cannot recommend enough: Node.js design patterns by Mario Casciaro. Personally, I'm not a big fan of using books when it comes to learning programming languages and frameworks. This one, however, totally worth checking out. Despite the name, it's not just about design patterns or even Node.js in particular: it's a practical guide on JavaScript and designing applications as a whole. It's a tough read, but it can definitely help to take your skills to the next level.

Hope you've enjoyed this tutorial, and I'd really appreciate knowing your impressions.

Have a good one!

DEV Community: Dmitry

Timeline portfolio map with React and D3.js | Part II

Table of contents

Putting nodes on lanes

Drawing lines to nodes

Rich content cards

Animating resize

Wrap up

Timeline portfolio map with React and D3.js | Part I

Table of contents

Prerequisites, tech stack and scope

Initial setup and structure

Data models and sample data

Responsive timeline map

Putting nodes on timeline

Let's Build Animated Pagination with React!

Problem and Objective Overview

Basic Setup

Building Pagination component

Adding Page Transitions

Swipe It!

Conclusion

No-headache Asynchronous JavaScript for Beginners

A step back

Data in a program

Function declaration and invocation

Call me maybe!

Server-side example

Client-side example

Conclusion