gitwtfhub

wtf is gatsby-theme-waves?

relequestual/gatsby-theme-waves — explained in plain English

Analysis updated 2026-07-19 · repo last pushed 2019-08-13

JavaScriptAudience · developerComplexity · 3/5DormantSetup · moderate

TL;DR

A Gatsby theme that adds scroll-driven animations to MDX content, letting you create step-by-step tutorials where code snippets and visuals change as the reader scrolls.

Mindmap

mindmap
  root((repo))
    What it does
      Scrollytelling for MDX
      Code updates on scroll
      Highlights changed lines
    Tech stack
      Gatsby
      MDX
      JavaScript
    Use cases
      Technical tutorials
      Data visualizations
      Explanatory blog posts
    Audience
      Gatsby site authors
      Tutorial writers
      Documentation creators
    Status
      Experimental
      More wave types coming
      Better docs planned

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Create a step-by-step coding tutorial where code blocks update as the reader scrolls through explanations.

REASON 2

Build data visualization blog posts where charts and visuals change in sync with the narrative.

REASON 3

Write technical documentation that progressively walks readers through code evolution.

REASON 4

Develop interactive explainers that highlight specific lines or columns of code at each step.

What's in the stack?

GatsbyMDXJavaScript

How it stacks up

relequestual/gatsby-theme-waves3rd-eden/ircb.ioa15n/a15n
LanguageJavaScriptJavaScriptJavaScript
Last pushed2019-08-132016-11-162019-04-07
MaintenanceDormantDormantDormant
Setup difficultymoderateeasyeasy
Complexity3/52/52/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Requires an existing Gatsby site with MDX already configured, you must add the theme to gatsby-config and merge style settings.

No license information provided in the README.

Wtf does this do

Gatsby Theme Waves is a tool for people who write blog posts or documentation using MDX (a format that mixes Markdown with interactive components). It adds "scrollytelling" to your content, meaning elements on the page, like code snippets, images, charts, or maps, animate and change as the reader scrolls down. Instead of presenting a static block of code or a single image, you can guide readers through a progression, highlighting specific lines or swapping visuals step by step. At a high level, you wrap your content in a special component, like CodeWave. Inside that wrapper, you alternate between code blocks and regular Markdown text. As the reader scrolls through the text, the code block above or beside it updates to reflect what's being discussed. By default, the tool highlights the lines that changed between consecutive code blocks, but you can also manually specify which lines or even which columns within a line to highlight. This is useful for anyone writing technical tutorials, data visualizations, or explanatory blog posts on a Gatsby site. For example, if you're teaching someone how a piece of code evolves, say, building a function step by step, you can show each iteration alongside the explanation, so the reader sees the code change in sync with your narrative. The live demo linked in the project gives a clear sense of the effect. The project is still experimental, as noted in the README. Setting it up requires an existing Gatsby site with MDX already configured, and installation involves adding the theme to your Gatsby config and merging some style settings. The README doesn't go into much detail beyond code blocks, but it mentions that more "waves" (likely other types of animated components beyond code) and better documentation are coming.

Yoink these prompts

Prompt 1
Install gatsby-theme-waves on my existing Gatsby site with MDX already set up. Walk me through adding it to gatsby-config.js and merging the style settings.
Prompt 2
Using gatsby-theme-waves, create a CodeWave MDX component that teaches a React useState hook step by step, highlighting the new lines added in each iteration.
Prompt 3
Show me how to manually specify which lines and columns to highlight in a CodeWave block instead of using the default changed-line highlighting.
Prompt 4
Create a scrollytelling blog post with gatsby-theme-waves that walks through building a JavaScript function, alternating between code blocks and explanatory text.
Prompt 5
Help me configure gatsby-theme-waves on my Gatsby blog so I can write tutorials where code snippets animate as readers scroll down the page.

Frequently asked questions

wtf is gatsby-theme-waves?

A Gatsby theme that adds scroll-driven animations to MDX content, letting you create step-by-step tutorials where code snippets and visuals change as the reader scrolls.

What language is gatsby-theme-waves written in?

Mainly JavaScript. The stack also includes Gatsby, MDX, JavaScript.

Is gatsby-theme-waves actively maintained?

Dormant — no commits in 2+ years (last push 2019-08-13).

What license does gatsby-theme-waves use?

No license information provided in the README.

How hard is gatsby-theme-waves to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is gatsby-theme-waves for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.