mdn/dom-examples: MDN's Runnable DOM and Web API Demos

What mdn/dom-examples actually is, and who it is for

The README opens with a single sentence of scope: this repository holds "code examples that accompany various MDN DOM and Web API documentation pages." That is the whole product. There is no package on a registry, no importable module, no CLI. The top-level entries are directories named after browser features: abort-api, audiocontext-setsinkid, auxclick, canvas, channel-messaging-basic, contact-picker, css-painting, document-picture-in-picture, drag-and-drop, edit-context, file-system-api, indexeddb-api, navigation-api, pointer-lock, popover-api, screen-capture-api and several dozen more.

The audience follows from that layout. If you are writing MDN documentation and your sample cannot run inside an MDN page, this is where it goes. If you are an application developer trying to understand how a specific Web API behaves before you commit to it, each directory is a small, complete, runnable page you can open in a browser. The value is in the pairing of code and live URL, not in reusable abstractions.

The README is unusually blunt about the second audience being secondary. A note states that examples can be embedded directly in MDN pages with EmbedLiveSample macros or regular Markdown code blocks, that these methods are simpler to maintain because the code lives beside the content, and that you should only add examples to this repository if your example does not easily run on MDN pages for technical or security reasons. In other words, the maintainers treat this repository as a fallback, not a preferred home.

How the demos are organised and served

Each feature gets its own directory, and inside it a self-contained page. The README links most of them to a live URL under mdn.github.io/dom-examples, which tells you the delivery mechanism: the repository is published as a static site from the main branch, and every directory is reachable as a path. The abort-api example lives at mdn.github.io/dom-examples/abort-api/, the chroma-keying canvas demo at mdn.github.io/dom-examples/canvas/chroma-keying/, and so on.

Some directories hold more than one demo and expose an index page instead of a single file. css-carousels has two, one with scroll buttons and scroll markers and one that also uses the ::columns pseudo-class to paginate content. css-custom-functions has three: color adjustment functions, a complex gradient background function, and a responsive narrow/wide value selection function. file-system-api collects separate tests for createSyncAccessHandle() mode, createWritable() mode, and FileSystemHandle.remove(). css-typed-arithmetic points at an index page to reach its live examples. The structure is flat and filesystem-driven rather than generated, so what you see in the tree is what you get on the site.

That design has a direct consequence for anyone reading the code: there is no shared runtime, no bundler config, no dependency manifest at the root of the examples. Each page carries its own HTML, CSS and JavaScript. Copying one demo means copying a handful of files, not resolving a dependency graph.

Running a demo locally, and the repository's own rule about browser support

Because the pages are static, the first real use is to serve the directory over HTTP rather than open the file directly, since APIs such as Channel Messaging, File System Access and the Clipboard family expect a proper origin. Clone the repository, then start any static server from the repository root.

git clone https://github.com/mdn/dom-examples.git
cd dom-examples
python3 -m http.server 8000

With that running, open the demo you care about by path, for example http://localhost:8000/abort-api/ or http://localhost:8000/channel-messaging-basic/. You should see the same page that mdn.github.io/dom-examples serves for that directory. If a demo needs an origin that the browser considers secure, localhost qualifies.

The README adds a rule that applies to any example you write or adapt. When a technology is not yet available in all major browsers, use feature detection to fall back to simpler behaviour or to tell the user their browser is not supported, and do not write supported browser names and versions into code comments or prose, because that information goes out of date quickly. That is a maintenance instruction with teeth: a demo that hardcodes a version check will rot, while one that probes for the API will keep working.

For a concrete first read, the abort-api directory is the smallest useful case. It demonstrates AbortSignal and AbortController, the pair you use to cancel a fetch or a listener. Open its index.html and its script side by side; the live page at mdn.github.io/dom-examples/abort-api/ shows the same behaviour.

Where the repository is the wrong tool

The README's own note is the strongest limitation, and it is a scoping one. If your example runs fine inside an MDN page via EmbedLiveSample or a Markdown code block, the maintainers say it should live there instead. Submitting it here adds a second copy that has to be kept in sync with the documentation, which is exactly the maintenance cost the note is trying to avoid.

Beyond that, this is not a starter kit. There is no package.json at the root, no test harness, no CI contract described in the README, and no versioning of the examples themselves. Nothing tells you that a given demo still matches the current shape of an API; the only signal is the last push to the repository, which was on 2026-09-22. A directory can sit unchanged for a long time while the specification moves.

Several of the demos cover APIs that are not available in all browsers, and the README's feature-detection guidance exists precisely because of that. If you copy a demo for the Device Posture API, the Contact Picker API or the EditContext API into a product, you inherit the compatibility question, and the repository does not answer it for you. The README explicitly refuses to record browser support, so the demo code is not a compatibility statement.

Finally, the examples are demonstrations of an API surface, not applications. They do not show error handling at product scale, state management, or the edge cases you meet when a user cancels halfway through. Reading them as reference is right; shipping them as-is is not.

How it differs from W3Schools-style references and from framework DOM guides

The closest alternative in search traffic and in habit is a tutorial site such as W3Schools, which presents DOM manipulation as short numbered lessons with an editor pane. The difference is provenance and granularity. dom-examples is the code that the MDN reference pages themselves point at, so a demo and the specification-oriented prose next to it were written together. A tutorial site optimises for a learning sequence; this repository optimises for one API per directory, with no narrative between them.

A second comparison is the framework documentation that people reach for when they search for DOM examples. React's documentation, for instance, explains how a virtual DOM reconciles a component tree and why direct DOM manipulation is usually avoided inside components. That is a different subject: it teaches a rendering model built on top of the DOM. dom-examples teaches the platform interfaces themselves, which is what you need when the framework is not the layer under discussion.

If what you want is a maintained, installable wrapper around a browser API, none of these is the right comparison either. dom-examples ships no wrapper, and the README's contributor note makes clear that adding one is out of scope.

Licence, maintenance and what a fork costs you

The repository is licensed CC0-1.0. That is a public-domain dedication rather than a permissive software licence, which matters if you copy a demo into a codebase that has a licence compatibility policy; CC0-1.0 is not the same instrument as MIT or Apache-2.0, and some organisations treat it differently. Read LICENSE in the repository and check it against your own policy rather than assuming equivalence.

Maintenance is a real consideration but a simple one. The repository is not archived, and its last push was on 2026-09-22, so it is being touched. There are no retrieved releases, which fits a project whose unit of change is a directory rather than a version. Upgrading means pulling the main branch and re-reading the demo you depend on; there is no changelog to consult and no migration path to follow.

If you fork it to host your own variants, you take on the whole static-site surface, including the GitHub Pages publishing that produces the mdn.github.io URLs. The README gives no instructions for that, because contributing a new example is the intended path and forking is not.

Editorial conclusion

Adopt mdn/dom-examples as a reading and copying source when you need to see a browser API actually wired up: pick the directory that matches the API, open its live page under mdn.github.io/dom-examples, and read the HTML, CSS and JavaScript together. Do not adopt it as a dependency, do not fork it to host your own demos, and do not treat any single directory as production-ready code, because the README positions the repository as a fallback for examples that cannot run inside MDN pages, and it carries no build, test or release machinery. Before you copy anything, check the directory's own index or README, confirm the API is available in your target browsers rather than trusting the demo, and read LICENSE to confirm the CC0-1.0 terms for the files you take.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. mdn/dom-examples on GitHub
4. Project website
5. README