DEV Community: Andrico

The Two Lines of CSS That Tanked Performance (120fps to 40fps)

Andrico — Mon, 02 Sep 2024 13:00:00 +0000

I recently released Learn WCs and If you’ve seen it, you’ve likely noticed the animation in the background, where the coloured circles move diagonally across the screen. It looks like this:

It works nicely on Chrome and Safari, but I noticed a severe drop in performance on Firefox.

The performance was so bad, that I straight up disabled this animation in Firefox.

How does the animation work?

The animation is built using two nested divs. The outer div is the first child of the site’s body tag.

<body>
    <div class="background-mask">
        <div class="background-gradient"></div>
    </div>

    <!-- Rest of content -->
</body>

The .background-gradient element is responsible for creating a gradient that spans the entire width and height of its parent container. Like so:

The outer .background-mask is responsible for two things:

It sets the position to fixed, and makes the container fill the entire dimensions of the viewport.
Creates a dotted mask over the gradient

This ensures that the colour of the dots is the colour of the gradient directly underneath it:

Here’s the CSS for everything I described above:

.background-mask {
    --mask-size: 24px;

    /* Position Styles */
    position: fixed;
    width: 100%;
    height: 100%;
    z-index: -1;

    /* Mask Styles */
    mask-image: radial-gradient(black 2px, transparent 2px);
    mask-size: var(--mask-size) var(--mask-size);
    mask-position: 0px 0px;
    animation: mask-move 3s infinite linear;
}

.background-gradient {
    background: var(--red);
    background-image: var(--gradient);
    width: 100%;
    height: 100%;
}

@keyframes mask-move {
    0% {
        mask-position: 0px 0px;
    }

    100% {
        mask-position: var(--mask-size) var(--mask-size);
    }
}

@media (prefers-reduced-motion: reduce) {
    .hero-background-mask {
        animation: none;
    }
}

If you’re interested in learning more about masks in CSS, then I can recommend this comprehensive post by Ahmad Shadeed

What’s causing this drop in performance?

Not all CSS properties animate equally. Without going too much into how the browser renders HTML to the page (though I’ve outlined it here), there are a handful of stages it goes through. The three stages that we’re interested in are:

Layout - When the browser calculates the size and positions of the elements on the page
Paint - Draws all the visual aspects of the page, like images, colors, shadows, etc
Composite - Layering the elements on top of one another in the correct order

The order of the pipeline looks like this:

Layout → Paint → Composite

The layout and paint processes can be CPU-intensive, so it’s important to try and reduce the amount of times your CSS triggers the stages in the pipeline*.* The browser helps in some part by optimising performance for certain properties, some skip entire stages of the rendering pipeline and others can leverage hardware acceleration to move computation from the CPU to the GPU.

Animating certain properties, like translate and opacity , both avoids triggering a layout and uses hardware acceleration.

Sadly, this is not the case when animating mask-position. I took a look at Chrome and saw that the paint count for the background div was increasing on every frame. After a few seconds it had already triggered a paint over 1,000 times.

Even with this high paint count, the animation on Chrome feels smooth. However, it feels super janky on Firefox. Annoyingly, I couldn‘t find a way to measure the paint count on Firefox, so any assumptions I make about Firefox’s poor performance is purely conjecture.

What I did notice is that the animation is fine for small devices, but gets worse as the size of the screen increases. My working theory is that Firefox doesn’t batch the layout triggers for each the 24x24 masks, which causes the FPS to tank when more 24x24 masks are present. Again, I might be completely wrong here.

How did I fix this?

Instead of animating badly optimised CSS properties like mask-position , I needed to lean on the more performant properties, like translate.

The solution wasn’t to move the masks by 24px, but to instead move the entire background element using the translate property.

From an abstract standpoint, this is how the animation looks:

Here’s the two line change in the CSS:

/* --mask-size = 24px */

