mdn/web-components-examples: fifteen directories of working custom element code

Fifteen example directories and no build step

The repository is a folder of demonstrations rather than a package. The top level holds .github/, .gitignore, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, README.md and SECURITY.md, and then fifteen directories, one per topic. There is no package.json, no lockfile, no bundler configuration and no test runner anywhere in that list, which tells you the intended way to run any of this is not installing a package.

Instead the README links every example to a live page served from mdn.github.io, so each directory is published as a static page and the browser is the runtime. There is no install command to copy, which is unusual for a repository people are tempted to treat as a starter kit. What you read in the directory is what runs in the page.

The repository is not archived and the last push was on 2026-09-30. It carries no releases, which is the right shape for something that tracks a documentation set rather than shipping code. The declared license is CC0-1.0, a public domain dedication that suits reference material people are meant to copy from, and the primary language is recorded as JavaScript.

Autonomous elements next to customized built-ins

The examples fall into two families, and the split is the most useful thing in the repository. Four are autonomous custom elements that extend HTMLElement: editable-list, edit-word, element-details and popup-info-box-web-component. Each takes its content from attributes or from light DOM children.

The README describes each one closely. editable-list consolidates elements into a list with addable and removable items, where items arrive through a list-item attribute or by typing text and clicking the plus sign. edit-word wraps one or more words so that clicking or focusing the element reveals a text input. element-details shows a box containing an HTML element name and description, taking its structure from a template element that carries its own styling and populating slot elements at runtime. popup-info-box-web-component creates an info icon that opens a popup box when focused, reading its information from attributes.

The other family inverts that relationship by extending an existing HTML interface. expanding-list-web-component creates an unordered list with expandable and collapsible children, and its class inherits from HTMLUListElement rather than HTMLElement, binding custom behaviour to the built-in element through the is attribute. word-count-web-component inherits from HTMLParagraphElement, counts the words inside the element, displays the total inside an attached shadow DOM, and carries an interval that keeps the count current as the content changes. Reading both families side by side shows quickly what customized built-ins give you and what they cost.

One shadow DOM mechanism per directory

Styling gets a directory to itself, which is the reason the repository is organized as a flat list rather than as one demo application.

simple-template is described as a trivial example demonstrating the template and slot elements. slotted-pseudo-element isolates the ::slotted pseudo-element on its own. slotchange builds summary-display around the slotchange attribute and the HTMLSlotElement interface: the element takes a list of possible choices as one slot value and a description for the selected choice as the other, several paragraphs sit inside the element holding every possible description, and clicking a choice gives that paragraph the matching slot attribute so it appears in the second slot. life-cycle-callbacks uses custom-square with l and c attributes to draw a coloured square and adds buttons to create, destroy and change attributes on the element, so the callbacks are visible rather than described. composed-composed-path shows the composed and composedPath properties on the Event object, which decides how far an event travels across a shadow boundary.

Those five cover the shadow boundary and the element lifecycle. Three further directories push into styling and composition that the README text never reaches, which is the gap worth knowing before you start from this repository as a template.

Three directories the README never lists

The README lists twelve examples. The repository holds fifteen directories. host-selectors, shadow-part and popup-info-box-external-stylesheet exist in the tree, and their names alone say a good deal about what is inside them: one covers the host selectors that let a shadow root style its own element, one covers the shadow-part pseudo-element paired with a part attribute on the host side, and the last is the same popup info box idea with its stylesheet kept outside the shadow root rather than inside it. None of the three has a bullet in the README, so a reader working from the README alone would not know they exist.

The second disagreement is smaller and easier to trip over. The repository description points at the MDN documentation for web components under the /Web/Web_Components path, while the README's own first line links to /Web/API/Web_components. Both are MDN URLs covering this material, but they are different paths and only one of them will survive a future documentation reshuffle.

Neither disagreement blocks using any of this. The test is cheap: list the directories yourself and compare the count against the bullets. Fifteen against twelve is what to expect today, and any directory with no matching bullet is worth opening first, because it is the part of the collection the surrounding documentation has not caught up with.

Why this is not a component library

Treating the repository as a starting point for a project is where it disappoints. There is no package.json, so there is no version pinning, no dependency resolution and no way to consume element-details as a dependency. There is no test suite, so an example that works in your browser today says nothing about whether it still works after a browser release. The license is CC0 rather than MIT or Apache, which is right for reference code you intend to copy and awkward if you want attribution preserved in a derived library.

What you are reading is documentation that happens to be executable. Each directory answers one question about custom elements, and the questions are chosen by the MDN documentation team rather than by the needs of any application. That is a strength when you are learning and a liability when you are shipping.

The comparison that matters is against any component library you would otherwise reach for. A library gives you a version number, a build, tests and a support commitment. This repository gives you fifteen correct, minimal, dependency free answers about shadow DOM and lifecycle callbacks that you have to adapt yourself. For finding out what a slot does, or what HTMLUListElement demands of a customized built in element, it is hard to beat. For anything beyond that, start from the MDN documentation and use these directories to check your understanding against code that runs.

Following one example from the README to the live page

The fastest path through the repository is one example end to end. The README establishes the pattern: pick a bullet, follow the live link next to it, then open the MDN documentation page it references.

For a first pass, popup-info-box-web-component is the most complete of the examples the README describes. It is an autonomous custom element that takes its information from its attributes and defines both structure and basic style in an attached shadow DOM, so one directory covers attribute handling, shadow root construction and CSS placement in about as little code as the idea can be expressed in. word-count-web-component makes a reasonable second, because it swaps the interface being extended and adds the interval that keeps a rendered value in step with changed content.

If you want to edit an example, the live pages are published from the repository rather than built by you, and there is no build step to run. Serving the directory you changed from any static file server is the entire workflow. The contribution guidelines are linked from the first line of the README, and the tree also carries CODE_OF_CONDUCT.md and SECURITY.md, so the project has the usual governance files in place even though it publishes nothing to install:

composed-composed-path/
defined-pseudo-class/
edit-word/
editable-list/
element-details/
expanding-list-web-component/
host-selectors/
life-cycle-callbacks/
popup-info-box-external-stylesheet/
popup-info-box-web-component/
shadow-part/
simple-template/
slotchange/
slotted-pseudo-element/
word-count-web-component/

That list is the whole repository, and comparing it against the README bullets is the first thing worth doing with this project.

Editorial conclusion

This is a documentation repository rather than a dependency: useful for learning what a slot, a shadow root or a customized built-in actually requires, useless for pinning a version or shipping a component. The concrete starting point is one directory, popup-info-box-web-component, opened next to its MDN documentation page, with host-selectors and shadow-part left for after the gap between the directory list and the README is understood.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. mdn/web-components-examples on GitHub
4. README