# mdui is Web Components, so v2 keeps shipping while v3 is written

> mdui is a Material Design 3 component library built from Web Components, published as one npm package with a CDN build pinned behind a major version tag. The maintainer is writing v3 against the M3 Expressive specification and says v2 stays on bug fixes and new features.

**zdhxiong/mdui** — Material Design 3(Material You) UI components using Web Components.

- Repository: https://github.com/zdhxiong/mdui
- Website: https://www.mdui.org
- Stars: 4,525 · Forks: 375
- Language: TypeScript
- License: not declared
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/zdhxiong-mdui

## Every control is a custom element tag

The usage section is three lines long, which is the clearest statement of the design. Install the package, import the stylesheet and the library, then write the tag:

```bash
npm install mdui --save
```

```js
import 'mdui/mdui.css';
import 'mdui';
```

```html
<mdui-button>Button</mdui-button>
```

Because the components are Web Components rather than a framework's own widgets, the page claims they work with all frameworks, and that claim is the whole architectural argument: the same tag renders the same way in React, in Vue or in a page with no framework at all. The cost is the usual one for custom elements. You configure them through attributes and listen for events rather than passing props, and the styling boundary is a single imported stylesheet rather than scoped CSS per component. For a team whose framework choice is still open, or whose pages are static, that trade is usually worth making.

## The CDN pins a major version, the npm command does not

There are two documented distribution routes and they differ in one important detail. The CDN example is complete, with a doctype, a stylesheet link and a script tag loaded from unpkg:

```html
<link rel="stylesheet" href="https://unpkg.com/mdui@2/mdui.css" />
<script src="https://unpkg.com/mdui@2/mdui.global.js"></script>
```

Both URLs are versioned as mdui@2, so a page that copies them keeps getting the 2.x line. The npm command is not versioned at all, since it is a plain `npm install mdui --save` with no range, which means your lockfile is the only thing holding the version. Note also the two file shapes on offer, mdui.global.js for a page with script tags and mdui.esm.js linked from the badges for bundlers, plus the same stylesheet on both routes. Pick one shape per project, because mixing the global build with an ESM build registers the custom elements twice.

## v3 is in development while v2 keeps getting fixes

The note at the top of the page is a roadmap and a warning at once. The maintainer is developing mdui v3 based on the M3 Expressive specification, and publishes the development progress on a GitHub project board, while mdui v2 will continue to be updated for bug fixes and new features during that period. The repository's default branch is v2 and the releases are all 2.x: v2.1.5 on 2026-07-14, v2.1.4 on 2025-05-16 and v2.1.3 on 2024-10-24, with the last push on 2026-07-21. The gap between v2.1.3 and v2.1.4 is about fourteen months, so releases here are not frequent, and the current line's newest release is only a few weeks older than the last commit. For planning purposes, that means the 2.x line is alive but slow, and v3 has no date on the page.

## Dark theme and dynamic color are one line each

The feature list is six items and they are worth quoting in full because of what is missing. It works with all frameworks, it works with CDNs, it implements the Material 3 design system, it includes a dark theme and dynamic color, it is optimised for WebStorm and VSCode, and it is open source. That is the entire feature statement. There is no component inventory, no accessibility note, no list of which Material 3 roles are covered, and no example of either dark theme or dynamic color being switched on. The two features that carry the Material You identity are exactly the two that a reader cannot evaluate from the page. If your decision depends on how the theme is configured or how a color scheme is derived, the English or Chinese documentation under mdui.org is where you have to go next.

## Editor support is a build step, not a plugin

The claim about WebStorm and VSCode is not a hand written extension, it is generated during the release build. The mdui build script compiles Less, compiles Lit styles, runs tsc for the package, builds the Lit JavaScript, and then runs a sequence of generators, with a parallel group at the end:

```
"build:mdui": "tsx scripts/mdui/build-less.ts && tsx scripts/mdui/build-lit-style.ts && tsc -p packages/mdui/tsconfig.json && tsx scripts/mdui/build-lit-js.ts && npm-run-all -s localize-build customElements:mdui i18n -p vscode:mdui webtypes:mdui jsxtypes:mdui",
```