@keyframes mask-move {
    0% {
        transform: translate(calc(var(--mask-size) * -1), calc(var(--mask-size) * -1));
    }

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

The browser no longer animates the mask-position, which triggered a layout on each frame. Even though the background moves on each frame, through translate it doesn’t trigger a layout or a paint. You can see that the only paints twice, down from 1,000+ every minute.

Eagle-eyed viewers will have spotted a problem. If you remember, the height and width of the background fills the viewport. Shifting the background left and up by 24px leaves us with this empty space in the viewport.

Solving it is as simple as adding the mask size to the width and height of the container:

.background-mask {
    --mask-size: 24px;

    width: calc(100% + var(--mask-size));
    height: calc(100% + var(--mask-size));
}

Let’s take a look again in Firefox:

It may not be a perfect solution, but it’s always a little satisfying pulling off a fun smoke and mirrors CSS trick.

What is a component library and should you build your own?

Andrico — Tue, 06 Aug 2024 09:18:11 +0000

💡 I want to give a special shoutout to stephband (Mastodon, Bluesky) for proofreading and providing feedback.

Please note that this is a X-Post from my site. The content is largely the same, but the original post has interactive snippets and videos that are omitted in this article.

What if there were no music albums?

I’m a huge music fan. One of my favourite pastimes is to put on a record and listen to it front to back. A music album is simple in concept, it’s a suite of recorded tracks by an artist and is considered a complete and coherent set of songs.

But what if recorded music didn’t exist? Instead of putting songs to tape, CD, or mp3 (or FLAC if you’re that way inclined), you could only listen to an album if the artist played it live for you. You’d need to go to the band, ask them to set up their equipment and get them to play the album front-to-back. They’d need to play it the same way every time to ensure that everyone had the exact same experience.

The cracks would start to show. It’s not an efficient way to ensure that anyone interested in the band’s music can listen to it. If Taylor Swift were to play her song Fortnight personally for every person who listened to it on Spotify, it would take her 3,179 years. And that doesn’t account for any plane travel. Artists would get bored, maybe even careless, leading to a lesser experience for their listeners.

So how does this relate to web development? Every time you build a UI control, you have to ensure it’s functioning, robust, and accessible. You’ll get bored if you keep rewriting the same UI every time. Mistakes will slip through, leading to a worse experience for your end users.

A little about me

I’ve been a web developer for nearly 10 years, and I’ve written hundreds of components myself, often the same UI pattern many times. I’ve used dozens of component libraries, and have built admin dashboards, component libraries, mobile applications, blogs, figma plugins, VSCode extensions, and more. This article will be a distillation about where I see the role of components, libraries, and whether developers should write their own.

What is a component?

When building user interfaces, we don’t write all the HTML markup from scratch every single time. We write our UIs using components— reusable building blocks that encapsulate common UI patterns. Writing a component lets you use it multiple times in a single project or even in independent projects.

Here I’ve written a counter component, I’ve written it once and used it in multiple places on the page.

<body>
  <div class="wrapper">
    <counter-button></counter-button>
    <counter-button></counter-button>
    <counter-button></counter-button>
  </div>

  <script type="module">
    import { LitElement, html } from 'lit';

    class CounterButton extends LitElement {
      constructor() {
        super();
        this.count = 0;
      }

      static properties = {
        count: { type: Number }
      };

      _increment() {
        this.count++;
      }

      render() {
        return html`
          <button @click=${this._increment}>Count: ${this.count}</button>
        `;
      }
    }

    customElements.define('counter-button', CounterButton);
  </script>
</body>

Us tutorial creators like to demo counters like they’re going out of style, but a real-world application will contain dozens of different UI patterns written as components.

In this article, I’ll group CSS rules that provide styling for certain UI patterns under the components umbrella. The definition can get murky depending on who you ask.

What is a component library?

Not all components are standalone. It makes sense for many components to be grouped within a single package, called a component library.

If you want your site to have a specific look or feel, you can use a component library. There are component libraries that:

offer components that adhere to a design specification.
offer multiple solutions for a specific UI pattern.
work with specific toolchain

But they come in different shapes and sizes. The definition I’ve come to use when defining a component library is the following:

A component library is a set of reusable components that are cohesive in their utility, or appearance (or both). A great component library will help developers achieve their UI needs efficiently, while offering an exemplary experience for the end user.

What’s the difference between a component library and a design system

I talk about guidelines and design systems later in this article, so I’ll take a moment to disambiguate them. It can be difficult to see where one ends, one begins, or one subsumes the other.

Design Systems

I see a design system as a specification for how things should look, feel, and behave. A design system can encompass a product, a brand, or a company to ensure consistency across the suite of experiences. A comprehensive design system will dictate everything from font families, font sizes, spacing sizes, UI patterns, and copy guidelines.

A few of the most well-known design systems include:

Material Design (Google)
Base Design (Uber)
Lightning Design System (Salesforce)

While many design systems are specific to companies, there are design systems, like Material Design, that teams across the globe use to shortcut their way to building familiar feeling products. You’ve probably used a handful of products that use Material Design principles but they’re certainly not free from basic usability issues.

Component Libraries

As for component libraries, they may or may not be the code implementation of a design system. If you work for a company with a design system, it’s likely that the corresponding component library (if one exists), is tightly integrated with it.

For instance, Google’s Material Web is a web component implementation of Material Design. Base Web and Lightning Web Components are also open source too.

A brief history of component libraries

The concept of UI components (or widgets) has been around for a long time. If you want to see a museum’s worth of retro user interfaces, grab some popcorn and watch this 2+ hour video of "all the widgets" from 1974-1990.

From the early 2000s, we’d start seeing component libraries made to help developers build for the web. The web browser landscape back then was unrecognisable from what we see now. Versions of Internet Explorer deviated away from the spec entirely, which was particularly problematic given the huge market share that IE had back in the day. Internet Explorer 6 was famously known for being a pain to develop for. Mainly due to its incorrect implementation of the box model, and lack of CSS2 support.

💡 TIL, Internet Explorer supported a “quirks mode” that let developers write non-standard HTML and CSS to appease older browsers that didn’t support the standards.

Fortunately, when I started web development in earnest, many of these issues were ironed out. By this point, there were still a handful of libraries that made writing complex interfaces with cross-browser support a little easier. jQuery UI, the first component library I used, supported accordions and other widgets. But the browser is constantly evolving, and we now have a native way of implementing this accordion pattern using the details and summary elements, available in all browsers in 2020. With these elements, you can get pretty far along creating interactive accordions without JavaScript.

Contrast this with 2009, and these elements haven’t been implemented in any browser. It required a fair bit of JS to get working. Have a look at the jQuery UI v1.7 source code, and CTRL+F “accordion” if you want to see how web devs were implementing accordions 15 years ago.

Over the next couple of decades, the capabilities of the web grew. More powerful devices meant more powerful browsers. More powerful browsers meant web applications became more ambitious. Developers responded by creating the tools to help us build these applications by allowing us to create UIs using building blocks, i.e., a component model. We saw a proliferation of these component-based frameworks. I’m talking Angular, React, and Vue. Each with its own rich ecosystem of component libraries.

There’s a reasonable argument to be made that there has been an over-correction and that the frontend landscape is now oversaturated with tools that are too powerful for most people’s needs, but let’s not go there.

This version is extended with interactive snippets on the original post

What makes a good component library?

The challenge with building a component library is that they’re not a one-and-done deal. Many of the most popular libraries have been around for years and have had heaps of research, usage feedback, and contributions to get them to where they are now.

I’ve found that a good component library often has the following traits:

It understands the problems of its target developers and solves those problem well
It has great documentation
It ensures a good experience for the end-user
It’s robust and caters for appropriate input modes and devices.

On the flip side, a way to discern if a component library isn’t good is if it doesn’t consider accessibility, has an inconsistent API, has little to no project stewardship, or has no clear and consistent documentation.

What are the benefits of using a component library?

We know what a good component library looks like, so let’s see how one can make your life, and the lives of your users a little better.

Component libraries save you time

If you’re on a project with a tight deadline, it’s important to be efficient. But efficiency shouldn’t come at the cost of crafting a robust web experience. Using a component library lets you spend less time reinventing the wheel and more time focusing on the finer details.

Component libraries make you and your users happier

We’re not motivated by repetitive work. We enjoy technical challenges, and writing the same components over again is not a fun challenge. We’ve already spoken about what happens when we get bored and let mistakes slip through.

If you wanted to implement a dialog component from scratch, you’d need to:

Handle focus trapping correctly
Make the rest of the page inert
Position the dialog correctly
Ensure that it works with assistive technologies

It takes work to remember and implement the above, but the consequence of getting it wrong can render your interface literally unusable, such is the case if you incorrectly handle focus.

By using a component library that’s been built with the end users in mind, you can prevent the risk of introducing broken experiences, while spending less time rebuilding the same components.

Component libraries lead to consistent experiences

If you work for a company with several different web applications, they’ll generally follow a set of guidelines. These guidelines might dictate the colour palette to use, the size of your typography, or how UI elements should look and behave.

But you increase the likelihood of your application deviating from the style guide if you’re re-writing components. By having a component library, you can more easily audit your component’s UI against the brand guidelines so they look great, wherever they’re used.

Uber has several different apps that share the same user interface elements. I’m almost certain that they use the same component library across these apps. That way each new app is virtually guaranteed to adhere to the brand’s guidelines.

What are the drawbacks of using a third-party component library?

The benefits I’ve mentioned above are irrespective of whether you’re using your own component library or a third party. If you or your team has decided that they don’t want to build a library, and instead lean on a third-party, then it’s worth considering the following.

Vendor lock-in

By choosing a component library, you’re picking a partner who will greatly impact how you write your frontend code and how your interfaces will look and behave.

The former will have a big impact on you, and the latter will have a big impact on your end users. Using a component library is locking you into the standards of that component library.

The library could introduce massive breaking changes in a major version that could require dedicated development time, and a lot of testing to ensure that no serious regressions were introduced.

A few years back I used React Admin to build a complex admin dashboard to an internal division. The library offered a suite of components specifically dedicate for fetching and displaying complex data. Because our application at the time relied heavily on React Admin, upgrading between major versions was challenging, especially as many of the internal tools used by React Admin had been swapped out for others. The change surface was huge, and we spent a good deal of time upgrading and flagging the issues that we spotted.

I don’t believe that building our own solution would have saved us any time in the long term, but this kind of vender lock-in is worth considering, especially before going all in on a tool.

Code bloat

Shocking as it is, libraries with a lot of components tend to be written using lots of code. Code that you download when installing dependencies, and code you sending over to your end users.

Modern tooling makes it easier to perform bundle optimisations like tree-shaking to remove unused code, but there’s no guarantee that you’re removing all of the code that your users won’t need.

Unless you dig deep into the libraries that you’re using, you may not be aware of all the separate packages they’re importing. You could end up with hundreds of unnecessary dependencies. The folks in the e18e community have been working hard at bringing this problem to light, while also fixing it too.

Many of these problems could also be said about rolling your own component library. The biggest difference is that you have stewardship over your component library. You’re able to define how it solves your specific problems, and you have control over improving its shortcomings.

The different shapes a component library can take

The initial proposal for the World Wide Web was a tool to improve communication between researchers at CERN. The proposal outlined how documents could be shared, and linked to one another through the use of hypertext. This is the fundamental cornerstone of the web, and we still use the humble <a> tag to link between other HTML documents across the web.

But the web has grown in scope over the last few decades, and the browsers we use to navigate the web have become beasts of their own. The browsers today can enable powerful forms of creative expression, and the running of native-like software.

There are hundreds of different solutions out there, some general purpose, others hyper-niche, but finding the right tool for your next project requires a complex decision process that might look like this.

This isn’t a comprehensive list of ALL use cases or component library types, but it illustrates how component libraries differ in terms of:

the technologies involved.
the levels of abstraction they offer.
the problems they solve.

Let’s take a look at some of the most common component library types

💡 A quick side note: If you're interested in building your own web component library, then consider checking out my course Component Odyssey. You'll learn how to build and publish a component library that works in any frontend framework.

Utility classes libraries / CSS Style Guides

For me, Bootstrap is the first that comes to mind. Back in the day, if you wanted to give your site a quick lick of paint, you’d drop the CDN link to the bootstrap CSS file and immediately get that Bootstrap look. It was everywhere in the mid-2010s.

The technical scope of these kind of tools range from

A single CSS file (Pico)

A toolchain to generate CSS classes based on your configuration (Tailwind)

Dozens of other tools, like Open Props, fit somewhere in between.

Off-the-shelf component libraries

If you’re building an interactive web application, you might just want to grab a suite of components that look great and function well. There are many of these off-the-shelf component libraries that give you everything you need and more.

Regardless of which framework you’re writing your app with, there’s likely to be a set of great looking components for you to use.

Another great component library is Shoelace, which provides dozens of fully interactive and fully-styled components.

What makes libraries like Shoelace particularly interestingly is that it’s built using web components, the browser’s built-in way of writing components. Building your UIs with tools like Shoelace, give you the added benefit of being able to use them across different frontend frameworks. Which is something I’ve spoken a little about in the past.

Here's the same Shoelace component being used in Vue and React.

Unstyled components

Depending on your project’s specs, you might not have the luxury of using an off-the-shelf tool. Your design specs might be very specific.

I’ve seen teams roll components at the first sign of friction. And in one case of a hand-rolled data picker, led to a way worse user experience. In retrospect, using an unstyled component library would have given the team flexibility with appearance, while ensuring that the time

That’s why you can reach for a library out there that offers completely unstyled components with flexible styling hooks. If it’s a good library, it’ll also take care of all those complex interactions. It’s a best of both worlds situation.

It’s easy to mess up a checkbox if you want to push beyond the styling hooks that the browser provides, unless you test with a wide-range of devices and input modes.

The original article has a video showing me interact with different checkbox implementations using a screen reader

Radix is a popular example of a library, but it’s built using React.

Other examples of component libraries like this are Lion and HeadlessUI.

Copy Pastable Component Libraries

Some developers might want the best of both worlds. They might want a component built by a trusted third-party library, while also having full control over the markup, styles, and functionality. Libraries like ShadCN allow for this kind of work flow, by allowing developers to copy and paste the component definition into their own projects, effectively letting them own the component.

Why isn’t there one component library to rule them all?

At this point, it’s probably clear why no such single component library exists. We’ve looked at a non-exhaustive look at different groups of component libraries.

There is, however, a movement to introduce a “Global Design System”, a concept spearheaded by Brad Frost.

In the announcement, Brad outlines that in the hundreds of projects he’s been a part of, many of the UI controls behave (or should behave) similarly across these various projects, yet developers reimplement the same thing in every single project. This has lead to lots of wasted time and effort, and inconsistencies between projects. This also expands to the existing component libraries out there. You’ll see that the keyboard behaviour for a combobox in React Aria, is different to that of the combobox in ShadCN.

The original article has a video showing me interact with different combobox implementations using a keyboard

Brad Frost is proposing a Global Design System as a set of web components that should be adoptable by almost any frontend project to ensure a baseline of functionality for the controls that are not yet available in HTML.

There are discussions going on within the Open UI to see how this could start taking shape within the next few years.

Should you build your own component library?

This article has been a wide dive into component libraries, and with all that context, you’ll inevitably ask yourself, when staring at the empty HTML page for your next big project, whether to build your own component library or use an existing one.

My first thought is: I don’t think you should build your library.

I generally favour picking a battle-tested library. Particularly one that has:

Been used across thousands of projects
A strong community, in Discord, or GitHub
Great documentation
A strong focus on accessibility
Worked with the strengths of the chosen framework

Most importantly out of all of these is to use a component library puts care into building accessible components.

Take a combobox for instance. It’s a search input and a select menu mixed into one. If you’ve built your own, you may get it looking good, and working with your mouse. But you’ll also need to consider:

Cross browser support
Tab and focus behaviour
Screen reader support
Handle states for async loading of search results

Konnor Rogers, who does excellent work in the web + web component space, has shared countless frustrations with his experiences building an accessible combobox. Here’s one such tweet he shared.

Screen reader support is particularly complex, and is worth of its own bullet-point list. To support screen readers, you’ll also need to handle:

live regions
interactive controls
selected items
support between different screen readers

As a side note, I only have access to Voiceover, meaning it’s difficult for me to test these complex UI patterns using different screen readers. Like browsers, there are differences between screen readers. In this article, Are We Live?, Scott O’Hara describes how there’s variance among the difference with how they treat the live regions.

This means it’s also up to you, the developer to pick a component library that you can trust has been developed with accessibility in mind. This is why it’s also important to pick a component library that has a strong community. It’s important to be able to:

See the bugs and issues others have flagged for a given library
Suggest (or even contribute) improvements and changes to such library
Discuss ideas with members of the community and build working relationships with active members of the community or even maintainers themselves

Finally, and not least, a great component library will consider much more than the aesthetics of their components. For a component library designed for the web, it should try it’s best to:

adhere to the Web Content Accessibility Guidelines (WCAG)
ensure that the components work across different input modalities (touch, keyboard, screen reader)
ensure that the components are usable for folks with additional requirements, like those living with vestibular disorders, vision impairments, or a broken hand.

Building your own component library can be a good thing, actually

If I haven’t scared you off from building a component library, then let me contradict myself and explain why it can be a really good thing to build your own.

If you take the time to put care and attention into building a component library, then you’ll find yourself a developer who better understands the browser platform, accessibility best practices, testing practices, and more.

But it doesn’t just stop there, there are some excellent reasons to build your own library.

For starters, you can build something tailored to your needs, and avoid some of the bloat you might get form an off-the-shelf component library. It’s up to you and your team to understand your end users, and you can build something specifically for them.

You also have the opportunity to experiment with novel approaches. If you have a hyper-niche problem, there might not be a component library out there to solves that need. It could be a component library that:

Visualises data in specific way
Has a distinct and unique visual identity
Is built on a new framework

That gives you the opportunity to build something tailored to your needs. You then have the opportunity to change and fix things as your needs change, or as you understand the problem space better.

Importantly, you’ll learn more about the web by doing so. If it’s your first time building a component library, it can be an opportunity to dive deeper into the HTML browser specs, or brush up on your web accessibility knowledge. This will improve your abilities as a web developer, which will serve you well in any frontend project in the future. It could even help you land your next job.

So whether you should build a component library depends on your end goals. Consider questions like:

Do I want to better under stand the browser?
Do I want to build something quickly?
Do I want to make it usable for as many users as possible?
Do libraries exist that solve my current problem?

Depending on what your answers are, you can make the right call for your project.

Thanks for reading! If you're interested in building your own web component library, then consider checking out my course Component Odyssey. You'll learn how to build and publish a component library that works in any frontend framework.

Using Heaps of Cutting Edge CSS Features to Build a Progress Indicator

Andrico — Tue, 09 Jan 2024 09:00:00 +0000

For the last 7 months, I’ve had my head down building Component Odyssey. It’s been a richly fulfilling project and I’m eager for people to take the course and learn heaps about building component libraries using web components.

I’ve seen some incredible demos over the past year and wanted to bite my teeth into some of these cool new features. So I used some downtime over the Christmas period to cram tons of new CSS features into a lesson progress indicator for the Component Odyssey platform. The result is the following progress indicator that shows how much of the page the user has scrolled:

Building it gave me some exposure to some of the latest CSS features like:

animation-timeline: scroll()
CSS trig functions, sin() and cos()
color-mix()
the @property at-rule

I know the risks of building something with a particular tool in mind. As the saying goes “When all you have is a hammer, then something something nails”

Yes, I have a hammer, and I’m going to smash the walls down with it

In this article, I’ll run through how to create a pared-down version of this swanky progress animation while still using all of the CSS features mentioned above. I’ll also show you how to gracefully handle browsers that don’t support these features through progressive enhancement.

If you want to follow along, then it’s best to use the latest versions of Chrome or Safari, currently Firefox doesn’t have general support for properties like animation-timeline. Get started by jumping into the starter Codepen.

If you want to peruse the finished code, you can check it out here.

Creating the markup

I’ve already provided a little markup to simulate a page with enough content that you need to scroll to get to the bottom. To get started creating the progress indicator, you’ll need to add some more markup.

The markup itself is really simple, we’ll only need to create 3 div elements.

The outer element is responsible for the positioning and layout of the loader. We’ll give this a class of wrapper.

The middle element is responsible for rendering the track to the screen. We’ll give this element a class of progress. We’ll later use a ::after pseudo-element to create the thumb.

The innermost element will be used to create the circular hole in the middle, making the indicator look like a low-calorie doughnut. This will have a class of inner.

Take a look at the following if you need a hand visualising the structure:

Provide the following markup as the first child of the main element create the following markup:

<div class="wrapper">
    <div class="progress">
        <div class="inner"></div>
    </div>
</div>

You’ll also need to apply the following styles to give the markup a base visual experience:

.wrapper {
    --size: 80px;

    position: fixed;
    width: var(--size);
    aspect-ratio: 1/1;
    top: 24px;
    left: 24px;
    display: flex;
    align-items: center;
    justify-content: center;
}

.progress {
    --track-size: 16px;

    width: var(--size);
    aspect-ratio: 1/1;
    border-radius: 50%;
}

.inner {
    position: absolute;
    width: calc(100% - var(--track-size));
    aspect-ratio: 1/1;
    background: var(--background-color);
    border-radius: 50%;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    margin: auto;
}

Most of the CSS here shouldn’t come as a shock to you, so I won’t go over it line by line, but I will touch on some of the more interesting bits.

In .wrapper we’re fixing the element to the top left of the screen, and using flexbox to center the children horizontally and vertically.

💡 I learnt that if you want an element to share the same value for both its width and height, you just set the width and use aspect-ratio: 1/1. The browser will implicitly set the height. This is a neat trick because you won’t have to define the same value twice, and it makes it easier to guarantee that the width and the height share the same value.

As for the .inner element, I’ve used a mix of absolute positioning and the margin: auto to center it in the middle of the .progress element. We’ve also deducted the --track-size from the full width of the container, to ensure that it’s correctly positioned over the .progress element.

You won’t be able to see anything just yet, but if you add a temporary background-color: red to the .progress element, it should render as follows:

Creating an animated progress indicator

Creating a scroll-driven animation of this kind requires a lot of new CSS features that you may have not used before. Instead of learning everything all at once, we’ll start by decoupling the animation from the scrolling mechanics.

That way, by the end of this section, you should have the following animation that plays automatically:

We’ll start by creating a new animation called load:

@keyframes load {
    0% {
        --progress: 0%;
    }

    100% {
        --progress: 100%;
    }
}

All this does is move the progress along from 0 to 100 over the course of the animation. In your .progress rule, add the following CSS properties:

.progress {
    # Existing rules

    animation: load linear 1s infinite;
    background: conic-gradient(
        from 0deg at 50% 50%,
        var(--red) var(--progress),
        var(--black) var(--progress)
    )
}

The animation property should be pretty straightforward, but there’s a lot going on with the background rule, so let’s step through it.

For starters, we’re using a conic-gradient as it makes it easy for us to animate the background over 360 degrees, in the way shown in the animation above. We’re starting from the 0deg position, which is top and center. We’re describing where we want the center of the gradient to be using at 50% 50%.

conic-gradient(from 0deg at 50% 50%) alone would render something like the following:

Hopefully I’ve made it clear why that’s the case.

As for the the second and third arguments of the conic-gradient function, we’re linking the --progress variable (which is being calculated via the load animation) to the two colors. The --red is used to denote the completed progress, while the --black is used to denote the remaining position. It might be confusing why they share the same --progress value. The --progress value for the --red value denotes where the gradient stop ends, while the --progress value for the --black denotes where the gradient stop begins. Because it’s the last stop on the gradient, it’s implied that it ends at 100%. By setting the same --progress value to both stops in the gradient, we create a hard transition between the two colors. Without doing so, our progress indicator (with a --progress value set to 16%) would look like this:

Now, something strange is probably happening. Instead of your progress indicator transitioning gracefully across the entire perimeter of the circle, it’s instead flashing between the black and red.

Why is this happening?

This is because we’re making the browser interpolate between percentage values, which is something it can’t do automatically. Even though we’ve given the --progress variable a percentage value, the browser doesn’t assume that it’s always going to be a percentage value.

We can solve this by telling the browser that --progress will always be a percentage value. We can do this by explicitly defining the --progress property using the @property CSS rule. Just add the following to the top-level of your CSS:

@property --progress {
    syntax: '<percentage>';
    inherits: false;
    initial-value: 0%;
}

We’re telling the browser that --progress should only support percentage values and that the initial value is 0%. We’re also not interested in having the custom element inherit its value.

Finally, I don’t quite like the use of the --black variable to signify empty progress. It looks too stark. I’d like to create a lighter shade created from the black to ensure a more homogenous visual palette. This is something we can easily achieve using the color-mix() CSS function.

Jump back up to the :root CSS rule and add the following variable:

:root {
    # your other CSS variables

    --grey: color-mix(in srgb, var(--black), transparent 60%);
}

The color-mix function lets us mix two colors together. In this case, we’re mixing the color stored in our black variable with some transparency, which will result in a partially see-through grey color. You’ll need to replace the reference to the --black variable in the conic-gradient function with --grey to see the color change in effect.

Now that we’ve defined our custom property, the browser will be able to interpolate the correct values during the entire animation, so it should now transition smoothly from start to finish.

Scroll driven animations

The next stage of our animation journey is to tie our animation to the scrolling of the page.

This should only take us a couple of lines of CSS.

You’ll need to do two things. First adjust the animation property in your .progress class to remove the infinite value, and to change the duration from 1s to 1ms. We can’t remove the value altogether because Firefox needs it for scroll animations to work.

Next update your .progress class to include the following

.progress {
  # other CSS properties

    animation-timeline: scroll(nearest block);
}

The animation-timeline property tells the browser to tie the progress of the animation with a specific timeline. In this case it’s the scroll timeline, which we specify using the scroll function.

You can see I’m providing two arguments to scroll(), nearest and block.

The nearest value is used to tie the animation to the nearest ancestor that has a scrollbar, in this case it’s the document. If you’re certain that you only ever want to tie the animation to the document’s scrollbar, then you can use swap out nearest for root instead.

The block property denotes the axis that we want to tie our animation to. For most cases this will be the vertical scrollbar, but for vertical writing modes, this will be the horizontal scrollbar.

Now that you’ve hooked up the animation to your page’s scroll, you should be able to scroll up and down the page and watch how your animation changes accordingly.

Progressively enhancing your scroll animation

While it’s exciting to use these new features in the browser, the animation-timeline property doesn’t have universal support across browsers yet. It’s still very new in Chrome, and it’s only available in Firefox behind a feature flag. If you try opening the code in Firefox, you’ll notice that the progress ring just appears with a finished animation.

In cases like this, it’s important to set up a solid base experience for all browsers, and then progressively enhance your webpage with the newer features on compatible browsers. Because the progress indicator isn’t critical for the application to function, we can just hide it away if the browser doesn’t support the animation-timeline property.

We can do this by moving our .wrapper, .progress, and .inner classes within CSS’s @supports at-rule, like so:

@supports (animation-timeline: scroll()) {
    .wrapper {
    }

    .progress {
    }

    .inner {
    }
}

Doing so ensures that if the browser doesn’t support scroll(), then it will ignore all of the styles contained within the rule.

Adding the indicator thumb

The final thing for us to add is a cool little indicator thumb, to both give our progress indicator a little more visual interest and to also let us play with the swanky CSS trigonometric functions.

To create the indicator thumb, start by writing the following CSS inside of the @supports block:

.progress::after {
    --radius: calc(var(--size) / 2);
    --track-offset: calc(var(--track-size) / 4);

    content: '';
    position: absolute;
    aspect-ratio: 1/1;
    width: calc(var(--track-size) / 2);
    background: var(--red-dark);
    border-radius: 50%;
    left: calc(50% - var(--track-offset));
    top: calc(50% - var(--track-offset));
    transform: scale(1.5);
}

This creates a new pseudo-element off of the .progress class, and gives it it’s visual appearance. Once added, the indicator thumb should live in the center progress element. We’re using the --track-offset variable to position the thumb correctly by taking into consideration the dimensions of the track.

⚠️ I’m also increasing the size of the thumb to using scale() so that its size in the DOM is still relative to the --size variable. This just means a little less maths for us to worry about when setting the value for --track-offset. Using scale() makes it easy to change the size of the element without causing a shift in the DOM.

The next step is to use the color-mix() function again to create a dark red from the base red color. Add the following to your :root rule.

:root {
    # your other CSS variables

    --red-dark: color-mix(in srgb, var(--red), var(--black) 60%);
}

Your progress indicator should look less like a UI widget and more like a dartboard:

Let’s position the thumb on to the track.

.progress::before {
  # rest of properties

    translate: calc((var(--radius) - var(--track-offset)) * cos(var(--angle)))
      calc((var(--radius) - var(--track-offset)) * sin(var(--angle)));
}

This is probably the gnarliest piece of CSS in this entire article. It isn’t anywhere near as complex if we break it down in half. Here’s the first half:

calc((var(--radius) - var(--track-offset)) * cos(var(--angle)))

This uses a little trigonometry to calculate the position of the thumb based on the current angle (which will be tied to the scroll progress) and the radius of the circle. The cos() function is used to determine the horizontal value of the position.

The second half of the value is identical, except we’re using the sin() function to determine the vertical position of the indicator:

calc((var(--radius) - var(--track-offset)) * sin(var(--angle)))

⚠️ I’m not going to use this article as an introduction into trigonometry, but I can point you in the direction of some amazing resources:

Trigonometric functions in CSS

Trigonometric functions in CSS and JavaScript: Beyond Triangles

You may have noticed that I’ve specified a variable, --angle that I haven’t yet defined. Because we’ll be animating the --angle we need to explicitly define it using the @property rule, much like we did for the --progress property. The only difference is that we’ll need to specify a different syntax value. Instead of <percentage> the value will need to be <angle> .

@property --angle {
    syntax: '<angle>';
    inherits: false;
    initial-value: -90deg;
}

By setting the initial value to -90deg we ensure that thumb is placed at the 12 o’clock position on the progress indicator.

Your indicator should now look like this:

The next step is to create the animation for the thumb and then bind the animation timeline to the scroll position of the page.

Let’s start by creating a new animation:

@keyframes rotate {
    0% {
        --angle: -90deg;
    }

    100% {
        --angle: 270deg;
    }
}

Over the course of the entire animation, the thumb will rotate 360 degrees, performing a full revolution over the progress element.

Finally we need to add the following two properties to the thumb:

.progress::after {
    # other CSS properties

    animation: rotate linear 1ms;
    animation-timeline: scroll(nearest block);
}

Doing so applies the rotate animation to our thumb and binds it to the scroll position.

Everything should now work flawlessly:

Wrapping up

I created this progress indicator specifically to become more familiar with the amazing tools that CSS has shipped in the last couple years. Hopefully you learnt just as much from this lesson as I did making it.

There were other CSS features I wanted to explore, like popover and :has but I couldn’t find a way to fit them in with this animation. If people find this article interesting, I might try and create more little changes to the Component Odyssey platform, using cutting-edge CSS features.

By wary, that because a lot of the CSS features I’ve covered are still very new, check the browser support before using them in production. If they’re not supported in one or more browsers, but you’re desperate to use them, then use a progressive enhancement strategy to ensure that those with compatible browsers get the full experience, while still offering users of unsupported browsers a solid baseline experience.

If you enjoyed this article, and would love to learn more about Component Odyssey or other cool web development tips, then consider subscribing to the newsletter.

Resources

Getting practical with scroll progress timelines

We can finally animate css gradients

Fitness inspired loaders

MDN: @property at-rule

MDN: Animation Timeline

Navigating Your Component Journey with Component Odyssey

Andrico — Tue, 28 Nov 2023 13:00:00 +0000

The Complexities of Building Your Own Component Library

At some point, every web developer has thought about creating their own component library, and for good reason.

Building a library is an opportunity to express your creativity, learn to develop more accessible web experiences, contribute to the open source community, upskill yourself for a better-paid role, or simply become a more well-rounded web developer.

A component library is also a valuable tool to have in your team, as reusing the same components over several projects is a great way of saving your team lots of time and effort.

But building a component library is no easy task in part due to how complex the web development landscape has gotten over the years. With so many frameworks and runtimes to choose from, how do you know which is the best to pick for your component library? Picking one may very well lock your components out from being used with others.

Ultimately, you want your end-users to have enjoyable web experiences, you want your library consumers to easily build interfaces with your library, and you want a smooth development experience to build, test, and publish your library.

That’s what Component Odyssey will teach you to do.

Introducing Component Odyssey

Component Odyssey will help you navigate your component library journey.

In Component Odyssey, I’ll be teaching you how to build a component library with a minimal tech stack. You’ll learn how to avoid locking yourself into the shiny framework of the month, and you’ll write components that work across any JavaScript framework.

So why should you embark on your Component Odyssey?

You’ll become a more future-proof web developer

The core technologies introduced in Component Odyssey are baked into the browser, meaning that as you become more familiar with these tools, you’ll also become more familiar with building for the browser as a whole. The skills you learn in this course will serve you in almost any front-end project you work on in the future.

You’ll build components that your users will love

You won’t just be writing components in Component Odyssey, you’ll learn how to style, test, type, and publish them. These are all important in ensuring that the components you ship are robust and user-friendly.

You’ll boost your career opportunities

Building a component library is an excellent way to contribute to the open-source community, which improves your chances of working on other cool projects, or landing some wonderful job roles. Just sharing the library you’ve built from scratch with a prospective job employer will help you stand out from the crowd of applicants.

I did just this when I interviewed for my current job, and the interviewers loved my component library:

You’ll learn to do more with less

The components you’ll be building in Component Odyssey are built using web components, the browser’s built-in way to create reusable components. You don’t need a framework to write and publish them, and as a result, you’ll be able to deliver components that work across the web.

Web components aren’t new or radical, loads of large companies use web components to power their web experiences, like Microsoft, Adobe, and NASA.

You’ll also be introduced to other tools and technologies that lean into the browser’s built-in capabilities, which means that you, and your library consumers, can avoid complex build systems to run your code.

The Component Odyssey platform

Component Odyssey is a self-paced and highly interactive course, so there’ll be plenty of hands-on coding for you to do. There are also no deadlines, so you can go through the entire course on your own time.

Every lesson is accompanied by written content and a video, and the course is jam-packed with code examples, exercises, and projects.

Most lessons contain some interactive runnable code like the one below:

Other lessons contain in-depth exercises for you to download and run locally on your computers.

Most importantly, throughout the entire course, you’ll be slowly building out a functioning component library, with multiple components, a testing strategy, and some handy workflow automation.

You won’t be alone either, starting Component Odyssey will also give you access to a Discord community. You’ll be able to share the amazing things you’ve built, get help on any tough challenges you’re facing, and meet other developers on their journeys.

Who should take Component Odyssey?

You don’t need to be an expert web developer to take this course, it’s designed for anyone with some working HTML, CSS, and JavaScript experience. If you’ve built a few interactive websites and have a few months of web development experience, then you’re golden.

Component Odyssey doesn’t cover the absolute basics of HTML, CSS, and JavaScript, but it does build on top of those browser fundamentals, so you can build great components without a framework.

Is Component Odyssey worth taking if you’re a seasoned developer? Absolutely, there’ll still be so much for you to gain, as you’ll be diving deep into web components, and you’ll learn how to style, test, and publish them.

About me

As for me, I’m Andrico, a web developer based in London. I’ve been a professional web developer for the last 7 years and have worked across a bunch of startups. I’m currently building design-to-code automation and design system automation at Anima.

In previous roles, I was a front-end champion, where I ran workshops about front-end development, web accessibility, and front-end testing.

I’ve also built a few personal projects on the side like Cali Skills, a bodyweight fitness tracker, and Handstand Journey, a popular mobile application designed as a fun introduction to the exciting world of arm balances.

I’m also the creator of a2k, the Windows 2000-inspired web component library. I’ve also contributed to several open-source projects, most notably the Open UI, where I led the site rewrite from Gatsby to Astro.

Component Odyssey is everything I’ve learnt about web development and component library development condensed down into a fun and highly interactive course.

Fun fact: Before starting my career as a web developer, I worked in the family chip shop in South-East London (it’s still going strong, so stop by for some fish and chips!).

Register your interest

Component Odyssey is still in development, with more release details coming out in the following months. If you’d like to be notified about Component Odyssey news, including beta testing details + launch discounts, then please register your interest.

Gather User Feedback On Any Website with Hermes WC

Andrico — Mon, 13 Nov 2023 19:26:26 +0000

Nothing’s more important for indie developers than gathering user feedback, especially for early-stage projects that are likely to undergo massive changes regularly. At the same time, many developers don’t need the kind of enterprise-level feature set that many of the most well-known customer platforms offer.

For the last few months, I’ve been creating Component Odyssey, a course designed to help developers build and publish components that work everywhere. As I’m gearing up to open my platform to beta testers I need a free, quick, and easy mechanism to gather user feedback.

I want an unintrusive widget that I could drop into my page which students could use to send feedback at any point during the course to flag bugs and unclear course content. Given that the Component Odyssey platform is built on top of SvelteKit, it would be easy for me to create a Svelte component that fires data to an endpoint.

But I wanted to practice what I teach, and a form widget feels like a great candidate for a web component as the browser already has great support for building forms. On top of that, a form widget isn’t a novel piece of functionality and certainly shouldn’t rely on a specific framework to work. The idea of writing a simple, but very useful component, that I can’t then use in my React and VanillaJS projects feels like a waste of energy.

That’s what led me to build Hermes WC. With Hermes WC, you can easily add an interactive form that dispatches the form data to a location of your choice.

Here’s a demo of Hermes WC in action, sending feedback to Discord, Slack, and an HTTP endpoint.

So let’s see how you can add Hermes WC to your own projects

Step 1: Installing Hermes WC

Begin by installing Hermes WC:

npm install hermes-wc

Step 2: Adding the Hermes WC markup

Once you’ve done that, you can update your webpage with the following markup:

<hermes-wrapper>
    <form class="hermes-stack" data-hermes="form">
        <sl-input name="feedback" label="Feedback" placeholder="e.g., Not clear enough"></sl-input>
        <hermes-score-input
            name="score"
            label="Score"
            score-count="5"
            start-helper-text="Low Score"
            end-helper-text="High score"
        ></hermes-score-input>
        <div class="hermes-row">
            <sl-button data-hermes="close">Close</sl-button>
            <sl-button variant="primary" type="submit">Submit</sl-button>
        </div>
        <p data-hermes="helper-text" />
    </form>
</hermes-wrapper>

There’s heaps of stuff going on here, so let’s break it down, element by element.

Hermes Wrapper

This is the component that’s responsible for handling the layout of the Hermes form. It mainly handles the form’s open and close states, while also placing a button on the right hand side of the page.

Form

This is the form element that’s in charge of listening and reacting to the submit event. A form element with the attribute data-hermes="form" is required.

SL Input

Because Hermes WC uses a standard HTML form element, we can use any old HTML form controls as children and their values will be captured in the submit event. As a result, I’m using the Shoelace library to render some pre-styled and accessible components.

Hermes Score Input

This is an additional web component that Hermes WC provides. It renders a horizontal radio button group with some attributes for helper text.

SL Button

This is a button provided to us by Shoelace. The button on the left has a data-hermes="close" attribute, which is used to close the feedback widget.

The button on the right has an attribute type="submit" and is used to submit the form when it’s clicked.

Whatever else you want…

Like I mentioned earlier, because Hermes WC works with HTML forms, you can use any HTML form control to build your form.

Step 3: Import the styles into your page

To apply the default styles to Hermes WC, go ahead and import the styles into your project:

<link rel="stylesheet" href="path/to/node_modules/hermes-wc/src/style.css" />

Step 4: Initializing the Hermes WC form

With the markup written, you’ll need to add a small splash of JavaScript to initialize the form.

import { DiscordSubmissionAdapter } from 'hermes-wc/src/submission-adapters/discord.js'
import { initializeHermesForm } from 'hermes-wc/src/index.js'

initializeHermesForm({
  submissionAdapters: [new DiscordSubmissionAdapter({
    webhookUrl: 'your webhook url'
  })],
  submissionCompleteCallback: (response) => { // handle the response }
})

Running initializeHermesForm will do a few things under-the-hood, like set up event listeners and register the web components.

You can then provide one or more submission adapters which send your data to a destination of your choice. As of now, Hermes WC supports sending feedback to Slack, Discord, or an HTTP GET endpoint. You can even create your own adapters.

You can also pass a function through to the submissionCompleteCallback option, which gets fired when all of the submission requests are settled. You’ll be given the response of all the promises, which you can use to display a success or error message to your users.

Wrapping Up

I hope you find a tool like Hermes WC useful. I plan to open source a bunch of the tools I create for Component Odyssey. Other tools include Sandpack Lit.

If you’d like to learn how to build your own components that work anywhere, regardless of framework, then please register your interest for my course, Component Odyssey.

Writing Components That Work In Any Frontend Framework

Andrico — Mon, 06 Nov 2023 13:00:00 +0000

The browser has a built-in way of writing reusable components in the form of web components. They’re an excellent choice for building interactive, and reusable components that work in any frontend framework. With that said, writing highly interactive and robust web components isn’t simple. They require a lot of boilerplate and feel much less intuitive than the components you may have written in frameworks like React, Svelte, and Vue.

In this article, I’ll give you an example of an interactive component written as a web component, and then refactor it using a library that softens the edges and removes heaps of boilerplate.

Don’t sweat if you’re not familiar with web components. In the next section, I’ll do a (very brief and limited) overview of what web components are, and what they’re made out of. If you have some basic experience with them, you can skip the next section.

What are web components?

Before web components, the browser didn’t have a standard way of writing reusable components. Many libraries solve this problem, but they often run into limitations like performance, interoperability, and issues with web standards.

They’re a technology made up of 3 different browser features:

Custom elements
Shadow DOM
HTML Templates

We’ll do a quick crash course of these technologies, but it’s by no means a comprehensive breakdown.

Custom Elements

With Custom Elements you can author your own custom HTML elements that you can reuse across your site. They can be as simple as text, images, or visual decorations. You can push them further and build interactive components, complex widgets, or entire web applications.

You’re not just limited to using them in your projects, but you can publish them and allow other developers to use them on their sites.

Here are some of the reusable components from my library A2K. You can see that they come in all shapes and sizes, and have a range of different functionalities. Using them in your projects is similar to using any old HTML element.

Here’s how you’d use the progress element in your project:

<!DOCTYPE html>
<html>
    <head>
        <title>Quick Start</title>
        <meta charset="UTF-8" />
    </head>

    <body>
        <!-- Use web components in your HTML like regular built-in elements. -->
        <a2k-progress progress="50" />

        <!-- a2k web components use standard JavaScript modules. -->
        <script type="module">
            import 'https://cdn.jsdelivr.net/npm/@a2000/progress@0.0.5/lib/src/a2k-progress.js';
        </script>
    </body>
</html>

Once you’ve imported the third-party scripts, you can start using the component, a2k-progress in this case, just like any other HTML element.

If you’re building your own web components, there’s virtually no limit to how complex you can make your custom elements. I recently created a web component that renders a CodeSandbox code editor in the browser. And because it’s a web component, you can use it in any framework you like! If you’d like to learn a little more about that, you can read more here.

Shadow DOM

If you have a working knowledge of CSS, you’ll know that vanilla CSS is scoped globally. Writing something like this in your global.css:

p {
    color: tomato;
}

Will give all p elements a nice orange/red color, assuming that no other, more specific CSS selectors are applied to a p element.

Take this select menu for example:

It has a distinct character which is driven by the visual design. You might want to use this component, but if your global styles affect things like the font family, the color, or the font size, it could cause issues with the appearance of the component:

<head>
    <style>
        body {
            color: blue;
            font-size: 12px;
            font-family: system-ui;
        }
    </style>
</head>

<body>
    <a2k-select></a2k-select>
</body>

This is where the Shadow DOM comes in. The Shadow DOM is an encapsulation mechanism that prevents the rest of the DOM from interfering with your web component, this ensures that the global styles of the web application don’t interfere with any components that you consume. It also means that component library developers can author their component with the confidence that they’ll look and behave as expected across different web applications.

There’s a lot more nuance when it comes to the Shadow DOM, as well as other features that we’re not going to touch on in this article. If you’d like to learn more about web components though, I have an entire course (Component Odyssey) dedicated to teaching you how to build reusable components that work in any framework.

HTML Templates

The last feature in our whistle-stop tour of web components features is HTML Templates.

What makes this HTML element different from other elements, is that the browser doesn’t render its content to the page. If you were to write the following HTML you wouldn’t see the text “I’m a header” displayed on the page:

<body>
    <template>
        <h1>I'm a header</h1>
    </template>
</body>

Instead of being used to render the content directly, the content of the template is designed to be copied. The copied template can then be used to render content to the page. You can think of the template element much like the template for a 3D print. The template isn’t a physical entity, but it’s used to create real-life clones.

You would then reference the template element in your web component, clone it, and render the clone as the markup for your component.

I won’t spend any more time on these web component features, but you’ve probably already noticed that to write vanilla web components, there are a lot of new browser features that you need to know and understand. You’ll see in the next section that the mental model for building web components doesn’t feel as streamlined as it does for other component frameworks.

A Basic Web Component

Now that we’ve briefly covered the fundamental technologies powering a web component, here’s how to build a hello world component:

const template = document.createElement('template');
template.innerHTML = `<p>Hello World</p>`;

class HelloWorld extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.append(template.content.cloneNode(true));
    }
}

