Ryan Geyer’s Blog

I finally found a use for ChatGPT: Workout routines

Ryan Geyer — Mon, 04 Dec 2023 22:56:10 GMT

I'll just come out and say it: I don't like ChatGPT very much.

When it comes to programming, I tend to find that there is rarely any overlap between the tasks which it is actually capable of doing competently, and the things which I actually would like an AI to help me with. However, I have finally found a non-programming use case which has genuinely been life-changing for me: generating workout routines.

I am very out of shape. I have been for quite a long time, but lately it has started to feel like a real problem which I can't keep ignoring; I'm only 28 but my joints are starting to ache and physical exertion often feels much harder than it should. I have a nice set of weights, but every time I feel motivated to work out, I have always ended up running into a wall: I have no idea what to do.

If we're being honest with ourselves, the proper answer to this problem should probably be to join classes or find a personal trainer, but this presents some additional problems for me: these options cost a non-trivial amount of money, require traveling to another location, can't be flexibly slotted into my day where I have time, and of course I've already spent a good chunk of change on my own equipment at home so I would like to justify that purchase if I can.

This is where ChatGPT comes in! I have crafted a prompt which allows me to use ChatGPT as a virtual fitness trainer. Now, I can just pop into that chat, type "Give me an upper-body workout", and it will generate a routine for me on demand!

Now, it's not perfect: despite really hammering on the fact that I don't want it to include exercises which require equipment that I don't have access to, it still suggests exercises requiring an exercise bench with annoying frequency. Of course, I am not a great prompt engineer, so I'm sure my prompt could be tightened up a lot as well. Despite these imperfections, it always gives me a starting point, and it has generally done a pretty good job at suggesting a fairly complete workout routine. If I can't do something it suggests, I just ask it to provide an alternative and it usually does better the second time around.

This has made a huge difference in allowing me to overcome my analysis paralysis and just start working out; my past attempts at getting fit usually sputter out within a couple weeks, but I am now well into my 3rd week of regularly exercising and I am feeling great about it.

If you can relate to my struggles of wanting to work out more but not knowing how to go about it, I can't recommend this approach highly enough. Give it a try!

My Garden In Review 2025

Ryan Geyer — Tue, 30 Dec 2025 22:25:33 GMT

figcaption {
  grid-column: 1/-1;
}

}

[aria-describedby="already-had-footnote"]::after { content: "*"; }

#already-had-footnote::before { content: "*"; } </style>

2025 is over, we're deep in the winter, and I'm missing my garden. What better time to review what happened this year and reminesce about back when things weren't gray, cold, and dead?

Native Plants

I'm very passionate about native plants and insects. In my opinion, landscaping with native plants is one of the easiest ways for an individual to make a noticeable positive impact on the environment. Getting to see beneficial insects and birds using the things you planted for them is so incredibly satisfying, and it makes me feel so much more connected to nature than I ever have before. As an extra bonus, native plants are adapted to living in your climate on their own, so they require much less maintenance once they're established!

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-08-11--full-front-garden-photo.jpg" alt="Two landscaping beds outlined with rocks in front of a house, separated by a strip of grass between them. Each bed has a birdbath and is filled with a variety of plants. The bed closer to the camera has a variety of plants in bloom, including Lanceleaf Coreopsis, Purple Coneflowers, Black-Eyed Susans, Anise Hyssop, and Wild Petunias."> <img src="/assets/blog/garden-in-review-2025/2025-08-11--front-garden-main-section.jpg" alt="A closer shot of the larger landscaping bed closer to the house. Purple Coneflowers and Black-Eyed Susans are absolutely thriving in this bed, along with a little bit of Butterfly Weed, one of my personal favorites."> <figcaption> Our front yard garden in August. Note that I am painfully aware that there are some non-native plants in here, but the ratio is probably 90% native and rising. </figcaption> </figure>

This was the second full growing season since I ripped up a bunch of our yard in the fall of 2023 and started the garden in earnest.

There were some disappointments; a couple things I planted in the previous year didn't work out or struggled a lot more than I expected, including some plants that I was really excited about. But failure is part of the journey, and I'm learning a lot about what plants will work where depending on their needs.

With that said, I think things are still going great and this was overall a very successful year.

What I planted this year

I was a little out of control this year.

My parents got me a gift certificate for the Wildtype plant nursery near where I grew up so I took a trip out there this spring and loaded up. It was an awesome experience! If you're located in Mid-Michigan and looking for native plants, you can't do better than Wildtype.

Most of the plants listed here came from Wildtype, but I couldn't help but keep adding more to my collection from other nuseries here and there as the year went on. So here is the full list, minus a couple things I know I bought but apparently didn't keep records of and I have no idea what they were now. Guess that'll be a fun surprise next year!

New Jersey Tea
Wild Strawberry
Common Violet
Little Bluestem
Golden Ragwort
Blue Vervain
Showy Goldenrod
Joe Pye Weed
Mountain Mint
Turtlehead
Northern Blazing Star
Dense Blazing Star
Dwarf Blazing Star
Wild Hyacinth
Anise Hyssop
<span aria-describedby="already-had-footnote">Swamp Milkweed</span>
<span aria-describedby="already-had-footnote">Butterfly Weed</span>
<span aria-describedby="already-had-footnote">Wild Columbine</span>

<span id="already-had-footnote">already had some, but added more</span>

We ripped up two invasive Burning Bushes to replace with New Jersey Tea, I'm excited about that upgrade.

You may also notice that I went on quite a Blazing Star kick, getting 3 different varieties. A house in our neighborhood has an incredible yard full of native plants and every fall I see their Blazing Stars absolutely dripping with Monarch Butterflies and it fills me with envy, so I'm trying to copy them.

I planted a majority of these plants in the spring, and for the most part they did great! Some plants can be a little boring in their first year, especially if you planted them in the spring instead of the previous fall, but at least most of these stayed fairly happy and healthy. I'm excited to see what they do next year.

Bugs

The best part of native plant gardening is all the cool bugs that they attract! This was a great year for that. Here's some of my favorite photos I got, all taken on my phone for better or worse. I tried my best to identify them correctly but may have gotten some wrong because I'm not even close to an expert!

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-08-23--monarch-cat-1.jpg" alt="A monarch butterfly caterpillar climbing around on swamp milkweed. Monarch caterpillars have black, white, and yellow stripes and have pairs of black tentacles on their head and rear. I say 'tentacles' instead of 'antennae' because apparently there is a meaningful difference; an antenna is considered to be stiff and rigid while a tentacle is more flexible and soft."> <img src="/assets/blog/garden-in-review-2025/2025-08-25--monarch-cat-2.jpg" alt="A smaller monarch butterfly caterpillar on the underside of a swamp milkweed leaf, nibbling on the end of it."> <figcaption>Monarch Caterpillars</figcaption> </figure>

<figure> <img src="/assets/blog/garden-in-review-2025/2025-07-05--brown-belted-bumblebee.jpg" alt="A bumblebee on a purple coneflower. The bee has a fuzzy yellow mane around its shoulders and back, and a brown-ish patch on its back which is why I think it's a Brown-Belted Bumblebee. The bee has a big grayish-yellow pollen sac on its hind leg. Some bee species' females have 'pollen baskets' on their hind legs which pollen accumulates in as they go from flower to flower. The photo is an extreme close-up which reveals a lot of detail; you can see little yellow specs of pollen on the flower and on the bee's face."> <figcaption>Brown-Belted Bumblebee</figcaption> </figure>

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-07-15--black-swallowtail-cat-1.jpg" alt="A black swallowtail caterpillar climbing up the stem of a carrot. Black swallowtail caterpillars are green with stipes running along their back that are composed of a series of black and yellow dots."> <img src="/assets/blog/garden-in-review-2025/2025-07-20--black-swallowtail-cat-2.jpg" alt="A close-up shot of a black swallowtail caterpillar on the stem a carrot, about to eat some leaves on the end."> <figcaption>Black Swallowtail Caterpillars</figcaption> </figure>

<figure> <img src="/assets/blog/garden-in-review-2025/2025-06-09--eight-spotted-forester-moth.jpg" alt="An Eight-Spotted Forester moth. This is a very cool looking moth. It has a black body with orange tufts on its legs and yellow spots on what I guess I would call its shoulders? Its wings are all black with 2 white spots on each. It's not visible here but they have an additional set of inner wings which also have 2 spots each, bringing us to the eight spots in the name!"> <figcaption>Eight-Spotted Forester Moth</figcaption> </figure>

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-07-29--monarch-1.jpg" alt="A Monarch Butterfly eating nectar from Swamp Milkweed flowers. Monarch Butterflies have black bodies with white spots, and their wings are orange with black lines running through them and more black and white spots along the edges. This is not a great shot from a distance because I have found that Monarchs are annoyingly skittish and don't like me taking photos of them."> <img src="/assets/blog/garden-in-review-2025/2025-07-29--yellow-swallowtail.jpg" alt="A Yellow Swallowtail Butterfly eating nectar from Swamp Milkweed flowers. Yellow Swallowtails have yellow wings with black lines running through them. This Swallowtail appears to be a female, so it has a line of prominent blue spots along the edges of its lower wings, followed by a line of yellow spots. I believe males' blue spots are significantly less prominent."> <figcaption>Monarch and Yellow Swallowtail Butterflies on Swamp Milkweed</figcaption> </figure>

<figure> <img src="/assets/blog/garden-in-review-2025/2025-07-25--texas-leafcutter-bee.jpg" alt="A Texas Leafcutter Bee on a Swamp Milkweed flower. These bees are very cool because they have unique black and white colors instead of the typical black and yellow. As you might be able to guess from the name, leafcutter bees cut little bits off of plant leaves to build their nests with."> <figcaption>Texas Leafcutter Bee</figcaption> </figure>

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-08-13--bumblebee-on-cutleaf-coneflower-1.jpg" alt="A side profiel of a bumblebee on a Cutleaf Coneflower. The flower has thin oval-shaped yellow petals."> <img src="/assets/blog/garden-in-review-2025/2025-08-16--bumblebee-on-cutleaf-coneflower-2.jpg" alt="A close-up shot of a fuzzy little bumblebee on a Cutleaf Coneflower. The bee has gathered two orange pollen sacs, one on each hind leg."> <figcaption>Bumblebees on Cutleaf Coneflowers</figcaption> </figure>

