Should You Use Web Components in Your Drupal Project?

We cover the benefits and downsides of custom Web Components, and give you some advice on whether you should use them in your Drupal project.

First, what are we talking about when we use the term web components? In the context of Drupal, we could mean a suite of modules, a Twig template that can be inserted into other templates in a theme, and more.

For the purpose of this article, we are talking about custom HTML tags that encapsulate some functionality. You could create a <my-accordion> tag that pulls in all of the JavaScript and CSS it needs to function and then use it wherever you want. Or maybe you want something like <my-social-media-icons> or a custom <my-video-player> that has your analytics bundled in. We won’t cover how to create and use web components. You can learn more about them at, which also contains a large directory of ready-made components to browse and take inspiration from. We also did a video on using web components with Drupal.

Should you use Web Components in your Drupal project? It depends. Once you learn about them, you can be tempted to use them for everything. We get it. They’re neat and new and provide a lot of benefits. However, some downsides could grind your development pace to a halt.

The benefits of web components

In our experience, here are some benefits we have identified.

  • Platform agnostic. Web components are native to the browser. You can build a component once, use it wherever, and don’t have to worry about compatibility with other platforms. Theoretically, you can take your custom tags and start using them. One client uses web components for a global navigation feature that works across several different CMSs and React apps.
  • Backward compatibility. Updating a web component won’t necessarily break previous instances used in Drupal because the tag will stay the same. It works more like an API instead of markup dumped on the page. The internal logic of the component can change without causing compatibility problems.
  • Encapsulating single functionality within the component itself. The component travels with everything it needs to function. Automatically pushing to Google Analytics when someone expands an accordion, for example. Styles and JavaScript can be encapsulated within the components.
  • A unified design system implementation. Because the styles of the component are encapsulated within it, you can enforce brand consistency across different technologies and platforms.
  • No extra libraries are needed. Previously, projects have depended upon libraries like React and Vue.js to provide custom components. You can still use those libraries, but they aren’t required. Though there are frameworks like Lit that help you build and expand components. These enhance the developer experience and are not required for using components.
  • Piecemeal migration out of Drupal 7. If you start building out web components in Drupal 7, those should be transferrable to Drupal 10 or whatever platform you migrate to. This is worth considering if you still have new development to do but want less technical debt.

You might not realize all of these benefits, based on how you’re using web components, but they are there for you to pluck off the tree and enjoy, if you are willing to put in the effort. However, there are some potential downsides.

The downsides of web components

  • They can slow down development time. Web components are still relatively new, and there will be quirks you need to work out. Even developers familiar with the technology will probably need to work at a more deliberate pace, like walking over uneven ground. Many times, it will be easier just to use a Twig template. The front-end skills and paradigms used for Drupal won’t necessarily transfer to developing with web components.
  • Potential performance problems. You’ll need to pay more attention to how your content is structured so a single page doesn’t end up accidentally rendering tens of thousands of DOM nodes. Plus, it’s possible to nest components within components, exacerbating this problem. Every web component you load on a page also increases the on-load JavaScript compilation and execution.
  • They’ll probably need to be part of your JavaScript build system. You have to be using Webpack or another bundling system to get all of the dependencies. If you already have an extensive front-end build process, this won’t be a big deal, but it’s a big lift if you don’t already have one. You could also get around this by writing components that require no outside dependencies (vanilla JavaScript) and, therefore, no build step.
  • They require JavaScript to load. Most visitors will have JavaScript enabled, but you’ll need to weigh the pros and cons of leaving the rest unserved.

How to decide if you will use web components

This comes down to a simple question: do the benefits outweigh the downsides for our project? 

But before you answer this question, you need to honestly assess your ability to realize and capitalize on those benefits.

Are you trying to do the same thing consistently across frameworks? Do you have a Drupal website but also JavaScript web applications or other websites powered by a different CMS? You’ll want to consider web components. But if your only web platform is Drupal, you should think twice about using web components, weighing the downsides carefully. Just use Twig templates instead and start taking advantage of Single Directory Components in Drupal core once they become mature.

To get the biggest benefit, you’ll also need some kind of governance in place. Do you have a team that can enforce brand standards and consistency? Your web component library will likely be tied to some design system, which means there is documentation that needs to be maintained and updated. You don’t want developers each making their own versions of a <my-accordion> component. Consistency doesn’t come automatically. You’ll have to work at it. 

You’ll also want to ask who the audience is for your project. Are you a non-profit whose audience might have laggy internet connections? The extra JavaScript required to load web components might not be worth it.

However, using web components can make sense in smaller projects, even if you are not sharing among different platforms. You might think of an HTML element you wished existed and then create it with minimal styles and little JavaScript. This is the minimalist approach. If your project already has a front-end build process in place and a developer familiar with the standard, using web components for a few targeted use cases can work well.

A final warning about what not to do

Don’t replicate existing HTML tags, like H2 headings or anchor tags. It’s tempting because you get style encapsulation. But do you really want to require JavaScript to render every single heading or link on a page? No. You do not.

Native HTML tags are already native HTML tags. Don’t recreate them.

Besides that, have fun expanding the web. If you want help evaluating your need for custom web components or with your implementation in Drupal, we’d be glad to help.

Get in touch with us

Tell us about your project or drop us a line. We'd love to hear from you!