customElements.define('hello-world', HelloWorld);

This is the most simple component one could write, but there’s already so much going on. For someone completely new to web components, and without the background knowledge I provided above, they’re going to be left with a lot of questions, and a lot of confusion.

For me, there are at least two key reasons why web components can be challenging to write, at least within the context of the hello world examples.

The markup is decoupled from the component logic

In many frameworks, the markup of the component is often treated as a first-class citizen. It’s often the content that gets returned from the component function, or has direct access to the component’s state, or has built-in utilities to help manipulate markup (like loops, conditionals, etc).

This isn’t the case for web components. In fact, the markup is often defined outside of the component’s class. There’s also no built-in way for the template to reference the current state of the component. This becomes a cumbersome limitation as the complexity of a component grows.

In the world of frontend, components are designed to help developers reuse markup in several pages. As a result, the markup and the component logic are inextricably linked, and so they should be colocated with one another.

Writing a web component requires understanding all of its underlying technologies

As we saw above, web components are made up of three technologies. You can also see in the hello world code snippet, that we explicitly need to know and understand these three technologies.

We’re creating a template element and setting its inner HTML
We’re creating a shadow root, and explicitly setting its mode to ‘open’.
We’re cloning our template and appending it to our shadow root
We’re registering a new custom element to the document

There’s nothing inherently wrong with this, since web components are supposed to be a “lower-level” browser API, making them prime for building abstractions on top of. But for a developer coming from a React or a Svelte background, having to understand these new browser features, and then having to write components with them can feel like too much friction.