Rain Barrels!

We've been dealing with annoying drainage issues since we got this house because the previous owners decided to pave so much usable yard space around our garage that when it rains, the water only has a few limited places to drain which causes the ground in those spots to basically become a completely saturated swamp.

I learned that our county has a program where you can apply for rebates for taking actions to improve drainage and reduce water usage, including installing rain barrels, so I went for it! It was a great easy process and we were approved for 2 rain barrels. Between getting all of the pieces to connect the barrels to our downspouts and the materials for building a simple wooden stand for one of the barrels, I ended up spending a bit beyond the maximum rebate amount, but we still got a really nice setup for something like 80% off!

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-05-30--rain-barrel-1.jpg" alt="A terra cotta-colored rain barrel on a patio. A flex tube is running from a nearby downspout to the top of the barrel so that rain running off of the roof will be diverted into the barrel."

<img src="/assets/blog/garden-in-review-2025/2025-05-30--rain-barrel-2.jpg" alt="A terra cotta-colored rain barrel, raised up on a wooden stand about 3 feet off the ground, on the other side of the house from where the first barrel is. A flex tube is running from a nearby downspout to the top of the barrel so that rain running off of the roof will be diverted into the barrel."

<figcaption> The two rain barrels I installed this spring. </figcaption> </figure>

Between installing these barrels and planting a bunch of water-loving native plants in one of the particularly swampy corners of our property, our drainage issues seem to have been almost completely resolved. Along with the drainage improvements, they were able to serve as a very reliable source of free water for my gardens! It's pretty astonishing to see how quickly these barrels can fill with even a relatively small amount of rain, and that rain goes much further than you might think. I barely had to use a garden hose to water anything all summer, which felt like a huge win.

Vegetables

I focus a lot of my energy on native plants, but I do grow some vegetables too! The last couple years, my attempts at growing vegetables went fine, but I kept making the mistake of growing things which seem neat, but weren't practical at all because we don't actually care to eat them that much.

So this year, I tried to shift my focus to things I knew we would use: cucumbers, tomatoes, and carrots.

I learned that tomatoes are pretty sensitive to cold, so in cold climates like Michigan, if you want to maximize their growing season you have to start them early indoors until it's consistently warm enough for them to go outside. I had tomato seeds I harvested last year from tomato plants that my partner's uncle had given us, so I just planted those in pots in early April and let them grow on my office window sill. I couldn't believe how many of the seeds germinated, this went better than I could have dreamed.

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-04-02--tomato-seedling.jpg" alt="A close-up of two tiny tomato plant seedlings poking out of the dirt in a small pot on a window sill."

<img src="/assets/blog/garden-in-review-2025/2025-04-26--larger-tomato-seedling.jpg" alt="A small pot on a window sill with 4 small tomato plants in it. One of the plants is getting particularly tall, probably about 8-10 inches."

<figcaption> Indoor tomato growth progress from week 1 to week 4. </figcaption> </figure>

The tomatoes and cucumbers ended up being massive successes. We had a near-constant supply of fresh cucumbers and tomatoes all summer, and it never felt like we couldn't find enough uses for them. Lots of great salads, and I became quite fond of a "greek chickpea bowl" type thing which was just chickpeas, red onions, cucumbers, and tomatoes over rice with tzatziki sauce. Delicious.

We did have some points where we were starting to drown in cucumbers, but people love cucumbers so it was pretty easy to offload them on friends and family.

<figure class="two-col"> <img src="/assets/blog/garden-in-review-2025/2025-08-13--tomatoes.jpg" alt="A raised garden bed with a trellis attached with a bunch of cherry tomato plants growing up it. On the other side of these tomatoes is a dense thicket of Jerusalem artichokes. We'll get to that."

<img src="/assets/blog/garden-in-review-2025/2025-08-13--cucumbers.jpg" alt="A raised garden bed with a trellis attached with cucumber vines growing up it. On the other side of these cucumbers is a patch of carrots."

<figcaption> The tomatoes and cucumbers at their peak in mid-August. </figcaption> </figure>

As for the carrots... We did use some! Nowhere close to all of them though. As it turns out, carrots don't always grow as nicely as you see them in the store (or I may have messed something up, not going to rule that out); a lot of them came out short and knotty and kinda ugly, but they did still get the job done. The real problem is that we realized that most dishes that we like to use carrots in are things like soups and stews which don't quite feel as appealing in the summer. I think the ideal setup is to harvest the carrots in the fall and store them in some way that allows them to stay good over the winter, but I'm not sure what that looks like right now.

<figure> <img src="/assets/blog/garden-in-review-2025/2025-11-04--carrots.jpg" alt="A bunch of carrots held up in front of the camera by a hand. The carrots are all varying sizes from about 3-6 inches. The carrots all have a bunch of places where they have knots and forks where they diverged and started growing in two different directions."

<figcaption> Some gnarly-looking carrots. </figcaption> </figure>

I haven't mentioned the fourth vegetable I grew in our vegetable garden yet... Jerusalem Artichoke. I had a dish which featured Jerusalem Artichoke at a restaurant the year prior and became fascinated by it. It's a native plant which is very beneficial to pollinators, but it has edible tubers that taste kinda like a nutty potato and can basically be cooked the same ways a potato can.

<figure> <img src="/assets/blog/garden-in-review-2025/2025-09-23--common-checkered-skipper.jpg" alt="A close-up shot of a Common Checkered Skipper on a Jerusalem Artichoke flower. The flower is bright yellow with medium-length petals that come to a point. These plants are in the sunflower family and can grow up to 10 feet tall. The skipper is a small butterfly with brown and white spotted wings."

<figcaption> A Common Checkered Skipper on a Jerusalem Artichoke flower. </figcaption> </figure>

Here's the thing... you're supposed to wait to harvest them until after the first frost, but things got away from me and I just never harvested them. Now the ground is too frozen for me to dig them up, so I'm going to have to wait for a day this winter when things thaw out enough that I can run out there and grab some.

Even if they're good, I think it was still a mistake to grow this because the ratio of how much space in my garden they took up to the number of times we'll actually eat them is completely off. It was nice to grow them for the pollinators, but the raised garden beds are supposed to be the little patch that's reserved for what us humans want to eat. I think next year I'm going to try replacing them with Jalapeños.

Wrapping Up

Whew, that was a lot! 2025 wasn't a great year for much, but I had a great time with my plants at least. Here's hoping that next year will be even better!

A simple way to programmatically detect support for cascade layers

Ryan Geyer — Thu, 12 Oct 2023 17:39:00 GMT

I recently needed to be able to programmatically test if a browser supports the relatively new @layer Cascade Layers CSS feature (in my opinion, one of the most exciting and underrated recent additions to CSS).

However, I quickly ran up against a big problem: @support queries don't work for at-rules like @layer! I'd love to be able to do something like what's suggested in this issue:

const doesSupportCascadeLayers = window.CSS.supports("at-rule(@layer)");

But currently, no dice. After a lot of searching around, I almost thought I was out of luck, but then I discovered that Cascade Layer support also comes along with the presence of some global classes which we can test for the existence of on the window!

This works like a charm:

const doesSupportCascadeLayers = "CSSLayerStatementRule" in window;

Unfortunately, I don't think there's any way to detect @layer support in pure CSS, but this was thankfully enough to satisfy my needs.

How Waymark finds all of the image elements on your website

Ryan Geyer — Sat, 16 Sep 2023 21:15:58 GMT

At Waymark, one of our core features involves generating brand profiles from user-provided website URLs. This process includes importing images from your website to save you time from having to upload content yourself, identifying which image is most likely to be your brand's logo, writing a summary of your brand which can be used to inform our AI-powered video generation, and more.

There is a lot of interesting stuff going on here, but in this article I am going to focus on the journey that we have gone on figuring out a way to get as many quality images from a page as possible. It's not as easy as you might think!

1. The simplest approach

Our image extraction works by opening the provided site in Puppeteer, so the very first approach that I took when writing this image extraction logic was by far the most appealing at first glance; Puppeteer allows you to intercept network requests made from the page and access the media type of the request, so it's possible to get pretty good results by simply intercepting all requests with an "image" media type and adding those URLs to a set, waiting for the page's network requests to settle, and calling it a day. The code would look something like this:

const imageURLSet = new Set<string>();

await page.setRequestInterception(true);
page.on('request', (request: HTTPRequest) => {
  const resourceType = request.resourceType();

  if(resourceType === 'image'){
    imageURLSet.add(imageURLSet.url());
  }
});

This is lovely! It allows the browser to do the work for us and we can just kick back and pick up the images as they roll in.

But of course, this approach has downsides:

Data URLs and inline SVG elements will not show up as network requests, so if you care about getting those images, you will need to add some extra handling. SVG elements are relatively easy to query for, but data URLs may prove to be a lot harder to track down.
The image URLs that come in are entirely black-boxed; if you care about getting additional context about the images such as where they are positioned on the page, this approach will not work for you.

As it turns out, Waymark needs to gather a lot of context about how image elements are displayed on the page to inform how we determine which image is most likely to be the brand's logo, so that second downside was a big problem. I initially tried rolling with some awkward solutions where we would reverse engineer an img element selector matching the image URL, like document.querySelector(`img[src*='${imageURLPathname}']`). But what if the image was loaded from an srcset? Or a picture <source> tag? Or a CSS background image? The list of edge cases kept growing, and it started to become clear that there were just too many gaps for us to be able to confidently provide an acceptable experience to as many users as possible.

2. BRUTE FORCE

So, we need to be able to get the elements for as many images on the page as possible. The simplest approach would be to just directly query for all <img>/<svg> elements on the page and go from there, but there didn't seem to be a good way to query for elements with a CSS background image. As such, my next approach was to just throw brute force at it by traversing down every single node in the DOM tree and checking if it was an <img>, an <svg>, or had a background-image CSS style. This worked... but it was slow, inefficient, and simply overkill. Even worse, the code was pretty hard to read/maintain/debug because it had to all run in a huge monolithic script that was excecuted on the page in Puppeteer, where it becomes a lot harder to reliably log or trace errors.

