# Where it all started

I had the original idea for “projections” way back in 2019. Inspired by OS X’s Dashboard Widgets and Adobe AIR, I’d begun to wonder if it might be possible to project a component from a website into those kinds of surfaces. Rather than building a bespoke widget that connected to an API, I thought it made sense to leverage an installed PWA to manage those “projections.” I shared the idea at TPAC that year and got some interest from a broad range of folks, but didn’t have much time to work on the details until a few years later.

In the intervening time, I kept working through the concept in my head. I mean in an ideal world, the widget would just be a responsive web page, right? But if that were the case, what happens when every widget loads the entirety of React to render their stock ticker? That seemed like a performance nightmare.

In my gut, I felt like the right way to build things would be to have a standard library of widget templates and to enable devs to flow data into them via a Service Worker. Alex Russell suggested I model the APIs on how Notifications are handled (since they serve a similar function) and I was off to the races.

I drafted a substantial proposal for my vision of how PWA widgets should work. Key aspects included:

• A declarative way to define and configure a widget from within the Web App Manifest;
• A progressively enhanced pathway for devs to design a widget that adapts to its host environment, from using predefined templates to using custom templates to full-blown web-based widgets (with rendering akin to an iframe);
• A collection of recommended stock templates that implementors should offer to support most widget types;
• Extensibility to support custom templates using any of a variety of templating languages; and
• A complete suite of tools for managing widgets and any associated business logic within a Service Worker.

# Widgets became a reality

After continuing to gently push on this idea with colleagues across Microsoft (and beyond), I discovered that the Windows 11 team was looking to open up the new Widget Dashboard to third-party applications. I saw this as an opportunity to turn my idea into a reality. After working my way into the conversation, I made a solid case for why PWAs needed to be a part of that story and… it worked! (It no doubt helped that companies including Meta, Twitter, and Hulu were all invested in PWA as a means of delivering apps for Windows.)

While the timeline for implementation didn’t allow us to tackle the entirety of my proposal, we did carve out the pieces that made for a compelling MVP. This allowed us to show what’s possible, see how folks use it, and plan for future investment in the space.

Sadly, it meant tabling two features I really loved:

• Stock/predefined templates. A library of lightly theme-able, consistent, cross-platform templates based on common data structures (e.g., RSS/Atom, iCal) would make it incredibly simple for devs to build a widget. If implemented well, devs might not even need to write a single line of business logic in their Service Worker as the browser could pick up all of the configuration details from the Manifest.
• Configurable widget instances. Instead of singleton widgets, these would allow you to define a single widget type and replicate it for different use cases. For example, a widget to follow a social media user’s profile could be defined once and the individual instances could be configured with the specific account to be followed.

I’m sincerely hopeful these two features eventually make their way to us as I think they truly unlock the power of the widget platform. Perhaps, with enough uptake on the current implementation, we can revisit these in the not-too-distant future.

To test things out, I decided to build two widgets for this site:

1. Latest posts
2. Latest links

Both are largely the same in terms of their setup: They display a list of linked titles from this site.

# Designing my widget templates

Given that they were going to be largely identical, I made a single “feed” template for use in both widgets. The templating tech I used is called Adaptive Cards, which is what Windows 11 uses for rendering.

Adaptive Card templates are relatively straightforward JSON:

{“type”:“AdaptiveCard”,“$schema”:“http://adaptivecards.io/schemas/adaptive-card.json”,“version”:“1.6”,“body”: [{“$data”:“${take(items,5)}”,“type”:“Container”,“items”: [{“type”:“TextBlock”,“text”:“[${title}](${url})”,“wrap”:true,“weight”:“Bolder”,“spacing”:“Padding”,“height”:“stretch”}],“height”:“stretch”}],“backgroundImage”: {“url”:“https://www.aaron-gustafson.com/i/background-logo.png”,“verticalAlignment”:“Bottom”,“horizontalAlignment”:“Center”}}

What this structure does is:

1. Create a container into which I will place the content;
2. Extract the first five items from the data being fed into the template (more on that in a moment);
3. Loop through each item and
   • create a text block,
   • populate its content with Markdown to generate a linked title (using the title and url keys from the item object)
   • Set some basic styles to make the text bold, separate the titles a little and make them grow to fill the container; then, finally
4. Set a background on the widget.

The way Adaptive Cards work is that they flow JSON data into a template and render that. The variable names in the template map directly to the incoming data structure, so are totally up to you to define. As these particular widgets are feed-driven and this site already supports JSONFeed, I set up the widgets to flow the appropriate feed into each and used the keys that were already there. For reference, here’s a sample JSONFeed item:

{“id”:“…”,“title”:“…”,“summary”:“…”,“content_html”:“…”,“url”:“…”,“tags”:[],“date_published”:“…”}

If you want to tinker with Adaptive Cards and make your own, you can do so with their Designer tool.

# Defining the widgets in the Manifest

With a basic template created, the next step was to set up the two widgets in my Manifest. As they both function largely the same, I’ll just focus on the definition for one of them.

First off, defining widgets in the Manifest is done via the widgets member, which is an array (much like icons and shortcuts). Each widget is represented as an object in that array. Here is the definition for the “latest posts” widget:

{“name”:“Latest Posts”,“short_name”:“Posts”,“tag”:“feed-posts”,“description”:“The latest posts from Aaron Gustafson’s blog”,“template”:“feed”,“ms_ac_template”:“/w/feed.ac.json”,“data”:“/feeds/latest-posts.json”,“type”:“application/json”,“auth”:false,“update”:21600,“icons”:[{“src”:“/i/icons/webicon-rss.png”,“type”:“image/png”,“sizes”:“120x120”}],“screenshots”:[{“src”:“/i/screenshots/widget-posts.png”,“sizes”:“387x387”,“label”:“The latest posts widget”}]}

Breaking this down:

1. name and short_name act much like these keys in the root of the Manifest as well as in shortcuts: The name value is used as the name for the widget unless there’s not enough room, in which case short_name is used.
2. You can think of tag as analogous to class in HTML sense. It’s a way of labeling a widget so you can easily reference it later. Each widget instance will have a unique id created by the widget service, but that instance (or all instances, if the widget supports multiple instances) can be accessed via the tag. But more on that later.
3. The description key is used for marketing the widget within a host OS or digital storefront. It should accurately (and briefly) describe what the widget does.
4. The template key is not currently used in the Windows 11 implementation but refers to the expected standard library widget template provided by the system. As a template library is not currently available, the ms_ac_template value is used to provide a URL to get the custom Adaptive Card (hence “ac”) template. The “ms_” prefix is there because it’s expected that this would be a Microsoft-proprietary property. It follows the guidance for extending the Manifest.
5. The data and type keys define the path to the data that should be fed into the template for rendering by the widget host and the MIME of the data format it’s in. The Windows 11 implementation currently only accepts JSON data, but the design of widgets is set up to allow for this to eventually extend to other standardized formats like RSS, iCal, vCard, and such.
6. update is an optional configuration member allowing you to set how often you’d like the widget to update, in seconds. Developers currently need to add the logic for implementing this into their Service Worker, but this setup allows the configuration to remain independent of the JavaScript code, making it easier to maintain.
7. Finally, icons and screenshots allow us to define how the widget shows up in the widget host and how it is promoted for install.

When someone installs my site as a PWA, the information about the available widgets gets ingested by the browser. The browser then determines, based on the provided values and its knowledge of the available widget service(s) on the device, which widgets should be offered. On Windows 11, this information is routed into the AppXManifest that governs how apps are represented in Windows. The Windows 11 widget service can then read in the details about the available widgets and offer them for users to install.

# Adding widget support to my Service Worker

As I mentioned earlier, all of the plumbing for widgets is done within a Service Worker and is modeled on the Notifications API. I’m not going to exhaustively detail how it all works, but I’ll give you enough detail to get you started.

First off, widgets are exposed via the self.widgets interface. Most importantly, this interface lets you access and update any instances of a widget connected to your PWA.

# Installing a widget

When a user chooses to install a widget, that emits a “widgetinstall” event in your Service Worker. You use that to kickoff the widget lifecycle by gathering the template and data needed to instantiate the widget:

self.addEventListener(“widgetinstall”,(event)=>{console.log(</span><span class="token string">Installing </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(initializeWidget(event.widget));});

The event argument comes in with details of the specific widget being instantiated (as event.widget). In the code above, you can see I’ve logged the widget’s tag value to the console. I pass the widget information over to my initializeWidget() function and it updates the widget with the latest data and, if necessary, sets up a Periodic Background Sync:

asyncfunctioninitializeWidget(widget){awaitupdateWidget(widget);awaitregisterPeriodicSync(widget);return;}

The code for my updateWidget() function is as follows:

asyncfunctionupdateWidget(widget){const template =await(awaitfetch(widget.definition.msAcTemplate)).text();const data =await(awaitfetch(widget.definition.data)).text();try{await self.widgets.updateByTag(widget.definition.tag,{ template, data });}catch(e){console.log(</span><span class="token string">Couldn’t update the widget </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">, e);}return;}

This function does the following:

1. Get the template for this widget
2. Get the data to flow into the template
3. Use the self.widgets.updateByTag() method to push the template and data to the widget service to update any widget instances connected to the widget’s tag.

As I mentioned, I also have code in place to take advantage of Periodic Background Sync if/when it’s available and the browser allows my site to do it:

asyncfunctionregisterPeriodicSync(widget){let tag = widget.definition.tag;if(“update”in widget.definition){registration.periodicSync.getTags().then((tags)=>{// only one registration per tagif(!tags.includes(tag)){periodicSync.register(tag,{minInterval: widget.definition.update,});}});}return;}

This function also receives the widget details and:

1. Looks to see if the widget definition (from the Manifest) includes an update member. If it has one, it…
2. Checks to see if there’s already a Periodic Background Sync that is registered for this tag. If none exists, it…
3. Registers a new Periodic Background Sync using the tag value and a minimum interval equal to the update requested.

The update member, as you may recall, is the frequency (in seconds) you’d ideally like the widget to be updated. In reality, you’re at the mercy of the browser as to when (or even if) your sync will run, but that’s totally cool as there are other ways to update widgets as well.¹

# Uninstalling a widget

When a user uninstalls a widget, your Service Worker will receive a “widgetuninstall” event. Much like the “widgetinstall” event, the argument contains details about that widget which you can use to clean up after yourself:

self.addEventListener(“widgetuninstall”,(event)=>{console.log(</span><span class="token string">Uninstalling </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(uninstallWidget(event.widget));});

Your application may have different cleanup needs, but this is a great time to clean up any unneeded Periodic Sync registrations. Just be sure to check the length of the widget’s instances array (widget.instances) to make sure you’re dealing with the last instance of a given widget before you unregister the sync:

asyncfunctionuninstallWidget(widget){if(widget.instances.length ===1&&“update”in widget.definition){await self.registration.periodicSync.unregister(widget.definition.tag);}return;}

# Refreshing your widgets

Widget platforms may periodically freeze your widget(s) to save resources. For example, they may do this when widgets are not visible. To keep your widgets up to date, they will periodically issue a “widgetresume” event. If you’ve modeled your approach on the one I’ve outlined above, you can route this event right through to your updateWidget() function:

self.addEventListener(“widgetresume”,(event)=>{console.log(</span><span class="token string">Resuming </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>event<span class="token punctuation">.</span>widget<span class="token punctuation">.</span>tag<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">);event.waitUntil(updateWidget(event.widget));});

# Actions

While I don’t want to get too into the weeds here, I do want to mention that widgets can have predefined user actions as well. These actions result in “widget click” events being sent back to the Service Worker so you can respond to them:

self.addEventListener(“widgetclick”,(event)=>{const widget = event.widget;const action = event.action;switch(action){// Custom Actionscase“refresh”:event.waitUntil(updateWidget(widget));break;}});

For a great example of how a widget can integrate actions, you should check out the demo PWAmp project. Their Service Worker widget code is worth a read.

# Result!

With all of these pieces in place, I was excited to see my site showing up in the Widget Dashboard in Windows 11.

You can view the full source code on GitHub:

• “Feed” Adaptive Card Template
• Widget definitions in the Manifest
• Widgets code in my Service Worker

I’m quite hopeful this will be the first of many places PWA-driven widgets will appear. If you’s like to see them supported elsewhere, be sure to tell your browser and OS vendor(s) of choice. The more they hear from their user base that this feature is needed, the more likely we are to see it get implemented in more places.

# Addendum: Gotchas

In wiring this all up, I ran into a few current bugs I wanted to flag so you can avoid them:

• The icons member won’t accept SVG images. This should eventually be fixed, but it was keeping my widgets from appearing as installable.
• The screenshots members can’t be incredibly large. I’m told you should provide square screenshots no larger than 500px ×500px.

I’m always looking for ways to improve these aspects of my own site. And, since it’s my own personal playground, I often use it as a test-bed for new technologies, ideas, and techniques. My latest adventure was inspired by a bunch of articles and posts I’ve linked to recently, especially

• Jeremy Keith’s “My First Service Worker”,
• Nicolas Bevacqua’s “Making a Simple Site Work Offline with ServiceWorker”,
• Dean Hume’s “Service Workers: Dynamic Responsive Images Using Webp Images”, and
• Malte Ubl’s “Not so micro optimizations”

After reading these pieces, I decided to see how much I could do to improve the performance of this site, especially on posts with a lot of images and embedded code samples, like my recent post on form labels.

# Using Resource Hints

To kick things off, I followed Malte’s advice and used Resource Hints to prime the pump for any third-party servers hosting assets I use frequently (e.g. Disqus, Twitter, etc.). I used the code Malte references in the AMP Project as my starting point and added two new methods (preconnect() and prefetch()) to my global AG object. With that library code in place, I can call those methods as necessary from within my other JavaScript files. Here’s a simplified extract from my Disqus integration script:

if(“AG”in window &&“preconnect”in window.AG){window.AG.preconnect(“//disqus.com/”);window.AG.prefetch(“//”+ disqus_shortname +“.disqus.com/count.js”);}

While a minor addition, the speed improvement in supporting browsers was noticeable.¹

# Integrating Service Worker

With that in the bag, I set about making my first Service Worker. I started off gently, using Dean’s piece as a guide. I added a WebP conversion bit to my image processing Gulp task to get the files in place and then I created the Service Worker. By default, Dean’s code converts all JPG and PNG requests to WebP responses, so I set it up to limit the requests to only those files being requested directly from my server. I have no way of knowing if WebP equivalents of every JPG and PNG exist on the open web (probably not), but I know they exist on my server. Here’s the updated code:

“use strict”;self.addEventListener(“fetch”,function(event){var request = event.request,url = request.url,url_object =newURL(url),re_jpg_or_png =/.(?:jpg|png)$/,supports_webp =false,// pessimismwebp_url;// Check if the image is a local jpg or pngif(re_jpg_or_png.test(request.url)&& url_object.origin == location.origin){// console.log(‘WORKER: caught a request for a local PNG or JPG’);// Inspect the accept header for WebP supportif(request.headers.has(“accept”)){supports_webp = request.headers.get(“accept”).includes(“webp”);}// Browser supports WebPif(supports_webp){// Make the new URLwebp_url = url.substr(0, url.lastIndexOf(“.”))+“.webp”;event.respondWith(fetch(webp_url,{mode:“no-cors”}));}}});

When I began tucking to the caching possibilities of Service Workers, following Nicolas’ and Jeremy’s posts, I opted to tweak Nicholas’ caching setup a bit. I’m still not completely thrilled with it, but it’s a work in progress. I’m sure I will tweak as I get more familiar with the technology.

To keep my Service Worker code modularized (like my other JavaScript code), I opted to break it up into separate files and am using Gulp to merge them all together and move the combined file into the root of the site. If you’d like to follow a similar path, feel free to adapt this Gulp task (which builds all of my JavaScript):

var gulp =require(“gulp”),path =require(“path”),folder =require(“gulp-folders”),gulpIf =require(“gulp-if”),insert =require(“gulp-insert”),concat =require(“gulp-concat”),uglify =require(“gulp-uglify”),notify =require(“gulp-notify”),rename =require(“gulp-rename”),//handleErrors = require(‘handleErrors’),source_folder =“source/_javascript”,destination_root =“source”,destination_folder = destination_root +“/j”,public_root =“public”;((public_folder = public_root +“/j”),(rename_serviceworker =rename({dirname:“…/”,})));gulp.task(“scripts”,folder(source_folder,function(folder){return gulp.src(path.join(source_folder, folder,“*.js”)).pipe(concat(folder +“.js”)).pipe(insert.transform(function(contents, file){// insert a build time variablevar build_time =newDate().getTime()+“”;return contents.replace(“”, build_time);}),).pipe(gulp.dest(destination_folder)).pipe(gulp.dest(public_folder)).pipe(rename({suffix:“.min”})).pipe(uglify()).pipe(gulpIf(folder ==“serviceworker”, rename_serviceworker)).pipe(gulp.dest(destination_folder)).pipe(gulp.dest(public_folder)).pipe(notify({message:“Scripts task complete”}));//.on(‘error’, handleErrors);}),);

As most of the walkthroughs recommended that you version your Service Worker if you’re doing any caching, I set mine up to be auto-versioned by inserting a timestamp (lines 23-27, above) into my Service Worker header file (line 3, below):

“use strict”;var version =“v:”,default_avatar =“https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mm&f=y”,missing_image =“https://i.imgur.com/oWLuFAa.gif”;

Service Workers are still pretty new (and modestly supported), but it’s definitely interesting to see what’s possible using them. Like Jeremy, I want to do a bit more exploration into caching and how it may actually increase the monetary cost of accessing a website if not used properly. Like any powerful tool, we need to wield it wisely.

# Making Gists Static

On particularly code-heavy posts (yes, like this one), I make liberal use of Gists. They’re quite useful, but the Gist plugin for Jekyll, while good, still requests a script from Github in order to load the pretty printed version of the Gist. On some posts, that can mean 5 or more additional network requests, not to mention execution time for the JavaScript. It’s yet another dependency that could prohibit you from quickly getting to the content you’re looking for. Additionally, if JavaScript should be available, but isn’t, you get nothing (since the noscript content is only evaluated if JavaScript support isn’t available or if a user turns it off).

With all of this in mind, I decided to revise the plugin and make it capable of downloading the JavaScript code directly. It then extracts the HTML markup that the JavaScript would be writing into the page and just embeds it directly. It also caches the result, which is handy for speeding up the build process.

You can grab my fork of the Gist Jekyll Plugin as, well, a Gist. It’s also in the source of this site on Github.

# (Hopefully) A Little Faster

All told, these changes have gotten the render time of this site down significantly across the board.² Even more so on browsers that support Service Workers and Resource Hints. I’ll likely continue tweaking as I go, but I wanted to share my process, code, and thoughts in case any of it might be useful to you in your own work. In the end, it’s all about creating better experiences for our users. How our sites perform is a big part of that.

Here’s a brief overview of the project:

The Candidate: My speaking engagements page.
The Challenge: The “Future” list will grow and shrink as I book things, so I never know how many will be there. The “Past” list will also grow, but I am less interested in getting crazy with that.
The Idea: A grid layout that flexes to visually highlight 1-2 upcoming future events and allows the others to flow in at the default grid size. It should be set up to handle everything from a single future event to a dozen or more.

The markup pattern was pretty simple. It’s just a list of events:

<ulclass=“listing listing–events”><liclass=“listing__item listing__item–1 event event–future”><!-- content --></li><!-- lis continue --></ul>

With that in place, I got to work.

# Single File

To set the stage, I started with some basic Flexbox syntax¹ by handling the container and the basic full-width small screen view:

.listing–events{display: flex;flex-wrap: wrap;}.event{box-sizing: border-box;padding: 1.25rem;/* 20px padding /margin: 0 0 1.25rem 0;/ 20px bottom margin /flex: 0 0 100%;}

You may be wondering where all of the experimental style rules are. I use Autoprefixer to handle the experimental property inclusion/trans-compilation so I can keep my CSS clean and standards-based.

This simple CSS gives you exactly what you’d expect: a vertical list of events, separated by 20px worth of space.

# Two by Two

Next up, I tackled the first breakpoint at 28.75em:

.listing–events{display: flex;flex-wrap: wrap;align-items: stretch;}.event{box-sizing: border-box;padding: 1.25rem;/ 20px /margin: 0 0 1.25rem 0;/ 20px v /flex: 0 0 100%;}@mediaonly screen and(min-width: 28.75em){/ 20px gap divided by 2 events per row /.event{flex: 0 0 calc(50% - 1.25rem / 2);margin-left: 1.25rem;/ 20px < /}/ Remove left margin for row starters /.event:nth-child(odd){margin-left: 0;}/ Reset margins on “future” events& remove the correct one /.event–future:nth-child(odd){margin-left: 1.25rem;}.event–future:nth-child(even){margin-left: 0;}/ Quantity Query - when more than 1,make the first span both columns  /.event–future:nth-last-child(n + 1):first-child{flex: 0 0 100%;font-size: 1.5em;margin-left: 0;}}

In this pass, I set up the event blocks to fill 50% of the parent container (well, 50% minus the 1.25rem gutter between them, using calc()).² In order to make the children wrap to form rows, I set flex-wrap: wrap on the list (.listing–events). Then, to make the children all equal heights across each row, I set align-items: stretch. The gutter space was achieved via left margins on all events save the row starters (.event:nth-child(odd)).

It’s worth noting that in the full page I have two sets of event listings: one past and one future. The “event” class is used in all instances. The modified “future” class is added to events that have not happened yet.

Then I used a quantity query to select the first future event when there is more than one in the list (line 38) and set it span 100% of the parent width. To keep the gutters accurate, I also swapped where the margins were applied, adding the margin back to .event–future:nth-child(odd) and removing it from .event–future:nth-child(even).

# Three’s a Crowd

Finally, I could tackle the third and most complicated layout. Things seemed to get a little wide around 690px, so I set the breakpoint to 43.125em.

.listing–events{display: flex;flex-wrap: wrap;align-items: stretch;}.event{box-sizing: border-box;padding: 1.25rem;/ 20px /margin: 0 0 1.25rem 0;/ 20px v /flex: 0 0 100%;}@mediaonly screen and(min-width: 28.75em){/ 20px gap divided by 2 events per row /.event{flex: 0 0 calc(50% - 1.25rem / 2);margin-left: 1.25rem;/ 20px < /}/ Remove left margin for row starters /.event:nth-child(odd){margin-left: 0;}/ Reset margins on “future” events& remove the correct one /.event–future:nth-child(odd){margin-left: 1.25rem;}.event–future:nth-child(even){margin-left: 0;}/ Quantity Query - when more than 1,make the first span both columns  /.event–future:nth-last-child(n + 1):first-child{flex: 0 0 100%;font-size: 1.5em;margin-left: 0;}}@mediaonly screen and(min-width: 43.125em){/ 1/3 width with 20px gutter /.event{flex: 0 0 calc(100% / 3 - 0.875rem);}/ Reset margins /.event:nth-child(even),.event:nth-child(odd){margin-left: 1.25rem;}/ Normal Grid margin removal /.event:nth-child(3n + 1){margin-left: 0;}/ Correct margins for the future events /.event–future:nth-child(3n + 1){margin-left: 1.25rem;}/ Quantity Query - when more than 2,make the first 2 go 50%  /.event–future:nth-last-child(n + 2):first-child,.event–future:nth-last-child(n + 2):first-child + .event–future{flex: 0 0 calc(50% - 1.25rem / 2);font-size: 1.5em;}/ Quantity + nth for margin removal */.event–future:nth-last-child(n + 2):first-child~ .event–future:nth-child(3n){margin-left: 0;}}

In this final pass, I used a slightly more complicated calculation to set the width of each child to 1/3 of the parent minus the gutters between them (100% / 3 - 0.875rem).

If you’re paying close attention, you might wonder why the gutter being used in the calculation is 0.875rem rather than the full 1.25rem. Well, the reason is (as best I can surmise) rounding. In order to get the flex width to fill the parent without causing a wrap, 14px (0.875rem) seemed to be the magic number.

It’s worth noting that if I allowed the event to grow (using flex-grow: 1 or its equivalent in the shorthand), the column would fill in perfectly, but the last row would always be filled completely too. You could end up with two events in the last row being 50% wide each or a single event being 100% wide, which I didn’t want. I wanted them all to be equal width with the exception of the first 2. Setting flex as I did allowed that to happen.

I went ahead and reset the standard margins for events as well (on both .event:nth-child(even) and .event:nth-child(odd)). And then I turned off the margins on the first of every group of three events using .event:nth-child(3n+1).

With that in place, I went to work on the future events, resetting the margins there as well. Then I used a quantity query (lines 70-71) to select the first two members when the list is more than 2 and set them to be 50% of the parent width minus the gutter.

To handle the margins in the quantity query instance, I added all the margins back (line 64) and then removed the left margins from the new row starters (line 77).

# Ta-da!

And there you have it. In about 80 lines of very generously spaced and commented CSS, we’ve got a flexible grid-based Flexbox layout with visual enhancements injected via quantity queries. I’m sure I’ll continue to tinker, but I’m pretty happy with the results so far.

You can view the final page of course (or watch a video of the interaction), but I also created a distilled demo on Codepen for you to play with.