A more advanced web component

Let’s take a look at a more advanced web component, a counter button.

You click the button, and the counter increments.

The following examples contains a few extra web component concepts, like lifecycle functions and observable attributes. You don’t need to understand everything going on in the code snippet. This example is really only used to illustrate how much boilerplate is required for the most basic of interactive interfaces, a counter button:

const templateEl = document.createElement("template");

templateEl.innerHTML = `
<button>Press me!</button>
<p>You pressed me 0 times.</p>
`;

export class OdysseyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    this.shadowRoot.appendChild(templateEl.content.cloneNode(true));
    this.button = this.shadowRoot.querySelector("button");
    this.p = this.shadowRoot.querySelector("p");
    this.setAttribute("count", "0");
  }

    // Note: Web components have lifecycle methods,
  // If we're setting event listeners when the component is added to the DOM, it's our job to clean
  // them up when it gets removed from the DOM
  connectedCallback() {
    this.button.addEventListener("click", this.handleClick);
  }

  disconnectedCallback() {
    this.button.removeEventListener("click", this.handleClick);
  }

  // Unlike frameworks like React, Web Components don't automatically rerender when a prop (or attribute)
  // changes. Instead, we need to explicitly define which attributes we want to observe.
  static get observedAttributes() {
    return ["disabled", "count"];
  }

  // When one of the above attributes change, this lifecycle method runs, and we can
  // react to the new attribute's value accordingly.
  attributeChangedCallback(name, _, newVal) {
    if (name === "count") {
      this.p.innerHTML = `You pressed me ${newVal} times.`;
    }
    if (name === "disabled") {
      this.button.disabled = true;
    }
  }

  // In HTML, attribute values are always strings. This means that it's our job to
  // convert types. You can see below that we're converting a string -> number, and then back to a string
  handleClick = () => {
    const counter = Number(this.getAttribute("count"));
    this.setAttribute("count", `${counter + 1}`);
  };