Overall, this did close a lot of the gaps that the previous approach had left, but it left me wanting. Eventually, an opportunity came to refactor this code during an initiative to further improve the reliability of our image extraction and logo identification, and I took it.

3. Figure out where the images are and go there directly

So, in the first approach, we tried just letting the images come to us, but this had some drawbacks by limiting the amount of information we could easily access.

In the second approach, we went in the complete opposite direction and tried desperately digging through every nook and cranny of a site looking for images.

But I have finally landed on a third approach which, in my opinion, works as a really nice middle-ground between the two. Earlier I mentioned that it didn't seem like there was a good way to query for elements with CSS background images, but that problem sat with me for a while; at the end of the day, any CSS styles are applied with a selector. Theoretically, couldn't we figure out how to parse the page's stylesheets, extract the selector(s) for any background-image styles, and directly query for them? Well, yes we can!

All of the stylesheets loaded on the page, both from inlined <style> tags and external linked CSS files, can be accessed on document.styleSheets.

This will return a list of CSSStyleSheet instances, each of which should include a cssRules property that enumerates every valid style rule parsed from the stylesheet. Unforunately, depending on how the site in question was implemented, directly accessing a stylesheet's cssRules may throw a CORS error if the stylesheet came from a different origin without a crossorigin="anonymous" attribute on the <link> tag.

This led me down a ridiculous aside writing a script to fetch each stylesheet as a string, manually search it for every instance of a background image style rule, and then construct the selector for that style rule, taking into account that nested CSS selectors are now supported in most browsers. I had a blast writing it and got it working well, but it is extremely important to remember that anytime you write code which could be described as "a fun puzzle", you need to deeply interrogate if it's actually a good idea to put it in production.

Of course, there were two much simpler solutions to this problem:

We control the Puppeteer browser, we can just disable CORS errors if we want.
Pretty much every modern browser supports creating constructed stylesheets with the CSSStyleSheet constructor. This exposes an API to parse a CSS stylesheet string in the exact way that browsers parse all other stylesheets, so you know it should work quickly and reliably.

I tinkered with disabling CORS, but started feeling a little uneasy as I realized that the Chromium flags required to achieve this appear to have shifted over the years; a simple "--disable-web-security" used to be all you needed, but more modern answers seem to indicate that you now also need to provide "--disable-features=IsolateOrigins" and "--disable-site-isolation-trials" flags as well. I don't think Chromium considers disabling CORS to be an important feature that people are supposed to be using (and for good reason!) so maybe we shouldn't bank on that API not changing under our feet.

So, the constructed stylesheet approach started looking a lot more appealing. And it worked like a dream! Here's what the code looks like to make this work:

// Gather the text contents of all of the stylesheets on the page into a big combined string
const combinedStylesheetString = (
  await Promise.all(
    Array.from(document.styleSheets).map(async (styleSheet) => {
      try {
        if (styleSheet.href) {
          // External stylesheets have an href which we can fetch
          return await fetch(styleSheet.href).then((response) => response.text());
        } else {
          // We can directly access the <style> tags for inlined stylesheets via styleSheet.ownerNode
          return styleSheet.ownerNode?.textContent || '';
        }
      } catch (e) {
        return '';
      }
    }),
  )
).join(' ');

const parsedStylesheet = new CSSStyleSheet();
await parsedStylesheet.replace(combinedStylesheetString);

Now that we have a CSSStyleSheet instance to work with, we can search it for any background image style rules and get the selectors for those rules.

const backgroundImages = new Array<{
  selector: string;
  imageURL: string;
}>();