Reading the tail of that command gives the editor story: a custom elements manifest, webtypes, and JSX types, plus localisation and i18n output, with the editor facing artefacts built in parallel. A separate build:mcp target compiles an MCP package, so the repository also produces something for model context tooling. The practical consequence is that autocompletion in your editor is a function of the published artefacts, not of anything in your project, and it will only be as current as the version you installed.

## Five workspace packages, each with its own clean target

The repository is a pnpm workspace, and the root package is private and marked as an ES module. The scripts give away the package names: clean:jq, clean:shared, clean:mdui, clean:icons-shared and clean:icons, each removing generated directories with rimraf globs, for example packages/mdui/components, functions, internal and locales plus the built stylesheet. The clean target itself is `run-p clean:*`, so all five run together, and lint mirrors the shape with `run-p lint:*` over stylelint and eslint per package. One package is named jq and is built and cleaned separately from shared, mdui and the two icon packages, and the page says nothing about what it is, so a reader has to read the source. What the layout does make clear is that this is a component library assembled from shared internals, not a single package of hand written tags.

## Styles are Less and Lit, compiled by scripts per package

The build scripts for the shared and mdui packages follow the same four step shape: run scripts to build Less, run a script to build the Lit styles, compile TypeScript with tsc against the package tsconfig, then a final script to emit the JavaScript. The shared package ends with build-js and mdui ends with build-lit-js, which tells you the component layer is built on Lit. Development variants of the same scripts pass a --dev flag to the style steps, so a local build skips production compression without changing the command. Alongside that sit eslint.config.js, stylelint.config.js, prettier.config.js, a browserslist config and .editorconfig, and the tree holds demos/ and docs/ next to packages/ and scripts/. In other words the toolchain is a component library pipeline: Less in, Lit styles out, TypeScript compiled per package, then the editor and localisation artefacts generated at the end.

## Conclusion

mdui fits a team that wants Material 3 without adopting a framework's component model, since a custom element tag works the same in React, Vue or plain HTML, and it fits teams that ship static pages through a CDN. It does not fit a team that needs a component API with props and events rather than attributes and custom elements. Before you adopt it, decide whether you are on the v2 line or waiting for v3, because the default branch is v2, the releases are all 2.x with a fourteen month gap between 2.1.3 and 2.1.4, and v3 is described as still in development against the M3 Expressive specification. Also read the dark theme and dynamic color features yourself: the page lists both without showing the configuration.

## FAQ

### What is mdui?

mdui is a library of Web Components implementing Material Design 3, also called Material You. It is published as the mdui package on npm, works with CDNs, and includes a dark theme and dynamic color among its listed features.

### How do I install mdui?

Run `npm install mdui --save`, then import 'mdui/mdui.css' and import 'mdui', and use the custom element tags such as mdui-button. For a page without a build step, the CDN route loads mdui@2/mdui.css and mdui@2/mdui.global.js from unpkg.

### Does mdui have a dark theme and dynamic color?

Both are listed among the library's features, alongside working with all frameworks, working with CDNs, the Material 3 design system, WebStorm and VSCode optimisation, and being open source. The page shows no configuration for either feature.

### What is the difference between mdui v2 and v3?

v3 is being developed against the M3 Expressive specification with its progress published on a GitHub project board, while v2 continues to receive bug fixes and new features. The repository's default branch is v2 and the published releases are all 2.x, up to v2.1.5 on 2026-07-14.

### Why does mdui claim WebStorm and VSCode support?

The release build generates the editor artefacts rather than shipping a plugin. The mdui build runs custom elements, webtypes and JSX type generators in a parallel group after compiling TypeScript and Lit styles, which is what feeds completion in those editors.

## Sources

- [Issues](https://github.com/zdhxiong/mdui/issues)
- [Project website](https://www.mdui.org)
- [README](https://github.com/zdhxiong/mdui/blob/v2/README.md)
- [Releases](https://github.com/zdhxiong/mdui/releases)
- [zdhxiong/mdui on GitHub](https://github.com/zdhxiong/mdui)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zdhxiong-mdui