Web component authors, we need to consider a lot of things:

Setting up the shadow DOM
Setting up the HTML templates
Cleaning up event listeners
Defining properties that we want to observe
Reacting to properties when they change
Handling type conversions for attributes

And there are still so many other things to consider that I haven’t touched on in this article.

That isn’t to say that web components are bad and that you shouldn’t write them, in fact, I’d argue that you learn so much about the browser platform by building with them. However, I feel that there are better ways to write components if your priority is to write interoperable components in a much more streamlined and ergonomic way.

Writing web components with less boilerplate

As I mentioned earlier, there are a lot of tools out there to help make writing web components much easier. One such tool is called Lit, which is developed by a team at Google. Lit is a lightweight library design to make writing web components simple, by removing the need for the boilerplate we’ve already seen above.

As we’ll see, Lit does a lot of heavy lifting under-the-hood to help cut down the total lines of code by nearly half! And because Lit is a wrapper around web components and other native browser features, all your existing knowledge about web components is all transferable.

To start seeing how Lit simplifies your web components, here’s the hello world example from earlier, but refactored to use Lit instead of a vanilla web component:

import { LitElement, html } from "lit";

export class HelloWorld extends LitElement {
  render() {
    return html`<p>Hello World!</p>`;
  }
}`

customElements.define('hello-world', HelloWorld);

There’s a lot less boilerplate with the Lit component, and Lit handles the two problems I mentioned earlier, a little bit differently. Let’s see how:

The markup is directly defined from within the component class. While you can define your templates outside of the class, it’s common practice to the template as the result of the render function. This is more inline with the mental model presented in other UI frameworks, where the UI is a function of the state.
Lit also doesn’t require developers to attach the shadow DOM, or create template and clone template elements. While having an understanding of the underlying web component features will help when developing Lit components, they’re not required for getting started, so the barrier for entry is much lower.

So now for the big finale, what does the counter component look like once we’ve migrated it over to Lit?

import { LitElement, html } from "lit";

export class OdysseyCounter extends LitElement {
  static properties = {
        // We define the component's properties as well as their type.
        // These properties will trigger the component to re-render when their values change.
        // While they're not the same, you can think of these "properties" as being
        // Lit's alternatives to "observed attributes"
        // If the value is passed down as an attribute, Lit converts the value
        // to the correct type
    count: { type: Number },
    disabled: { type: Boolean },
  };

  constructor() {
    super();
        // There's no need to create a shadow DOM, clone the template,
        // or store references to our DOM nodes.
    this.count = 0;
  }

  onCount() {
    this.count = this.count + 1;
  }

  render() {
        // Instead of using the attributeChangedCallback lifecycle, the
        // render function has access to all of the component's properties,
        // which simplifies the process of manipulating our templates.
    return html`
      <button ?disabled=${this.disabled} @click=${this.onCount}>
        Press me!
      </button>
      <p>You pressed me ${this.count} times.</p>
    `;
  }
}`