// Regex matches `url("<url-here>")` styles so we can extract the URL from a background image style
const cssURLStyleRegex = /url\(['"](.*?)['"]\)/;

const rules = parsedStylesheet.cssRules;

for (const styleRule of rules) {
  if (!(styleRule instanceof CSSStyleRule)) {
    continue;
  }

  let backgroundImageURL: string | null = null;

  const styleDeclaration = styleRule.style;
  backgroundImageURL = styleDeclaration.backgroundImage?.match(cssURLStyleRegex)?.[1];
  if (!backgroundImageURL) {
    backgroundImageURL = styleDeclaration.background?.match(cssURLStyleRegex)?.[1];
  }

  if (backgroundImageURL) {
    // If we found a background style with an image URL in it, we can get the selector for that style rule
    // on `styleRule.selectorText`
    backgroundImages.push({
      selector: styleRule.selectorText,
      imageURL: backgroundImageURL,
    });
  }
}

So now, we have a list of background image URLs and their selectors parsed from the page's stylesheets. Now if we want to find all of the elements on the page with background images, all we have to do is query for those selectors!

const backgroundImagesWithElements = backgroundImages.flatMap(({
  selector,
  imageURL,
})=>{
  const elementsMatchingSelector = document.querySelectorAll(selector);
  return Array.from(elementsMatchingSelector).map((element) => ({
    element,
    imageURL,
  }));
});

I'm very pleased with this solution. If we're honest with ourselves, it's still a little complex, but a major improvement over our previous attempts at gathering background image elements.

Now at this point, you can easily query for image tags with document.getElementsByTagName("img") and SVGs with document.getElementsByTagName("svg").

I will not argue that any solution is absolutely bullet-proof, but this feels the closest we've ever gotten. Of course, I have seen plenty of... "creatively" written websites while working on this feature to know that there will always be some website out there which defeats our image extraction. But that number is shrinking, and we'll keep working to get it lower and lower if we can.

Reflecting on hover-video-player v1.2

Ryan Geyer — Sat, 11 May 2024 18:06:26 GMT

Back in January when I released hover-video-player v1.1, it felt like it was finally a "finished" project; the component was meant to be extremely simple, and it seemed like there were no more obvious gaps in basic functionality that still needed to be added.

The next week, I got a new issue asking for a feature which was not currently supported. Classic.

For those unfamiliar, hover-video-player is a web component which can be used to add videos to your page which will play on hover, like a YouTube thumbnail preview. I use it on the homepage of this very site. It's based on the significantly more popular react-hover-video-player library which I also maintain, but as I have fallen more and more out of love with React, I confess that hover-video-player has become my favorite child.

The issue I received was a single sentence, a fairly innocent question: "Is there an easy way to keep one video playing at all times, even when none is hovering?"

This one put me in a bad mood. This project isn't finished at all. I did not and still don't have any plans to build specific behavior into the component which involves syncing with other components' states, but my existing implementation didn't expose APIs which would allow you control component state externally in order to implement that behavior yourself.

I didn't feel like I had any good ideas on how to approach the problem, nor did I feel much motivation to figure it out, so I just let the issue sit unaddressed. I spent the next 4 months feeling weirdly guilty about ignoring it, and then suddenly I recently had a burst of motivation to just power through and get this thing done.

So, here's what I did!

The changes

Adds the ability to place a <hover-video-player> component in "controlled" mode, meaning it will stop responding to hover events and allow you to have full programmatic control over when to start/stop video playback
- This can be turned on by either setting a controlled HTML attribute on the element or running hoverVideoPlayer.controlled = true in JavaScript.
Adds a hover() method to programmatically transition the player into a "hovering" state which will start playing the video
Adds a blur() method to programmatically transition the player out of the "hovering" state to pause the video
The component will now respond to externally-set data-playback-state attribute values
- This means you can make the video auto-play if you set an initial data-playback-state="playing" attribute!
- You can even start playback with hoverVideoPlayer.dataset.playbackState = "playing" if hoverVideoPlayer.hover() isn't verbose enough.
Makes hoverstart and hoverend events cancelable
- These events can now be intercepted and canceled with event.preventDefault() if you want to prevent the player state from updating in response to a hover/blur event.
- The new "controlled" mode is literally just syntactic sugar for calling preventDefault() for both hoverstart and hoverend events every time they are emitted.

These new APIs unlock everything that is needed in order to build the experience that the original issue that prompted all of this was asking about. I made a proof-of-concept in codepen which works pretty well!

Unfortunately I got a little overly excited and what started as a clean v1.2.0 release quickly turned into 4 rapid follow-up versions with lots of bug fixes and API refinements, finally bringing us to v1.2.4. This is the last one, I swear.

Having to make that many follow-up releases for a project is not the best, I'll openly admit that. However, there is something extremely powerful about publishing something before it's done. Like clockwork, as soon as it goes up, I'll think of another issue that I didn't account for and then I'm back in the code mines fixing it. It's not a good loop, but you can't argue it doesn't get results. In the future, I'm going to try using a beta channel for releases until I'm 100% confident that everything is set in stone; maybe that will produce a similar effect without also putting people using the library in harm's way.

What I learned

This library has helped me discover a ton of patterns I love for writing web components. When I first wrote hover-video-player, I stumbled into a new pattern which would later become popularized under the term "HTML Web Components"; components which enhance child content instead of being concerned with rendering the content themselves. It felt like an incredibly refreshing way of designing web components, and it even influenced how I design React components (I still need to write a blog going into more depth on that).

My favorite takeaway from this work was that JavaScript's built-in event interfaces are really great to work with. I had to think very hard and go through a couple iterations figuring out how I could expose a reasonable API for disabling a <hover-video-player> element's default behavior when a hover/blur event is fired, and achieving that by making the events cancelable with preventDefault() just feels so elegant and like it really goes with the grain of how native HTML elements work. Super refreshing.

For any who are curious how cancelable events work, this is it:

const evt = new Event("myevent", {
  cancelable: true,
});
// wasNotCanceled will be `false` if `evt.preventDefault()` was called in any handlers for this event.
// I kinda wish the values were flipped so it would return `true` if the event was canceled since this makes
// variable naming a little more awkward, but oh well.
const wasNotCanceled = eventTarget.dispatchEvent(evt);

I had no idea it was that easy!

However, I was also reminded that CustomEvents in TypeScript come with some extremely frustrating downsides; there is no good way to register typings for the events which a custom element can emit, and even if you know for certain that a given event will have a CustomEvent object instead of a plain Event object, TypeScript is going to fight you every step of the way until you've either added a bunch of extremely obnoxious unnecessary runtime checks or have just given up and cast everything as any.

For example, TypeScript will complain about this code block:

// ts error: Argument of type '(evt: CustomEvent<"paused" | "loading" | "playing>) => void' is not assignable to parameter of type 'EventListenerOrEventListenerObject'.
hoverVideoPlayer.addEventListener("playbackstatechange", (evt: CustomEvent<"paused" | "loading" | "playing">) => {});

This is what you have to do to satisfy it while still having evt.detail typed as expected:

hoverVideoPlayer.addEventListener("playbackstatechange", (evt) => {
  if (!(evt instanceof CustomEvent)) {
    return;
  }

  // evt.detail is now typed as any. Not very typesafe. The only way to narrow the type from
  // here is like this:
  const newPlaybackState: unknown = evt.detail;
  if(newPlaybackState !== "paused" && newPlaybackState !== "loading" && newPlaybackState !== "playing") {
    return;
  }

  // newPlaybackState can now be treated as a union of the 3 valid playback states
});

As web components continue to gain steam, this feels like an issue that TypeScript needs to address sooner than later. I'd be very interested to see if there are any proposals out there on how to make this developer experience better.

Micro-optimizing boolean-to-int conversions for... fun?

Ryan Geyer — Mon, 17 Mar 2025 21:29:28 GMT

Who doesn't love a little micro-optimization? I love messing around with in my side projects to push the performance as far as I can. I'm currently working on an RSS feed reader which uses IndexedDB, and as it turns out IDB doesn't allow boolean values to be indexed.

This meant that I had to start representing a boolean value as the numbers 0 or 1, and this raised an important question: what is the absolutely blazing-est fast-est-est way to coerce a boolean value into an integer in JavaScript?

The setup

First, let's all say it together: micro-benchmarks are bad and rarely a good measure of anything. I tried my best to get something meaningful out of this, bu all results here should be taken with a grain of salt.

I used https://jsbench.me to set up my tests and ran them in every browser. First, I have a setup script that executes before every run:

// Make an array of a random size between 128-256
const bools = new Array(128 + Math.floor(Math.random() * 128));
// Randomly fill the array with boolean values
for (let i = 0; i < bools.length; ++i) {
  bools[i] = Math.random() < 0.5;
}

Then I had each test case loop over the bools array and use a different method to coerce each value into an integer:

// Ternary
for (const bool of bools) {
  const num = bool ? 1 : 0;
}

// Casting with Number constructor
for (const bool of bools) {
  const num = Number(bool);
}

// Bitwise operator
for (const bool of bools) {
  const num = bool & 1;
}

Going into this, my hypothesis was that the ternary operator would perform the worst since it involves branching, then casting would be a little faster, and the bitwise operation would be a little faster still.

The results

We will use the ternary operator as our baseline, as that's what I would consider the most "readable" approach which I would actually use in a shared codebase where I'm worried about maintainability. I ran these tests in 3 different browsers and was pretty surprised by the results.

Browser	Ternary	Casting	Bitwise
Chrome	584K ops/s	752K ops/s (+29%)	1M ops/s (+78%)
Firefox	1.8M ops/s	439K ops/s (-75%)	1.8M ops/s (-)
Safari	3.2M ops/s	3M ops/s (-)	3.1M ops/s (-)

Say what you will about Safari but boy is it fast. Not only did all 3 results fall within the margin of error of each other, they also all ran over 3-5 times faster than Chrome!

Firefox didn't do too bad either, with the ternary and bitwise cases both running very fast and staying within the margin of error of each other. However, casting with the Number constructor did very poorly in Firefox, producing the slowest results out of any of the tests run.

And so that leaves us with Chrome. These results come the closest to what my expectations had been, but even then I was surprised by how big the performance gap was between each approach. I certainly did not expect bitwise operations to outperform ternary operators by nearly 2x!

Negation

Now I was curious, does this look any different in cases where we want to negate the value so that true becomes 0 and false becomes 1? I wrote some new test cases to see:

// Ternary
for (const bool of bools) {
  const num = bool ? 0 : 1;
}

// Casting with Number constructor + NOT
for (const bool of bools) {
  const num = Number(!bool);
}

// Casting with Number constructor + subtraction
for (const bool of bools) {
  const num = 1 - Number(bool);
}

// Bitwise operator
for (const bool of bools) {
  const num = bool ^ 1;
}

Browser	Ternary	Casting + NOT	Casting + Subtraction	Bitwise
Chrome	586K ops/s	455K ops/s (-22%)	679K ops/s (+16%)	1.1M ops/s (+87%)
Firefox	1.7M ops/s	430K ops/s (-75%)	428K ops/s (-75%)	1.7M ops/s (-)
Safari	2.9M ops/s	3.1M ops/s (-)	3M ops/s (-)	3.1M ops/s (-)

The results look pretty similar to last time, but I was interested to see that Chrome performs significantly worse when combining a Number cast with a NOT operator. I'm not sure why that would be, but that difference has been very consistent across multiple runs of these benchmark tests.

Conclusions

So, what can be taken away from this? Overall, the results are a little inconsistent between each browser engine's implementation, but we can clearly see that the bitwise operator is always either the outright winner or tied for first place in every browser.

However, that's obviously by far the least readable of all of the solutions. Even if a bitwise operation is nearly 2 times faster in Chrome than the more readable ternary operator, we need to think at scale here; the percentage looks impressive, but the actual difference is probably somewhere around 1-2 nanoseconds. There are much higher impact things you could be focusing on instead.

If you somehow find yourself solving a problem where you have thousands of boolean values which all need to be converted to integers in bulk, switching to a bitwise operator might be the right move for you. Otherwise, I wouldn't consider it to be very practical.

That being said, I'm going to keep using it in my side projects and you can't stop me.

Streaming promises in the order they resolve

Ryan Geyer — Fri, 29 Mar 2024 19:05:53 GMT

I have recently been obsessed with the idea of HTML streaming, in particular out-of-order streaming after reading this article on how out-of-order streaming can be done with declarative shadow DOM. I've been working on an experimental templating language/framework/monstrosity in my free time called Tempeh. I would consider the project's current state to be extremely rough and not ready for public consumption, so click that link at your own risk.

However, I wanted to share a cool thing I put together while exploring out-of-order HTML streaming possibilities.

Click here to skip right to the code.

Context

So, let's say I have 3 pieces of lazy content on a page. I have an html template string function which will unwrap promises and stream the html string contents in order as they resolve. An unfortunate limitation of this implementation is that it's order-dependent; the async lazy content at the end of the template literal can only be streamed as fast as the first promise resolves.

return html`
  <div la-z-id="vCz0LY_0">
    Loading...
  </div>
  <div la-z-id="vCz0LY_1">
    Loading...
  </div>
  <div la-z-id="vCz0LY_2">
    Loading...
  </div>
  ${waitFor(500).then(()=>html`
    <la-z id="vCz0LY_0" hidden>
      I'm first, but I'm the slowest!
    </la-z>
  `)}
  ${waitFor(300).then(()=>html`
    <la-z id="vCz0LY_1" hidden>
      I'm second, and I'm in the middle.
    </la-z>
  `)}
  ${waitFor(100).then(()=>html`
    <la-z id="vCz0LY_2" hidden>
      I'm third, but I'm the fastest!
    </la-z>
  `)}
`.arrayBufferStream();

So, we can use streaming to accomplish a cool effect where the static placeholder content can load in immediately, and then we stream in the lazy content as it's ready. Each piece of lazy content is wrapped in a <la-z> web component which, when it mounts on the page, will find its corresponding placeholder element and swap in the final lazy content.

In the scenario above, the first piece of lazy content is the slowest, so it will act as a bottleneck and prevent the other pieces of content from streaming sooner even if their promises have already resolved first. I want a way to stream the resolved values from an array of promises as they resolve, in the order that they resolve! Unfortunately there are not built-in friendly ways to accomplish this; the main methods available for dealing with a group of promises are either Promise.all/Promise.allSettled, which force you to wait for all promises to resolve together and preserves their order, or Promise.race/Promise.any, which can get the value of the first promise in the group which resolves, but nothing aside from that.

So, it's time to build something ourselves! My html template string function can also unwrap iterators, so I decided that should probably be the move.

The implementation

Alright, here's the code:

/**
 * Takes an array of promises and yields the resolved values in the order they resolve.
 * @template TResolveValue
 * @param {Promise<TResolveValue>[]} promises
 */
export async function* unorderedPromiseIterator(promises) {
  const resultStream = new ReadableStream({
    async pull(controller) {
      /** @param {TResolveValue} value */
      const onResolve = (value) => {
        controller.enqueue(value);
      };

      /** @param {unknown} err */
      const onError = (err) => {
        controller.enqueue(
          new Error("unorderedPromiseIterator: An unexpected error occurred.", {
            cause: err,
          })
        );
      };

      for (const promise of promises) {
        promise.then(onResolve, onError);
      }

      await Promise.allSettled(promises);
      controller.close();
    },
  });

  const reader = resultStream.getReader();

  try {
    /** @type {Awaited<ReturnType<typeof reader.read>>} */
    let readResult;
    while (!(readResult = await reader.read()).done) {
      yield readResult.value;
    }
  } finally {
    reader.releaseLock();
  }
}

Excuse the JSDoc annotations, I'm experimenting with being able to use TypeScript without a build step. Although it's a touch clunky, I like it overall!

So obviously there is some real deep cut neo-JavaScript stuff in here. The ReadableStream API and generator functions aren't something that you see super frequently day to day, although they've been around long enough to use comfortably both in Node and the browser. But both are extremely powerful and very fun to work with!

As it turns out, building something like this is pretty hard because generator functions only allow you to yield within the body of the generator function; this means that yielding from a promise.then callback is a no-go, and any obvious implementation ends up falling back into the same trap of having to wait for each promise to resolve in order.

On my first attempt at this, I went through a couple other iterations where I was tracking the index of each unresolved promise, waiting for any of them to resolve with Promise.race, removing that resolved promise from the array, adjusting all of the tracked indices, and then repeating that process until all promises where settled. The code was pretty gnarly and much more inefficient than I think something like this should be, so I kept searching for something better. I finally realized the ReadableStream API was exactly what I was looking for.

ReadableStreams provide us with a way to set up a custom stream which we can fully control the underlying implementation of. This makes it easy for us to simply pass a method to each promise's .then callback which enqueues the resolved value, and then we can close the stream one all promises have settled. Now we can yield each value in a generator-friendly way as they roll in from the stream's reader.

Pretty cool! Here's how it looks in action:

const promises = [
  waitFor(300).then(()=>"first (middle)"),
  waitFor(500).then(()=>"second (slowest)"),
  waitFor(100).then(()=>"third (fastest)"),
];

for await (const value of unorderedPromiseIterator(promises)) {
  console.log(value);
}

// console log:
// "third (fastest)"
// "first (middle)"
// "second (slowest)"

This can then be applied to the html template string example I mentioned above like this:

return html`
  <div la-z-id="vCz0LY_0">
    Loading...
  </div>
  <div la-z-id="vCz0LY_1">
    Loading...
  </div>
  <div la-z-id="vCz0LY_2">
    Loading...
  </div>
  ${unorderedPromiseIterator([
    waitFor(500).then(()=>html`
      <la-z id="vCz0LY_0" hidden>
        I'm first, but I'm the slowest!
      </la-z>
    `),
    waitFor(300).then(()=>html`
      <la-z id="vCz0LY_1" hidden>
        I'm second, and I'm in the middle.
      </la-z>
    `),
    waitFor(100).then(()=>html`
      <la-z id="vCz0LY_2" hidden>
        I'm third, but I'm the fastest!
      </la-z>
    `),
  ])}
`.arrayBufferStream();

The dumb reason why flag emojis aren't working on your site in Chrome on Windows

Ryan Geyer — Wed, 29 Jan 2025 22:10:35 GMT

So, you thought you'd be fancy and use cute little flag emojis in your UI as extra decoration to go along with country/language options. It's perfect; it provides an extra visual cue to help users quickly find the country they're looking for, and it just looks nice.

You can even dynamically derive country flag emojis from region codes with a simple code snippet, super cool!

// The offset to shift the ASCII code of each character in an ISO country code string by
// to derive the equivalent flag emoji for that code.
const EMOJI_CHARACTER_OFFSET = 127397;

const getEmojiForCountryCode = (countryCode: string) =>
  String.fromCodePoint(
    ...countryCode
      .toUpperCase()
      .split('')
      .map((char) => char.charCodeAt(0) + EMOJI_CHARACTER_OFFSET),
  );

// "en-US"
const currentLanguageCode = navigator.language;
// "US"
const currentCountryCode = currentLanguageCode.split("-")[1];
// "🇺🇸"
getEmojiForCountryCode(currentCountryCode);
// "🇫🇷"
getEmojiForCountryCode("FR");
// "🇸🇪"
getEmojiForCountryCode("SE");

Life is good.

...

A bug report comes in.

Some customers are saying the flag emojis are showing up as weird misaligned letters? I can't recreate it on my machine.

Huh?

Maybe they're using an ancient machine or extremely outdated browser which doesn't support rendering emojis?

No. After gathering more information, we find they're using the latest version of Chrome on a Windows machine.

What on earth is happening? Out of desperation I asked ChatGPT. It was useless as usual.

After doing more digging than I feel like I should have needed to, I found my answer: it appears that due to concerns about the fact that acknowledging the existence of certain countries can be perceived as a nominally political stance, Microsoft has opted to just avoid the issue altogether by not including country flag emojis in Windows' system font.

Problem solved! Can you imagine if, *gasp*, your computer could render a Taiwanese 🇹🇼 or Palestinian 🇵🇸 flag? The horror!

This seems like a Big Choice, yet there is very little official documentation acknowledging it, mainly just confused people like me posting on StackOverflow trying to figure out what's going on.

So, what does Windows do with flag emojis then? It just renders the letters of the country's ISO code, usually in an extremely ugly and poorly-aligned manner.

<figure> <img src="/assets/blog/windows-flag-emojis/gb-flag-emojis.png" alt="A graphic showing how the British flag emoji is displayed on different platforms. It is rendered as an icon of the British flag as expected on Android, macOS/iOS, and Firefox on Windows, but is rendered as just the letters 'GB' on Windows."> <figcaption>Source: <cite><a href="https://fullystacked.net/using-emoji-on-the-web/">Using emoji on the web - Fully Stacked</a></cite></figcaption> </figure>

You may have noted from the image above that Firefox on Windows doesn't have this issue. That's because Mozilla stepped up by shipping their own custom flag emojis with Firefox to fill the gap that Windows left.

Why wouldn't Chrome do the same thing?

... We currently have no plan to ship our own emoji font alongside the browser, hence marking as WontFix, works as intended. Alternatively, the website that you're visiting may consider providing an emoji font that has coverage for these flags. <cite>-- Google Employee, May 21, 2021</cite>

Oh. Okay.

I'm of two minds about Google's position here: on the one hand, I respect stubbornly refusing to cover for another corporation's BS which shouldn't be your problem.

However, obviously Firefox was able to do it without too much trouble, and Chrome on Windows represents a massive userbase who is forced to live with the fallout from this decision.

This means a worse experience for developers who have to account for this garbage, and a worse experience for users because rendering flag emojis consistently on all devices now requires JavaScript to detect flag emoji support and/or downloading image/font assets which they shouldn't need in the first place.

What you can do about it

If you absolutely need flag emojis, your two options are:

Replace live emojis with hard-coded image/SVG icons

Using hard-coded images is probably appropriate in cases where your needs are pretty simple, but I feel like it would become a huge pain if you're doing something more dynamic where you won't know exactly which flag icons you'll need until runtime. In this case, I could imagine that using a big SVG spritesheet might work decently well, but I can't find any good existing open source examples of that approach. Adding that to my list of open source projects I could do but probably won't get around to.

Polyfill the flag emojis with a custom font

Adding a custom polyfill font is interesting. The Twemoji font is popular for this (it's what Mozilla uses in Firefox), and you can use the unicode-range CSS property on the font face declaration to only use the subset of the font which covers the flag emojis (although you'll still be on the hook for downloading the entire 1.4MB font file).

@font-face {
  font-family: Twemoji;
  unicode-range: U+1F1E6-1F1FF, U+1F3F4, U+E0062-E0063, U+E0065, U+E0067, U+E006C, U+E006E, U+E0073-E0074, U+E0077, U+E007F;
  src: url("/fonts/twemoji.ttf") format("ttf");
}

:root {
  font-family: Twemoji, "My Main Font";
}

I haven't used it, but this Country Flag Emoji Polyfill library is taking a pretty nicely balanced approach to the problem. It uses JavaScript to detect whether the browser supports country flag emojis, and will only load in the polyfill font if necessary. It also uses a custom subset of the Twemoji font with only the flag emoji characters, significantly reducing the font download size. I wish their code wasn't so reliant on hard-coded CDN urls, but at a minimum it seems like a great starting point if you need something like it.

On that note...

How do you programmatically detect country flag emoji support?

It's dumber than you think: you just draw an emoji on a canvas and use brute force to guess at whether it was rendered correctly.

My approach was to draw an American flag emoji and then look at the pixels to see if any of them contained a non-grayscale color. This works because the Windows fallback emoji is just black/white text, so as long as we test against a flag which isn't supposed to be grayscale, we should be able to tell pretty easily whether it was rendered correctly or not.

export const getDoesBrowserSupportFlagEmojis = (): boolean => {
  const canvas = document.createElement('canvas');
  canvas.height = 1;
  canvas.width = 1;
  const ctx = canvas.getContext('2d');
  if (!ctx) {
    return false;
  }
  ctx.font = `${canvas.height}px sans-serif`;
  const flagEmoji = '🇺🇸';
  ctx.fillText(flagEmoji, 0, canvas.height);
  // Read the canvas pixels and search for any non-grayscale pixels. We used an american flag
  // emoji so there should be some red or blue in there if the browser rendered the flag emoji correctly.
  const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
  for (let i = 0; i < imageData.length; i += 4) {
    if (imageData[i + 3] === 0) {
      // Skip transparent pixels
      continue;
    }
    if (imageData[i] !== imageData[i + 1] || imageData[i] !== imageData[i + 2]) {
      // A pixel is grayscale if all three color channels are the same. If any pixel is not grayscale, that means the browser
      // rendered the flag emoji image instead of the fallback text, so we can return true.
      return true;
    }
  }

  return false;
};

In the project I was working on where we encountered this issue, we decided to not bother with fallbacks and just hide the emoji altogether if we detect that the browser doesn't support it. It's disappointing but it's fine.

I think the biggest lesson here is that you should never make flag emojis an integral part of your site's design, or you will suffer. In an ideal world, this would be fixed someday, but it's been years with no movement so I'm not holding my breath. Thanks, Microsoft! 🇹🇼

What's new in hover-video-player v1.3.0

Ryan Geyer — Thu, 18 Jul 2024 15:43:28 GMT

hover-video-player v1.3.0 is out! This is an exciting one as it finally resolves one of the most common requests I get on both this project and react-hover-video-player: "how do I use a YouTube video/Vimeo video/m3u8 stream?"

The answer has long been, "sorry, you can't." The hover-video-player component is built entirely on native HTMLVideoElement APIs, and I am not going to do custom work just to accomodate some other service's proprietary API (or in the case of m3u8, add an entire extra library just to support one media type).

Then I stumbled upon Mux's excellent media-elements, a collection of custom element libraries which provide HTMLMediaElement-compatible APIs for tons of different media sources, including basically every one I've ever been asked about. This set off a light bulb: in theory, if these custom elements implement all of the media element APIs which hover-video-player relies on, they could probably be used in place of a video element.

This required a small amount of additional work to support due to a handful of things relying on the assumption that we're always working with a <video>, but it wasn't too bad. And it works!

I will note that this feature isn't flawless; these custom elements do their best, but they usually don't perfectly mimick all of an HTMLVideoElement's behavior, and some of hover-video-player's APIs will most likely have weird interactions as a result. That's a price I'm willing to pay though; just supporting these alternative media sources at all is a big win which should hopefully help give people more options.

Here's an example of how it works:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/youtube-video-element@1"
></script>

<hover-video-player>
  <youtube-video
    src="https://www.youtube.com/watch?v=aqz-KE-bpKQ"
    playsinline
    muted
  ></youtube-video>
</hover-video-player>

As mentioned earlier, this feature gets requested heavily for my react-hover-video-player library as well, but React is very unfriendly when it comes to composing/controlling child elements like this. I think it could be done, but certainly not very elegantly. Since React has finally started coming around on web component support, I think I will plan to just direct people toward hover-video-player for now, but I'll keep thinking about it.

Happy hovering!

Using (almost) pure CSS to make fancy scroll-driven image sequence animations

Ryan Geyer — Thu, 05 Dec 2024 22:39:46 GMT

We've all seen it. Some new Apple product gets announced and you go to the product page to check it out. As you scroll, you get blasted in the face by a flashy highly-complex scroll-driven animation. Apple isn't the only company that uses this effect, but they really love it in particular. I was able to find one on their site in under a minute on the AirPods Pro 2 page:

<figure> <video src="/assets/blog/css-image-sequence-animations/airpods-product-page-example.mp4" muted autoplay loop></video> <figcaption> A screen recording showing an animation of a pair of AirPods twisting and flying out towards the screen as you scroll. </figcaption> </figure>

If you're a web dev like me, you've probably wondered how that effect works at least once. Maybe you've looked it up and were slightly underwhelmed like I was to discover that it's all pretty much smoke and mirrors; these effects are usually just a pre-baked video split into individual images for each frame, and then JavaScript checks your scroll position to determine which frame to show, usually by rendering to a canvas.

The most disappointing part of this is the performance implications: anyone who knows a thing or two about video compression will be able to tell you that the file size difference between a nice 5-second mp4 file and dozens of individual PNGs is eye-popping to say the least.

My partner Jess recently had me make some updates to their site including, you guessed it, adding a scroll-driven image sequence animation to the homepage. I was excited to finally have a chance to take a crack at this effect, and I think it turned out great!

<figure> <video src="/assets/blog/css-image-sequence-animations/jess-cb-phone-img-seq-demo.mp4" muted autoplay loop></video> <figcaption> A screen recording of my partner Jess' updated website, showing an animation of a phone with the Crate and Barrel app on it twisting as you scroll. </figcaption> </figure>

I said the magic behind how these image sequence animations work seemed a little underwhelming, but actually trying to implement it myself was an interesting challenge and I learned a ton as I continued to refine it and improve its performance. After a lot of experimenting, I have ended up landing on an implementation which I haven't really seen anyone else try before that is faster, more effecient, and can be implemented in almost pure CSS. I'm pretty excited to share it!

Image sequences, the Apple way

First, let's talk about how most sites implement this effect. Pretty much every implementation I've seen, including the Airpods one shown above, take a fairly brute force approach:

Preload every single individual frame image file you can up front, showing some loading state or placeholder in the meantime.
Once the images are loaded, start watching for scroll events. As the scroll position changes, calculate which frame of the animation should be shown for that position and render that image to a canvas.

This definitely works! But in my opinion, it's flawed.

Loading 65 individual image files at the same time is not great for performance.

I was shocked to discover that the Airpods animation is comprised of 65 PNGs weighing in at a total of 15.2MB. That's so much data! If they converted the frames to a more efficient format like WebP, that alone could bring the total weight down to 1.7MB, a massive nearly 90% reduction. However, there are still additional issues with this approach to consider.

On top of download size, if you're serving the image assets over HTTP/1, browsers will be limited to a maximum number of requests they can run in parallel, meaning you are all but guaranteed to run into a bottleneck that will cause the frames to take much longer to download and may start impacting how other parts of the site load as well.

Apple serves their images over HTTP/2 so that is less of a concern, but I have seen this mistake happen in the wild. I once saw a site where even on a fiber internet connection, you would still get stuck with a loading progress bar where you had to wait for maybe 30+ seconds before being able to interact with the site at all, just so they could have a fancy scroll-driven image sequence animation. There is no world where that is worth the wait, no matter how cool the animation is, never ever ever. Completely unacceptable.

Finally, my last point of contention is that all of this relies on quite a bit of JavaScript to manage loading the images, tracking your scroll position and calculating the current frame to display, and rendering that frame to a canvas. JavaScript comes with added potential points of failure and is much more expensive per byte than HTML or CSS due to added overhead required for parsing and execution. JavaScript can't always be avoided, but I'd love to avoid relying on it as much as possible!

I did observe that Apple uses one optimization technique worth noting: if you apply network throttling in your dev tools, the page still takes way too long to load in my opinion, but you'll be able to see that they try to prioritize loading frames at major checkpoints in the animation first so they can start serving a degraded version of the animation as soon as possible. For instance, you can see that they prioritize loading the first frame, then the last frame, then the frame at 50%, then at 25% and 75%, and so on, slowly increasing the resolution so that you can start playing an extremely choppy and kinda ugly but still functional version of the animation sooner while you wait for the rest of the frames to come in.

What if we used spritesheets?

I studied game development in college where spritesheets are a very common concept, but for those unfamiliar, a spritesheet is an asset optimization technique commonly used in game development for 2D games where you pack a bunch of images into a single big image file that can be loaded all at once.

<figure> <img src="/assets/blog/css-image-sequence-animations/airpods-spritesheet.webp" alt="The frames from the Airpods Pro animation shown above packed into a spritesheet." class="shadow-2" /> <figcaption>The frames from the Airpods Pro animation shown above packed into a spritesheet. Note that this asset has been scaled down so its file size is not representative.</figcaption> </figure>

Spritesheets have a few notable benefits for our purposes.

First, when you pack multiple images into one, the final image will usually be able to be compressed a little smaller than the total combined size of the individual files. In the case of the Airpods Pro animation, converting each frame to WebP resulted in a total combined size of 1.7MB, but packing all of those into a WebP spritesheet image brings the size down further to 1.5MB. That's a relatively modest 10% improvement, but still significant especially at scale.

Second, we're able to load all of the frames for the animation in a single network request, so concerns about HTTP/1 request bottlenecks are significantly lessened. Being a single image also means you could even add a preload <link> tag to the <head> to get things loading as soon as possible.

Playing through a spritesheet with CSS

Using a spritesheet means we can use some tricks to play through the animation with almost pure CSS. This only requires two elements: an <img> tag with the spritesheet loaded, and a wrapper element with overflow: clip which will serve as a window into the current frame we want to display from the spritesheet animation. At that point, all we have to do is shift the <img>'s position around so the current desired frame is visible in the parent's window, and we have a little animation going!

Here's the HTML and CSS for my implementation:

<!-- It's important that an aspect-ratio is defined on the img-sequence element which matches the
      exact aspect ratio of one cell in the spritesheet grid. -->
<img-sequence style="--sprite-count: 65; --column-count: 11; --row-count: 6; aspect-ratio: 1440/810">
  <img src="/img/my-spritesheet.webp" alt="" fetchpriority="high" class="spritesheet">
</img-sequence>
<style>
  img-sequence {
    /* The wrapper img-sequence tag will serve as a window into a single frame of the spritesheet,
        so we need the child <img> tag to be able to be absolutely positioned relative to this tag
        and to clip any overflow. */
    position: relative;
    overflow: clip;
    display: block;
  }

  img-sequence .spritesheet {
    display: block;

    position: absolute;
    top: 0;
    left: 0;
    /* Size the spritesheet so a single cell fits in the dimensions of the parent element */
    width: calc(100% * var(--column-count));
    height: calc(100% * var(--row-count));

    /* Progress in the animation is driven by a --progress CSS variable
       which should be a number from 0-1.
       We will use that to calculate the index of the current cell in the spritesheet grid
       which best matches that percentage of the way into the animation. */
    --cell: round(
      clamp(0, var(--progress), 1) * (var(--sprite-count) - 1) + 1,
      1
    );
    /* Now we can derive the row and column numbers for the current cell in the spritesheet grid. */
    --row: round(up, calc(var(--cell) / var(--column-count)), 1);
    --column: calc(var(--cell) - (var(--row) - 1) * var(--column-count));

    /* Translate the image to the appropriate position to display the current row and column inside the
        bounds of the parent img-sequence element.
        Using translate3d for hardware acceleration. */
    transform: translate3d(
      calc(-100% * (var(--column, 1) - 1) / var(--column-count, 1)),
      calc((var(--row, 1) - 1) * -100% / var(--row-count, 1)),
      0
    );
  }
</style>

All we need to do at this point is set a --progress variable on the <img-sequence> element and it will shift the image around to show the correct frame which is that percent of the way into the animation. I am currently using some JavaScript to calculate the scroll percentage which drives this progress value, so that is where my (almost) caveat in the title comes in.

Here's a rough example of how you would make the animation play with JavaScript:

window.addEventListener("scroll", () => {
  // Play through the animation from start to finish as the
  // user scrolls down by half of the window's height
  const progress = window.scrollY / (window.innerHeight / 2);
  imageSequence.style.setProperty("--progress", String(progress));
}, {
  // Don't forget to make your scroll listeners passive!
  passive: true
});

However, in the near future it should theoretically be possible to make this work with pure CSS using @property and scroll timelines! There is a polyfill for scroll timelines which I attempted to use, but I was fighting with too many major inconsistencies in behavior between the real version running in Chrome and the polyfilled version running in Firefox and Safari. I'm going to wait for things to get a little more baked before I try that again.

Regardless, here's a potential vision for how the image sequence could be played with a scroll timeline:

/* Register --progress variable's type as a number so
   the browser knows how to transition the value */
@property --progress {
  syntax: "<number>";
  inherits: true;
  initial-value: 0;
}

/* The scroll timeline will play through this
   animation to transition progress from 0 to 1 */
@keyframes imgSequenceProgress {
  from {
    --progress: 0;
  }

  to {
    --progress: 1;
  }
}

img-sequence {
  animation-name: imgSequenceProgress;
  animation-duration: 1ms;
  animation-direction: alternate;
  /* Play through the animation based on the
     scroll position of the element */
  animation-timeline: scroll(block nearest);
}

Isn't that awesome? CSS is awesome.

I will always relish an opportunity to keep my reliance on JavaScript to a minimum. I expect this approach will also provide some significant low-level performance benefits in terms of both memory usage and CPU usage compared to rendering to a canvas, but I haven't spent enough time profiling to be able to confidently speak to that.

Downsides

Like everything, this approach still has tradeoffs worth acknowledging.

First, it relies heavily on the round() CSS function, which has okay but not great browser support as of writing this. However, it is in all major modern browsers, and the progressive enhancement story isn't terrible; if a browser doesn't support round(), the animation will just be stuck on the first frame as if it were a static image.

The bigger flaw is that this simple implementation does not provide a good experience while you wait for the spritesheet image to load, and a 1.5MB image is definitely going to take some time to load for a lot of people. The one upside of using individual frames is that you can load and display the first frame a lot quicker while you wait for the rest to come in, but with a spritesheet, it's all or nothing.

I ended up writing a simple img-sequence web component which is initially hidden and fades in once the spritesheet image finishes loading in an attempt to smooth things out a little bit, but it still leaves me wanting. I could probably adjust the component further to display a small placeholder frame while we wait for the larger spritesheet to finish loading, but it hasn't felt necessary yet thankfully.

Overall, even with these downsides, I am still extremely pleased with how well this works and would highly recommend it to others. CSS is becoming extremely powerful, and it feels like this is only just beginning!

Addenda

Some additional content which I couldn't find room for in the main article, but still wanted to touch on.

A1: Spritesheet asset prep tips and tools

I've learned a lot in the process of building and continuing to refine this project, so I wanted to share some of the tips I've come up with and helpful scripts I've written along the way.

You may not need as many frames as you think

This was a game-changing realization for me. Jess' animation was initially delivered to me as 127 frames; they had just exported a 4.2-second-long clip at 30fps, which seems like a natural thing to do. However, it's important to remember that when an animation is scroll-driven, it's not going to play the same way.

I'm going to drop a classic programmer "it depends™" here, because every animation is probably going to need a slightly different treatment.

How small/subtle are the movements in your animation?

The less movement there is between each individual frame, the more frames you can probably afford to cut down.

Consider your pixel:frame ratio.

For Jess' site, we wanted the animation to play over the course of scrolling a very small distance; I ended up measuring it to be from 0 to approximately 140 pixels down the page. Nobody can scroll less than one pixel at a time, and I would argue almost nobody is going to painstakingly scroll down your page one single pixel at a time. In my opinion, if you have more than one frame for every 2 pixels of scrollable area, you have too many frames.

I found that cutting the frame count down by half from 127 to 64 still felt just as smooth as before, but with obviously massive improvements in file size.

I probably could have gone even further; the AirPods product page I've been referencing is way more aggressive than I would ever dare, as they're stretching 65 frames over a whopping 1200 pixels for a ~18.5 pixel:frame ratio. When I pay attention, especially when scrolling slowly, I can see the jitter, but it's not as bad as I would have thought.

Trimming white space around frames

Every frame image that I received had some extra transparent padding around it. WebP is good at compressing these blank pixels so that they had basically no effect on file size, but it did make it difficult for me to position the image sequence exactly how I wanted on the page.

I ended up writing a script which takes the path to a directory of frame images and uses sharp to loop over every image, determine the closest dimensions you can crop in to without cutting off content on any frame, and then applies that crop.

Image cropping script source

Building the spritesheet

I also wrote a script which takes the path to a directory of frame images and uses sharp to resize and pack them into a single WebP spritesheet image file. It also outputs a helpful metadata file containing all of the relevant information which is needed to make the animation work.

Spritesheet generation script source

My `<scroll-progress-region>` web component

I glossed over how I'm tracking scroll position. I created a <scroll-progress-region> web component which tracks its scroll position on the page and provides a --scroll-pct CSS variable which its children can use. This is awesome because I'm then able to stay in CSS land to translate that --scroll-pct into my image sequence's --progress variable.

I spent a decent amount of time toying around and doing math to figure out the exact formula I wanted for that translation, this is where it ended up:

--progress: calc((var(--scroll-pct) * -1.05) + 1.05);

<scroll-progress-region> component source

My `<img-sequence>` WebC component

Jess' site is written using 11ty and WebC, so I wrote an img-sequence WebC component which takes the path to a spritesheet file, loads everything in, and writes the HTML for the image sequence exactly how I need it.

<img-sequence @spritesheet="src/assets/path/to/spritesheet.webp"></img-sequence>

<!-- output -->
<img-sequence style="--spritesheet-url: url('/img/jTOLRJLwjR-16128.webp'); --sprite-count: 64; --column-count: 63; --row-count: 2; aspect-ratio: 256/510">
  <img
    src="/img/jTOLRJLwjR-16128.webp"
    alt=""
    fetchpriority="high"
    class="spritesheet"
  >
</img-sequence>

WebC is pretty niche, but this may still serve as a good example that you can transfer to whatever your site is built with!

WebC <img-sequence> component source

A2: So... why can't you use video files again?

I glossed over this question earlier, but I wanted to spend a little more time talking through why image sequences are the de-facto way to implement these animations for any curious enough. It definitely wasn't immediately obvious to me at first!

All of this image stuff seems like a lot of effort, and if serving an MP4 file would be so much more efficient than a bunch of individual image frames, why not do that?

From my research, it seems the answer is that you technically can use video. The simplest implementation of this would be something like:

window.addEventListener("scroll", () => {
  // Sets the video's time to a percent of the duration relative
  // to the percent of the window height that the user has scrolled
  video.currentTime = video.duration * window.scrollY / window.innerHeight
}, { passive: true })

This will work... okay. However, there are some tradeoffs to this approach worth considering:

1. Transparency

Let's get the big one out of the way first: the most common and well-supported video format, h.264/mp4, doesn't support transparency. That's a pretty common requirement for these types of effects, so that alone may be a showstopper.

More modern formats like WebM and the h.265 codec do support transparency, and browser support for those formats appears to be pretty good at this point, but this article covering how to wrangle all of the browsers into supporting video transparency does not make me feel good.

2. Rapidly scrubbing back and forth through a video is not the best way to use it

DISCLAIMER: I am not a video encoding expert and will probably get specifics wrong on this point. But I think I'm mostly right here.

This is an over-simplification, but video codecs like h.264 use techniques to save space by only encoding data describing the changes between each frame instead of having to encode the full image of every individual frame. This is great because it means you can skip encoding a lot of redundant information, and it's still extremely fast to render during forward playback because advancing to the next frame is as simple as applying that frame's changes to the current frame that you already have loaded.

However, now let's imagine that you're not performing forward playback. If you drop into a random point in the video, you now have to go back and look at the previous frames leading up to the current one to construct what the current frame should look like. That's a lot more work!

This means that although rapidly scrubbing through a video's timeline may work, the user's device is going to be putting in a ton more work decoding frames from scratch up to 60 times per second as the user scrolls.

I haven't done enough profiling to confidently say that this is a significant issue, but it's something that I do think is worth considering.

Statically-Typed Scoped Data Attributes with Vanilla Extract and React

Ryan Geyer — Sat, 05 Aug 2023 05:17:36 GMT

Over the last 2 years or so, Waymark has been undergoing an effort to convert our frontend codebase to TypeScript. We have a LOT of code and a fairly small team, so it's been a gradual process, but we've already seen huge benefits for developer experience.

In the process, we have also begun shifting our styles from runtime CSS-in-JS to using Vanilla Extract, a very cool library which allows you to write type-safe and scoped CSS in TypeScript that is then converted to static CSS files at build time. Because the styles are written in TypeScript, this gives us flexibility to dynamically generate CSS, the biggest benefit of runtime CSS-in-JS, but without the performance hit at runtime!

In many places in our codebase, we like to represent state in our HTML using data attributes. Here's what an example might look like:

// MyComponent.tsx

type Status = "init" | "loading" | "success" | "error";

export default function MyComponent(){
  const [status, setStatus] = useState<Status>("init");

  /* Imagine there's some code here which does something and updates `status` */

  return (
    <div data-status={status}>
      {status}
    </div>
  );
}

/* MyComponent.css */
[data-status="init"], [data-status="loading"] {
  color: gray;
}

[data-status="success"] {
  color: green;
}

[data-status="error"] {
  color: red;
}

This has a few benefits:

It's a great way to expose internal component state details for unit tests!
Data attributes can make it easier to see what's going on in your HTML at a glance when debugging, and it's also very easy to just manually edit the attribute's value in your dev tools if you need to manually see what a different state looks like.
Representing different possible state values on a single attribute tends to feel cleaner than having to manage multiple unique class names for each possible state value and making sure only one is applied at a time.

However, this approach can come with some downsides:

There are certain data attribute names which you will probably want to reach for a lot, and they can very easily collide if they aren't scoped properly. For instance, the data-status attribute used in the example above may end up being a very common attribute name that you want to use in multiple different components. This will probably mostly be fine, but the more components that use that attribute name, the more you are opening yourself up to the possibility that one element with a data-status attribute may end up getting wrapped by another element with a data-status attribute and then you may start experiencing some strange unexpected interactions.
By default, attribute names and values are not type-safe. If you misspell an attribute name or value in your HTML or CSS, or if something gets renamed, there's very little protection to prevent that bug from sneaking by unnoticed! Of course, this is just a typical risk you are usually taking on when working with HTML and CSS, but we're writing everything in TypeScript so it feels like we should be able to do better!

So, this leads me to the neat little makeDataAttribute util function that I created to solve both of these problems. It allows us to make data attributes both type-safe AND scoped to the components that they're used in!

How it works

The makeDataAttribute function takes the attribute name as a param and a generic type representing acceptable values for the attribute. It returns a callback which we can then use to apply the data attribute in our styles and components.

const dataStatus = makeDataAtribute<"init" | "loading" | "success" | "error">("data-status");

The returned callback takes an attribute value and returns an object with a scoped version of the attribute name as a key and the provided attribute value as the value. The returned object can be spread in JSX to apply the attribute to an element.

Note that the attribute name will get a small unique hash appended to the end to make sure it doesn't collide with other attribute names.

// { data-status-asf12: 'init' }
console.log({ ...dataStatus("init") });

This object also has a custom toString() method defined on its prototype so that when the object is used as a string, it will be formatted as a valid CSS selector for the attribute + value combo.

// [data-status-asf12="loading"]
console.log(`${dataStatus("loading")}`);

Here's what it all looks like in action:

// MyComponent.css.ts

import { style } from '@vanilla-extract/css';
import { makeDataAttribute } from '@libs/shared-ui-styles';

import type { Status } from './MyComponent';

export const dataStatus = makeDataAttribute<Status>("data-status");

export const myComponent = style({
  selectors: {
    [`&:is(${dataStatus("init")}, ${dataStatus("loading")})`]: {
      color: "gray",
    },
    [`&${dataStatus("success")}`]: {
      color: "green",
    },
    [`&${dataStatus("error")}`]: {
      color: "red",
    },
  },
});

// MyComponent.tsx

import { myComponent, dataStatus } from './MyComponent.css';

export type Status = "init" | "loading" | "success" | "error";

export default function MyComponent() {
  const [status, setStatus] = useState<Status>("init");

  /* Insert code that does something to update the status here */

  return (
    <div className={myComponent} {...dataStatus(status)}>
      {status}
    </div>
  );
}

And here's what the HTML and CSS output from this will look like:

<div className="qsr7lu14" data-status-asf12="init">
  init
</div>

.qsr7lu14:is([data-status-asf12="init"], [data-status-asf12="loading"]) {
  color: gray;
}

.qsr7lu14[data-status-asf12="success"] {
  color: green;
}

.qsr7lu14[data-status-asf12="error"] {
  color: red;
}

I will admit that this API is not perfect; it doesn't feel perfectly intuitive to me without requiring some explanation, and the fact that there is a meaningful difference between whether you are using the attribute as a string for a selector or as an object to spread on an element in JSX doesn't feel amazing. I certainly wouldn't reach for something like this in a smaller project, but in a big complex app like Waymark, I think the benefits from this approach do still outweigh the downsides.

The code

Now that I've showcased what it is and how it works, let's dig into the code!

Note: if you have ideas for how to improve this further let me know. Even better, if want to publish this as an open source library, be my guest!

import { addFunctionSerializer } from '@vanilla-extract/css/functionSerializer';

export function makeDataAttribute<TAttrValue extends string | number | boolean = never>(
  name: string,
) {
  // Add a random 5-digit string to the end of the attribute name to avoid collisions
  const scopedName = `${name}-${Math.random().toString(36).substring(2, 7)}`;

  const dataAttributeValueGetter = _dataAttribute<TAttrValue>(scopedName);

  // Use Vanilla Extract's magical addFunctionSerializer so we can guarantee that
  // the scoped data attribute value getter callback we're creating here
  // is able to be exported from a Vanilla Extract .css.ts file
  // in a way that can be used at runtime
  addFunctionSerializer(dataAttributeValueGetter, {
    importName: '_dataAttribute',
    importPath: 'absolute-import-path/to-this-file',
    args: [[scopedName]],
  });

  return dataAttributeValueGetter;
}

export function _dataAttribute<TAttrValue extends string | number | boolean>(
  attributeName: string,
) {
  const getDataAttributeValue = (attributeValue: TAttrValue): {
    [key: string]: `${TAttrValue}`;
  } => Object.create(Object.prototype, {
    [attributeName]: {
      value: `${attributeValue}`,
      enumerable: true,
    },
    // Custom toString method to return a string representing the data attribute as a CSS selector
    toString: {
      value: () => `[${attributeName}="${attributeValue}"]`,
    },
  });

  // Add an `attributeName` property to the function so we can access it at runtime;
  // this will mainly be useful for debugging/testing purposes
  Object.defineProperty(getDataAttributeValue, 'attributeName', {
    value: attributeName,
  });

  return getDataAttributeValue as typeof getDataAttributeValue & {
    attributeName: string;
  };
}

Okay, there is a lot packed in here! Let's break it down.

First, we should discuss what exactly Vanilla Extract's addFunctionSerializer method is, as that is what makes all of this possible.

addFunctionSerializer is a special utility function which is intended only for extremely advanced use cases which usually only matter to library authors. That's how you know you're doing something fun!

Because Vanilla Extract is compiled down to CSS at build time, it will normally strip away any functions defined in your .css.ts files. This means that you can't normally export a function from a .css.ts file and import it into a different file that would use it at runtime, because Vanilla Extract doesn't know how to serialize that function. However, you may be able to see where this is going... addFunctionSerializer enables you to help tell Vanilla Extract both that a function should be serialized and exactly how to serialize it so that it can be used at runtime!

So, to wrap our heads around what's going on here, we need to understand that the contents of the makeDataAttribute method in this file will only ever be run at Vanilla Extract's build-time when generating CSS. So, we need to define and export a second _dataAttribute function which represents the code that we want to be able to be executed at both build-time AND runtime, and then use addFunctionSerializer to point Vanilla Extract in the right direction on how to serialize the callback returned by makeDataAttribute.

Let's focus on _dataAttribute first.

export function _dataAttribute<TAttrValue extends string | number | boolean>(
  attributeName: string,
) {
  const getDataAttributeValue = (attributeValue: TAttrValue): {
    [key: string]: `${TAttrValue}`;
  } => Object.create(Object.prototype, {
    [attributeName]: {
      value: `${attributeValue}`,
      enumerable: true,
    },
    // Custom toString method to return a string representing the data attribute as a CSS selector
    toString: {
      value: () => `[${attributeName}="${attributeValue}"]`,
    },
  });

  // Add an `attributeName` property to the function so we can access it at runtime;
  // this will mainly be useful for debugging/testing purposes
  Object.defineProperty(getDataAttributeValue, 'attributeName', {
    value: attributeName,
  });

  return getDataAttributeValue as typeof getDataAttributeValue & {
    attributeName: string;
  };
}

So, the main thing this function does is create a getDataAttributeValue callback which takes an attribute value and returns an object that we can use to apply the attribute in our style and component code.

You don't see Object.create() a whole lot these days, but I opted for that as it provides a good way to be able to control exactly which properties on the object should be enumerable or not. This is important because we want to be able to spread the object on a JSX element's props without including unwanted junk like our custom toString() method.

Alright, now let's tackle makeDataAttribute.

const scopedName = `${name}-${Math.random().toString(36).substring(2, 7)}`;

First, we are simply taking the provided data attribute name and appending a random 5-character string to the end to make it unique. This is just using the classic quick and dirty trick of converting a random number to a base-36 string, as this tends to produce pretty decent short unique ID strings.

Now for the weird part.

const dataAttributeValueGetter = _dataAttribute<TAttrValue>(scopedName);

// Use Vanilla Extract's magical addFunctionSerializer so we can guarantee that
// the scoped data attribute value getter callback we're creating here
// is able to be exported from a Vanilla Extract .css.ts file
// in a way that can be used at runtime
addFunctionSerializer(dataAttributeValueGetter, {
  importName: '_dataAttribute',
  importPath: 'absolute-import-path/to-this-file',
  args: [[scopedName]],
});

return dataAttributeValueGetter;

So, ultimately we want makeDataAttribute to return the callback which _dataAttribute creates. In order to make sure this returned callback works at runtime, we'll then pass it to addFunctionSerializer along with the name and path where Vanilla Extract can import the function that created it, as well as any arguments that said function was called with. Given this information, Vanilla Extract should be able to serialize the callback so we can use it wherever we want!

Conclusions

Alright, so I'll admit it: this was a lot of complexity and effort for a relatively small win, and even then the final result still has tradeoffs.

That being said, I think this new util has made a postive impact in allowing us to write styles with more confidence, and this was a great exercise for helping build my mental model of how Vanilla Extract works, which has been very helpful as we have continued integrating it into our codebase.

And of course, most importantly of all, this was a ton of fun to build! I loved taking on the challenge of trying to design an API for how type-safe data attributes could even work, and even though I'm not 100% confident that this is the absolute perfect solution, I'm still pretty happy with how it came out.

Ryan Geyer’s Blog

I finally found a use for ChatGPT: Workout routines

My Garden In Review 2025

Native Plants

What I planted this year

Bugs

Rain Barrels!

Vegetables

Wrapping Up

A simple way to programmatically detect support for cascade layers

How Waymark finds all of the image elements on your website

1. The simplest approach

2. BRUTE FORCE

3. Figure out where the images are and go there directly

Reflecting on hover-video-player v1.2

The changes

What I learned

Micro-optimizing boolean-to-int conversions for... fun?

The setup

The results

Negation

Conclusions

Streaming promises in the order they resolve

Context

The implementation

The dumb reason why flag emojis aren't working on your site in Chrome on Windows

A bug report comes in.

What you can do about it

Replace live emojis with hard-coded image/SVG icons

Polyfill the flag emojis with a custom font

How do you programmatically detect country flag emoji support?

What's new in hover-video-player v1.3.0

Using (almost) pure CSS to make fancy scroll-driven image sequence animations

Image sequences, the Apple way

Loading 65 individual image files at the same time is not great for performance.

What if we used spritesheets?

Playing through a spritesheet with CSS

Downsides

Addenda

A1: Spritesheet asset prep tips and tools

You may not need as many frames as you think

How small/subtle are the movements in your animation?

Consider your pixel:frame ratio.

Trimming white space around frames

Building the spritesheet

My <scroll-progress-region> web component

My <img-sequence> WebC component

A2: So... why can't you use video files again?

1. Transparency

2. Rapidly scrubbing back and forth through a video is not the best way to use it

Statically-Typed Scoped Data Attributes with Vanilla Extract and React

How it works

The code

Conclusions

My `<scroll-progress-region>` web component

My `<img-sequence>` WebC component