The amount of code we’re writing is cut down by almost half! And this difference becomes more noticeable when creating more complex user interfaces.

Why am I going on about Lit?

I’m a big believer in web components, but I recognise that the barrier of entry is high for many developers. Writing complex web components requires understanding heaps of browser features and the education around web components isn’t as comprehensive as other technologies, like React or Vue.

This is why I think it’s important to use tools like Lit can make writing performant and interoperable web components much easier. This is great if you want your components to work within any frontend framework.

If you’d like to learn even more, this is the approach I teach in my upcoming course Component Odyssey. This course is excellent for anyone that wants to understand how to write components that work in any framework. I do this by covering the absolute basics of web components, before moving on to tools like Lit that simplify the process of writing web components without complicating your development environment. By the end, you’ll learn how to build and publish a component library that works across any frontend framework.

If you want early-bird discount codes for Component Odyssey, then head on over to the site to get notified.

Introducing Sandpack Lit: The Universal CodeSandbox

Andrico — Mon, 23 Oct 2023 15:19:27 +0000

Sandpack was a game-changer back when the team at CodeSandbox officially released it. Thanks to Sandpack, running a CodeSandbox in your browser-based projects was easier than ever. With it, you could open up a little window inside of your application that runs an entirely different application. And you weren’t limited to running simple sites, but entire web applications or Node servers.

If you haven’t directly used Sandpack yourself, you’ve probably been on a site that has for displaying runnable code snippets or code exercises. In fact, the React docs site uses Sandpack for its code exercises.

However, there’s one major problem… CodeSandbox only officially provides a React wrapper for Sandpack. If you wanted to run a CodeSandox from within your project, you’d need to either:

Create your project in React
Create your own wrapper around the sandpack-core library

Introducing Sandpack Lit

With more frameworks than ever to build web applications, it makes sense to offer a drop-in Sandpack solution for frameworks that aren’t React.

Developers could build their own Sandpack wrapper around their favourite frameworks, or the team at CodeSandbox could release official wrappers around each framework, but that feels like a lot of work for a lot of developers.

That’s where Sandpack Lit comes in.

Sandpack Lit is a standalone web component that allows you to add a CodeSandbox to any client-side web application. Let’s see it in action!

Sandpack Lit in action

You’ll see just how easy it is to render a CodeSandbox inside of different projects using different frameworks. I’ll render the same interactive theme picker inside the sandbox

If you want to go ahead and use it yourself, you can begin by installing sandpack-lit:

npm install sandpack-lit

Svelte

If you’re using Svelte, create the following component:

<script>
  import "sandpack-lit/dist/presets/sandpack";
  import "sandpack-lit/dist/themes/odyssey.css";
</script>

<main>
  <h1>Svelte</h1>
  <div class="container">
    <sandpack-preset
      options={{
        closableTabs: false,
        files: { /** files go here */},
        customSetup: {
          "dependencies": {
            "lit": "2.6.1"
          }
        }
      }}
    />
  </div>
</main>

<style>
  .container {
    width: 900px;
  }
</style>

Run and open your development server, and you should see Sandpack working:

Vue

If you’re using Vue, create the following component:

<script setup>
import "sandpack-lit/dist/presets/sandpack";
import "sandpack-lit/dist/themes/odyssey.css";

const files = { /** files go here */ }

const dependencies = {
  lit: "2.6.1",
};

const options = {
  closableTabs: false,
  files,
  customSetup: {
    dependencies,
  },
};
</script>

<template>
  <h1>Vue</h1>
  <div style="width: 900px">
    <sandpack-preset v-bind:options=options />
  </div>
</template>

Kick off your dev server, and you should see Sandpack working:

React

Consuming web components in a React project is a little different to the others, since React doesn’t offer out-of-the-box support for web components. Luckily Sandpack Lit offers a exports a React component that you can use instead:

import { SandpackLitComponent } from 'sandpack-lit/dist/presets/sandpack-react';
import 'sandpack-lit/dist/themes/odyssey.css';

function App() {
    return (
        <div style={{ width: '900px' }}>
            <h1 style={{ textAlign: 'center' }}>React</h1>
            <SandpackLitComponent
                options={{
                    closableTabs: false,
                    files: {
                        /** files go here */
                    },
                    customSetup: {
                        dependencies: {
                            lit: '2.6.1'
                        }
                    }
                }}
            />
        </div>
    );
}

export default App;

Run and open your development server, and you should see Sandpack working:

Vanilla

If you’re opting to not use a framework at all, you can add Sandpack Lit to your project using the following:

<body>
    <div id="app" style="width:900px">
        <h1 style="text-align: center; color: black;">VanillaJS</h1>
        <sandpack-preset></sandpack-preset>
    </div>
    <script type="module">
        import "sandpack-lit/dist/presets/sandpack";
        import "sandpack-lit/dist/themes/odyssey.css";
        const files = /** your files here */

        const sandpackEl = document.querySelector('sandpack-preset');
        const options = {
          closableTabs: false,
          files,
          customSetup: {
            "dependencies": {
              "lit": "2.6.1"
            }
          }
        };

        sandpackEl.options = options
    </script>
</body>

Run your local development server, and you can see Sandpack Lit working without a framework:

So how does Sandpack Lit work across all frameworks? Instead of being built using a framework, I’ve instead opted to use a handy native browser feature called web components.

What the Heck are Web Components?

The browser offers developers a way to write reusable components without needing an external framework. They can create a custom element (with styles, attributes, and more), and use it like any other HTML element.

You can even import and use web components made by other developers!

Nolan Lawson recently wrote about the use cases that web components are best for:

You have some component at the leaf of the DOM tree, it doesn’t need to be rendered server-side, and it doesn’t <slot> any content inside of it. Examples include: a rich text editor, a calendar widget, a color picker, etc. To me, this is the most unambiguously slam-dunk use case for web components.

I feel that this applies perfectly to an embedded code editor, like Sandpack, since a code editor is a highly interactive client-side component that doesn’t rely on the consumer passing down child content.

Real-world usages of Sandpack Lit (Component Odyssey)

While Sandpack Lit is still new, I’ve been using it over the last few months to build the exercises and code examples in my web development course Component Odyssey. Component Odyssey is dedicated to helping developers learn the ins-and-outs of component library development.

I’m using Sandpack Lit to run both browser-based code and Node projects in the browser:

If you’d like to learn build, manage, and distribute your component library in an ever-increasingly complex web development landscape, then register your interest to get an early-bird discount when Component Odyssey releases.

Learn more about Sandpack Lit

You may have noticed that I used the sandpack-preset web component. This is a component that renders a preset configuration of some additional components, ones that render the code editor, ones that render the preview, and one that sets up the shared context. Sandpack Lit also exports these components, so you can have more flexibility. If you’d like to learn more, you can check out the Sandpack Lit GitHub repo.

What’s next for Sandpack Lit?

Sandpack Lit is still in early days, if there are features that you’d like to see added, please add an issue in the GitHub, or try your hand at implementing it yourself. If you like the look of Sandpack Lit, then please leave a GitHub star and share online!

Making your design tokens future-proof

Andrico — Tue, 20 Jun 2023 14:09:42 +0000

Over the last decade, design systems have become a mainstay in many product development teams, and for good reason! Product teams want to deliver value to their users quickly but they also want to provide a consistent experience to their users.

As a result, there’s been a huge increase in the number of products designed to help teams of all sizes manage design systems. Software like Anima, Zeroheight, and Storybook all offer slightly different ways to improve workflows around building and maintaining design systems.

While many tools work at the macro level (like offering teams and stakeholders a way to view guidelines and interact with the components) there are other, more niche tools that teams can use to iron out the finer details.

This is especially true when it comes to managing design tokens. Before we dive into design tokens tooling, let’s review what design tokens are.

What are design tokens?

Design tokens are discrete pieces of data that represent the specific values of a design system. These values are often intentional design decisions made by the product team. These design tokens will then make their way over to the codebase, commonly as CSS variables, but can be represent in many other way.

Let’s look at how design tokens can be used to represent a colour palette.

In Figma, the designer has come up with a colour palette. The primary colour is a Tomato red. Our designer has specifically chosen 12 steps of the Tomato colour, with an alternative palette for the dark theme:

Design system tools may output this information as platform-agnostic data, usually in the form of a JSON object. There might be an additional conversion step where the data is converted into something platform specific, like CSS variables.

--tomato-4: #FFDED6;
--tomato-9: #F55442;
--tomato-11: #D43029;

@media (prefers-color-scheme:dark) {
    --tomato-4: #401A12;
    --tomato-9: #F55442;
    --tomato-11: #FF7D66;
}

button {
  background: var(--tomato-11);
    border-color: var(--tomato-9):
    color: var(--tomato-4);
}

This is what the above styles would look when rendered to the browsers:

Things get messy in the in-between stages where we’re:

Exporting the code to a platform-agnostic object.
Converting that object to something developers can use in their projects.

Just for the sake of example, this is what the platform-agnostic data looks like when exported out of Figma using three popular tools:

Anima

Link to plugin

{
  "tomato-10-dark": {
    "id": "f991b0d7b53deca9",
    "$type": "color",
    "$value": "#ff634f",
    "$description": ""
  },
  "tomato-10-light": {
    "id": "456aff72c86eb003",
    "$type": "color",
    "$value": "#e34236",
    "$description": ""
  }
}

Design Tokens

By Lukas Oppermann

{
  "color": {
    "tomato-10-dark": {
      "description": "",
      "type": "color",
      "value": "#ff634fff",
      "blendMode": "normal"
    },
    "tomato-10-light": {
      "description": "",
      "type": "color",
      "value": "#e34236ff",
      "blendMode": "normal"
    }
  }
}

Token Studio

Link to plugin

{
  "global": {
    "tomato-10-dark": {
      "value": "#ff634f",
      "type": "color"
    },
    "tomato-10-light": {
      "value": "#e34236",
      "type": "color"
    }
  }
}

If a team wants to move away from Token Studio and use Anima instead, we’d need to ensure that the tokens we’re exporting from Token Studio are compatible with Anima’s token format.

It’s highly likely that when migrating from any tool there will be inconsistencies in the data structures. This is because there’s no definitive way of writing design tokens.

Fortunately, the people over at the Design Tokens Community Group have been hard at work creating a design tokens specification, a set of rules and guidelines about what constitutes valid design tokens. It’s a specification that library authors and design system teams can use to ensure that whatever they’re building will be interoperable with the breadth of tooling out there.

While a single design token is usually a small, discrete value. Design systems may have a collection of thousands of design tokens. These design tokens may not be values, but aliases for other design tokens. They may be heavily nested within groups. Multiple design tokens might exist for different themes. At a point, it becomes very difficult for an individual to review a set of design tokens and cross-reference it with the specification.

Having a concrete specification defined not only means that the tools can start formatting their tokens consistently, but it also unlocks improved design tokens tooling that serve the greater design and web development community. A design tokens validator is one such tool, which Anima recently released as a free open-source tool, for anyone to use.

Validating your tokens

With this validator, you’re able to check that your design system’s entire set of design tokens matches the rules of the specification. And if they don’t, the validator provides links to the right part of the specification, to help you understand the problem and how to fix it.

Let’s try it ourselves now with an invalid set of design tokens:

{
  "colors": {
    "red": {
      "100": {
        "$value": "#FFCDD2"
      },
      "200": {
        "$type": "color",
        "value": "#EF9A9A"
      }
    }
  },
  "button": {
    "primary": {
      "color": {
        "$value": "{colors.red.200}"
      },
      "padding": {
        "$type": "dimension",
        "$value": "2em"
      }
    }
  }
}

At first glance, this set of tokens makes sense. We have a handful of colors defined at the top, as well as some component-specific tokens underneath. The color of the button is even an alias to an existing token. There are, however, a small number of issues that might be tricky for an individual to spot.

Let’s begin by opening the site.

Once everything’s loaded, paste in the above tokens.

You’ll see that the validator has flagged several issues:

Why not treat this as an exercise and look to fix the tokens yourself using the validator’s hints (you can also skip to the answers below)

Fixes for the tokens:

Give “colors.red.100” a “$type: “color”
Update “colors.red.200” to have property “$value” and not “value”
Update “button.primary.padding” to have a “$value” of “2rem”, as “em” is not a valid unit.

After updating the tokens with the above values, you can click validate again and the validator should pass! 🙌🏼

For the developers out there, you can even integrate the validator within your projects using the design-token-validator npm package.

Wrapping up

It’s exciting to see the Design Tokens CG specification slowly proliferate into more design tokens tooling. I hope that once the draft officially lands that design system tooling start adopting so designers and developers don’t have to worry about managing compatibility layers across tokens, but about actually building their design system.

If you enjoy the validator, please star on GitHub and share on Twitter

About me

I’m Andrico, a software engineer at Anima. If you enjoyed this piece, then please consider following me on Twitter, or checking out my personal blog.

The design tokens validator is just one of many tools created by Anima to help product teams improve their design system workflow.

Check out Anima if you'd like to:

Convert styles to design tokens inside Figma
Push generated tokens directly to GitHub
Pull code updates back into Figma

Introducing a2k - A UI library designed to capture that retro 2000s feeling

Andrico — Thu, 01 Dec 2022 21:34:19 +0000

Take a look at a new 2000s-inspired component library. You’ll learn what a2k is, how it’s been built, and how to use it to build retro applications in React, Vue, vanilla, or your favourite frontend framework.

What is a2k?

a2k is a web component library designed to evoke memories of the early 2000s era of computing.

Why does a2k exist?

To embrace the browser platform

Over the years, the browser has introduced several mechanisms to allow developers to create reusable custom components. These are known as web components. Web components are a native way of reusing custom markup across several places in a codebase, or different codebases entirely.

Web components make it easy to author components for others to use in their own projects. As a consumer, it requires little more than to import a component and then use it like an HTML element.

This makes it a great tool for building a2k.

To create a framework agnostic component library

You may be familiar with frameworks like React and Vue, which popularised the notion of building user interfaces using components. While these tools exist for more than writing and using components, there is an entire ecosystem dedicated to component libraries. MUI and Chakra UI, are both excellent examples of React component libraries that allow developers to build complex user interfaces from battle-tested components.

There is a catch when it comes to writing components using frameworks. Libraries written in React can’t be used in Vue projects and vice versa. In fact, component libraries written in Vue 2 aren’t necessarily compatible with Vue 3. Building a2k using web components means that we have an interoperable way of building retro user interfaces that won’t be obsolete by the next cycle of frontend tooling

To put the fun back in uhh.. fruntend (😅) development

a2k is designed to evoke a feeling of nostalgia and to help others form the foundations of their own retro web applications. For me, this alone is a motivating enough reason to pursue a project.

Andricos2000 is a fun example of a project that uses a2k to build a retro web application

How does a2k work?

Like with many UI libraries, a2k is comprised of a base stylesheet and a suite of fully-functional components

Base Stylesheet

This CSS file has a bunch of jobs. First off, it sets the base styles, like the default font family, loading cursor assets, setting the default element appearances, etc.

The file also defines some utility classes. For common styles that don’t need to be entire components, we can create utilities that we can reuse across our entire application.

Finally, the CSS file also creates the variables which we can use throughout our entire site. It also defines the variables for individual components. The file also applies the default values for these variables, which can be overridden by the user.

Component Suite

a2k exports a growing number of different web components. Many of these components can be categorised based on complexity or expected usage.

Layout UI

These are components with no built-in interactivity but are used to help build component/application layouts. One example is the a2k-panel, which is a box that applies some retro styling. It can be used alone, but it’s also used to build more complex components, like the a2k-window.

Behavioural UI

These are the common UI patterns, like buttons, select menus, and progress bars. You can use these components any place you’d use the native counterpart with the same behaviour but with the added benefit of cool retro UI.

Components like a2k-button offer style and functionality outside of the box. More complex UI components like a2k-select are built with the ARIA authoring practices in mind, so they’re accessible alternatives to the native browser components.

Composite Components

These are complex components that are built on top of other layout or behavioural components.

The a2k-taskbar is one such example. The taskbar is a complex UI pattern that’s built using a mix of HTML, a2k-button, a2k-icon, and a2k-panel.

These components are highly specialised and you will likely not need to use them frequently. They might be used to build desktop-inspired UIs. You can even build your composite components using the building blocks that a2k provides.

Getting started with a2k

Because a2k is built using web components, it’s easy to integrate with different frameworks, like Vue and React.

I’ve provided some handy guides below to get a2k up and running using different frameworks; vanilla JS, Vue, and React.

Vanilla JS

To begin, we’ll need to do a little repo setup. We’ll be using Web Dev Server, which we’ll use to run a local development server. This will allow us to easily use the node modules we install via npm.

We’ll also use Lit, which is a simple library to help build web components. While we won’t use this library directly, a2k uses it under the hood so we need to ensure that it’s available.

Start by initialising your project using:

npm init -y

You can now install the necessary node modules:

npm i @a2000/styles @a2000/select @web/dev-server lit

In the root of your project, create an index.html file with the following contents:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>a2k web components</title>
  </head>
  <body>
    <div style="width: 300px">
      <a2k-select placeholder="Favourite OS">
        <option>Windows</option>
        <option>Linux</option>
        <option>Apple</option>
      </a2k-select>
    </div>
  </body>
</html>

Lastly, kick off your development server with the following script:

npx wds --node-resolve --open --watch

Open up your site at localhost:8000 and you should be greeted with some unstyled HTML. This is completely expected as we haven’t linked up the a2k styles yet. We also haven’t registered our web components either, so the browser will display the fallback content. In this case, the contents are the three option elements.

Inside the head element add the following HTML tag:

<link rel="stylesheet" href="./node_modules/@a2000/styles/a2k-styles.css" />

If you jump back to localhost:8000, you can see that the font family and the sizes of the HTML have changed, which shows that the stylesheet is being imported properly.

The final step is to register our web component. We do this by simply calling importing the script that a2k uses to register the select component. At the bottom of your body element, paste the following:

<script type="module">
  import "@a2000/select/a2k-select.js"
</script>

Jump back to localhost:8000, and you should see a fully functioning select component.

And that’s it!

The a2k web components are working in your basic HTML file. Try and experiment with some of the other components laid out in the documentation. If you come up with anything cool, please share it with me on Twitter or Mastodon.

Vue

Because Vue scores a perfect score in the Custom Elements tests, integrating web components in your Vue project should be a breeze. Let’s see how we can do this with a2k.

In a new directory, run the following script:

npm init vue@latest

The terminal will prompt you with a few options but for the sake of this tutorial, you can choose no for all of them.

Move into the directory and install all the necessary dependencies:

cd vue-example
npm i @a2000/styles @a2000/select lit

Once that’s done, you can kick off your dev server with the following

npm run dev

Begin by updating your App.vue so that it looks like the following:

<script setup></script>

<template> </template>

<style scoped></style>

If you open up localhost:5173 in your browser, you should see an empty page. Let’s go ahead and add some web components.

First off, add the following to your index.html's head component:

<link rel="stylesheet" href="./node_modules/@a2000/styles/a2k-styles.css" />

Update your App.vue file to import and render the a2k select component:

<script setup>
  import "@a2000/select/a2k-select.js"
</script>

<template>
  <div style="width: 300px">
    <a2k-select placeholder="Favourite OS">
      <option>Windows</option>
      <option>Linux</option>
      <option>Apple</option>
    </a2k-select>
  </div>
</template>

<style scoped>
  a2k-select {
    color: black;
  }
</style>

Jump back to localhost:5173 and you should see the select menu in the browser. That’s it!

React

Sadly, React’s support for custom elements isn’t as comprehensive as Vue’s, so we’ll have to do a little extra work to get this working.

Let’s create a react project by running the following in your terminal:

npx create-react-app react-example

let’s install the necessary packages:

npm i @a2000/styles @a2000/select lit @lit-labs/react

The packages we’re installing are pretty much the same as earlier, but with an additional package, @lit-labs/react. This is a handy package by the Lit team to integrate web components with React.

Clean out your App.js file so it looks like the following:

function App() {
  return <div></div>
}

export default App

Kickoff the dev server using:

npm run start

Your localhost:3000 should be empty at this point.

Go ahead and create a new file in your src directory called SelectComponent.js with the following contents:

import * as React from "react"
import { createComponent } from "@lit-labs/react"
import { A2kSelect } from "@a2000/select"
import "@a2000/select/a2k-select.js"

export const SelectComponent = createComponent({
  tagName: "a2k-select",
  elementClass: A2kSelect,
  react: React,
  events: {
    onactivate: "activate",
    onchange: "change",
  },
})

Without getting too much into the weeds, I’m simply following the documentation for the createComponent API. I am however importing twice from @a2000/select twice. Once to access the A2kSelect component class itself, the second to register the custom element to the window. In the future, I’ll look to simplify this process.

This file exports a component which is a wrapper around the web component. The wrapper ensures that any props and events are handled correctly as they’re passed through to the custom element.

Next, let’s import our styles and use our component. Clear out App.js and replace it with the following:

import "@a2000/styles/a2k-styles.css"
import { SelectComponent } from "./SelectComponent"

function App() {
  return (
    <div style={{ width: "300px" }}>
      <SelectComponent placeholder="Favourite OS">
        <option>Windows</option>
        <option>Linux</option>
        <option>Apple</option>
      </SelectComponent>
    </div>
  )
}

export default App

For the most part, the markup looks very similar to the vanilla and Vue examples, so everything should look familiar to you. Jump back into your browser and have a little play with the components. Everything should be working as expected.

How can I support a2k?

a2k is still a work in progress, so any feedback is welcome. If you run into any problems while following the set-up guides, please open a GitHub issue.

Other ways you can support the library is by using a2k in your own projects and requesting the changes and features you’d like to see.

Finally, if you enjoyed the article and want to show a little support. You can simply give a2k a star on GitHub.

What does the future look like for a2k?

I’m nowhere near finished building a2k, there’s still much more I’d like to add in the near/long-term future. Some of the cool things I’d like to add include:

Support for server-side rendered components using declarative shadow DOM.
More components
Improved customisation
React components for each component

I’d also like to use a2k as a springboard for any cool and interesting ideas that I have. I’m also happy for others in the web community to contribute with some great ideas too.

Thanks for reading, and I hope that you have a lot of fun using a2k in your own projects.

Create a Borderlands-style skill tree in 5 minutes

Andrico — Wed, 21 Aug 2019 06:36:05 +0000

How to combine your two favourite things to make an exciting and engaging experience for your users.

Growing up, I spent my spare time doing what most programmers did; played video games every waking moment. I loved Adventure games and what a time sink they were; if time was the Mary Rose, and I was the French, my artillery were games like Kingdom Hearts, Ōkami, and Borderlands.

Why did I, and others, spend so much of our spare time exploring, surviving, dying, and (so, so much)grinding? Hundreds of factors contribute toward making an engaging experience, but the one I'm going to focus on is the notion of progression.

The idea of gamnification isn't new, with many popular applications (like todoist, or challenge timer) incorporating some sort of progression scheme to make us, the consumer, use their app, give them money, and hand over our personal data. So I decided to go about my way of enabling others to do just that, through beautiful skill trees! Note: I expect neither money nor data from those using my personal skill trees.

The last few weeks have seen me toil away to create what I hope to be a pleasant plug'n'play React package to help you create exciting skill trees. You can test it yourself by following the tutorial. I hope it to be a frictionless experience.

We hope to have something resembling the skill tree below.

https://thepracticaldev.s3.amazonaws.com/i/sn9tgrqpv98tm4ftqvqx.png

Grab the starter repo by using git clone git@github.com:andrico1234/borderlands-skill-tree.git

Move into the directory and run the starting script, yarn start. Give the site a whirl, you'll see nothing but the Borderlands logo and environment.

beautiful-skill-tree exposes three components: the SkillProvider, SkillTreeGroup, and the SkillTree components.

SkillProvider: This takes in no props and supplies the children with the skill tree's context. This puppy handles all of the global data related to the skill tree.

SkillTreeGroup: Is more involved in that it can take an optional theme property, where we can pass in some custom styling, to make our skill tree feel very Borderlands. The SkillTreeGroup also uses the children-as-a-function pattern to give us access to some imperative api functionality, such as skill tree reset, selected skills counter, etc. We don't need to worry about any of those for the scope of this article.

SkillTree: This is the most exciting of the package's exports, unless you're a sucker for typings (which are also exported, for all you TS fans). The SkillTree doesn't take any children but requires 3 props: treeId, title, and data. The treeId should be an id that's unique to each skill tree, but should be persistent across user sessions as this is used as the key for getting and setting the data to local storage. I'm not going to explain what the title prop does, I'll leave you to experiment. The data is the mixing pot of the application. You'll pass in your skill tree data structure which the app will use to render a beautiful-skill-tree. Let's get a real basic tree going before we move on to our multi-tree, multi-branch Borderlands spectacular.

In App.tsx, import the 3 components like so:

import { SkillProvider, SkillTreeGroup, SkillTree } from 'beautiful-skill-tree';

Place it underneath your img tag, outside of the image's container div, but within the outer div. Add the SkillProvider, passing the SkillTreeGroup as a child. Before you do the same with the SkillTree, remember that as SkillTreeGroup uses function-as-a-child pattern, you'll need to render a function that returns the child components. Return a single SkillTree and give it a treeId and a title prop. Pass an empty array into the data prop so your App.tsx looks like this.

function App() {
  return (
    // <div>
    //  <div headercontent />
        <SkillProvider>
          <SkillTreeGroup>
            {() => {
              return (
                <SkillTree treeId="basic-birch" title="First Skill Tree" data={[]} />
              )
            }}
          </SkillTreeGroup>
        </SkillProvider>
    // </div>
  );
}

Go to localhost:3000 to see the application running. You should see the logo, background, and a grey rectangle. If you're running into any errors, go through the introduction again and check to see if there any syntax error or incorrect imports.

Next, let's create a real basic tree. Just 3 items that move in a linear line. The data structure for data looks like this:

type Skill = { 
    id: string;
    icon?: string;
    title: string;
    tooltip: {
      description : string;
    },
    children: Skill[];
}

Each skill requires four properties, with one being optional. You should also notice that the children property is a recursive type, meaning that it takes an array of the same data structure, which it uses to render the children of the skill. This can go on infinitely, and make for some real complicated, winding trees. I'll create the first skill for you, and I'll trust you with carrying on for the next two items.

const data = [
  {
    id: 'first-skill',
    title: 'The root node',
    tooltip: {
      description : "The parent node, all of the descendants will be locked until it's selected",
    }
    children: [
      // rinse and repeat; always repeat.
    ]
  }

Add the above snippet to the App.tsx file, and replace the empty array inside of the SkillTree's data property with our data definition. Load your page, and you should have an interactive node. Give it a hover and a click and it should be reacting to your actions. If things are working, then I'll task you with creating two (or more) child nodes. Experiment with children and sibling lengths, to see what you can come up with. (If you also happen to break my precious package, leave me a GitHub issue so I can patch things up).

Once you're comfortable with creating a skill tree, let's go ahead and create our Borderlands skill tree. Fortunately, I've done all of the tedious work for you and have already created the data structures and accumulated the images.

You'll need to import the three trees from the data file, which can be done via

import { motion, harmony, cataclysm } from "./data/data";

The next step is creating two additional SkillTrees alongside the current one. You'll need to wrap them in a React.Fragment as your SkillTreeGroup will now be trying to render 3 top level components. Pass in the data accordingly, and if you're unsure, I've posted the code snippet below.

<React.Fragment>
  <SkillTree treeId="motion" title="Motion" data={motion} />
  <SkillTree treeId="harmony" title="Harmony" data={harmony} />
  <SkillTree treeId="cataclysm" title="Cataclysm" data={cataclysm} />
</React.Fragment>

Go ahead and check your web browser, it should be aaallmoost ready. We've got the skills rendered, but the styling feels a little lackluster. It doesn't feel very Borderlands. Fortunately for you, I'm a regular Neil Buchanan and prepared a custom theme. Import the theme and pass it through to the SkillTreeGroup's theme prop. The theme object is export via import theme from './data/theme';. Easy!

https://thepracticaldev.s3.amazonaws.com/i/efhb04w09pc44j8z44dr.png

Once you've done the above, check out the finished product. If you're still not satisfied with the styles, check out the theme object and customise it yourself, there are a bunch of additional attributes whose styles can be adjusted, so just peek into the typings of the package.

I mentioned earlier that there are a few additional properties and values that can be used to tweak the skill tree, so have a mess around yourself, and link me to any cool trees you create. I'd love to add it to the growing list of trees found here. Here's an example of the skill tree that kickstarted this obsession.

I hope you've enjoyed tinkering with the beautiful-skill-tree package. I'm always adding new features and updating, so give it a star on github! You can find an online demo of the borderlands skill tree here

You can find me on Instagram or GitHub if you want to chat code, music or fitness!