ZUI 3: a framework-agnostic HTML5 UI library built on Preact and Tailwind

What ZUI 3 solves, and who it is written for

Most component libraries assume you have already chosen a framework. ZUI 3 does not. The README describes it as a Web UI component library that is ready to use, composable and customizable, and states plainly that it is not bound to a specific JavaScript framework. That single decision drives the rest of the design: the public surface is a native DOM API, so the same button, dialog or data table can be dropped into a server-rendered page, a legacy jQuery-era application, or a modern build pipeline without a wrapper layer.

The audience follows from that. Teams maintaining an existing application that cannot absorb a framework rewrite are the clearest fit. So are developers who want CSS utilities and CSS components first, with JavaScript behaviour only where a control needs it. The README lists buttons, forms, navigation, cards, tables, dropdowns, dialogs, data tables and file upload as covered scenarios, which is the ordinary inventory of an admin interface rather than a marketing site. If your product is a dashboard, an internal tool or a content management backend, the component list maps onto the work directly.

How the pieces fit together: CSS variables, Preact and per-library workspaces

ZUI 3 is not one bundle with one entry point. The repository is a pnpm workspace, and the README says each feature is an independent workspace library that can be combined into a custom build. In practice that means lib/ holds the components, each with its own source, styles, debug page and documentation source, while config/ carries the shared Tailwind theme configuration. The build scripts in scripts/ read library metadata and assemble whatever subset you ask for.

Styling is driven by CSS variables. The README describes them as the mechanism for global design configuration, and names theme customization and dark mode as the outcomes. That is a meaningful choice: a CSS variable can be overridden at runtime by a host application without rebuilding the library, which is what makes the framework-agnostic claim hold up in practice. JavaScript components are written in TypeScript and use Preact internally, with Cash for DOM work, but Preact is an implementation detail rather than a requirement on your side. The published package exposes two entry points, an ESM build and a CommonJS build, plus a separate CSS export.

The Codex plugin in the same repository is a second, unrelated delivery path. The README says the repository is also a skills-only Codex plugin offering two workflows: $zui, which inspects an existing project's ZUI version and integration method before installing, integrating, refactoring or troubleshooting ZUI 3, and $zui-build, which creates standalone ZUI 3 pages or small static sites from a requirements description without installing dependencies or build tools. Those are agent workflows, not runtime code, and they should be judged separately from the library itself.

Installing ZUI 3 and wiring up a first component

The fastest path is the CDN build. The README gives a complete HTML page that loads zui.css and zui.js from jsDelivr, then attaches a click handler that calls a global zui object. Note the production advice in the README: pin an explicit ZUI version in the CDN URL rather than tracking the latest release.

<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ZUI 3 Demo</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zui/dist/zui.css">
</head>
<body>
    <button id="helloZui" type="button" class="btn primary">Hello ZUI</button>
    <script src="https://cdn.jsdelivr.net/npm/zui/dist/zui.js"></script>
</body>
</html>

After the script loads, the global zui object is available and the button carries the btn and primary classes. Clicking it should raise a message toast.

For a project with a build step, the README shows the package manager route. Install with pnpm, then import the stylesheet and the component you need:

pnpm add zui

import 'zui/css';
import {Messager} from 'zui';

Messager.show('ZUI 3 已就绪！');

The import specifier is zui/css, not a path into dist, and Messager is a named export from the package root. The package.json exports map confirms both: the root maps to the ESM or CommonJS build depending on how you import it, and ./css maps to dist/zui.css. If you are working on the library itself rather than consuming it, the README requires Node.js 22.13 or newer and pnpm 12.5.1, then git clone, pnpm install and pnpm dev. The dev server runs at http://localhost:5173/, and any single library has its own debug page at a path like http://localhost:5173/button/.

Custom builds, and why the component set is the real constraint

The build command accepts a library list and an output name. The README example is pnpm build -- --lib="button dropdown" --name=zui-custom, and the result lands in dist/zui-custom/. This is the feature that makes the workspace layout pay off: you ship the components you use and nothing else, which matters when the full CSS is more surface area than a small page needs.

The constraint is the same one that makes the feature possible. Because each component is its own workspace library with its own styles and debug page, a component that is not in lib/ is not available to the custom build, and the README does not describe any third-party component registry. The exts/ directory is the documented extension point: local extension libraries are added through pnpm extend-lib <path>. That is a source-level integration, not a plugin marketplace. If your design system needs a component ZUI does not ship, you are writing it against the same workspace conventions, and you should expect to maintain it alongside upstream changes.

There is also a verification cost attached to customization. The README's command table includes pnpm test:build, which it says validates representative ESM, UMD, CSS, source map, ZIP and externalized Cash artifacts. A custom combination is a new artifact shape, and the README does not claim that the build test matrix covers arbitrary --lib combinations. Treat a custom bundle as something you validate yourself.

Where ZUI 3 is the wrong choice

The clearest limitation is version migration. The README points readers looking for ZUI 1 to a separate site and the zui1 branch, which tells you the two lines are maintained apart. It does not document an upgrade path, a codemod, or a compatibility layer between them. If you are already running ZUI 1 and need a low-risk path forward, the repository as described does not give you one, and the 3.0.0 release date of 2024-07-26 means the current major line has been stable for a while without a documented successor migration story.

The second boundary is scope. ZUI 3 is a component library, not an application framework. It has no router, no state management and no data-fetching layer, and the README does not suggest otherwise. Teams that want a single dependency to cover routing and state should look at a framework instead and treat ZUI as the styling and widget layer beneath it.

Third, the toolchain requirements are not casual. Source development needs Node.js 22.13 or newer and exactly pnpm 12.5.1, and package.json enforces the package manager through a preinstall script that runs npx only-allow pnpm. Consuming the published package does not require any of that, but contributing or building a custom bundle does. If your CI image is pinned to an older Node release, that is a real blocker to work through before you start.

How ZUI 3 differs from Bootstrap and from component libraries tied to a framework

The closest comparison is Bootstrap. Both ship CSS utilities, CSS components and a JavaScript layer that attaches to markup, and both can be dropped into a page with a stylesheet and a script tag. The difference is in how the JavaScript is organized. Bootstrap's behaviour is built around its own plugin system and jQuery heritage, while ZUI 3 writes its components in TypeScript with Preact internally and exposes a global zui object or named ESM exports. That matters if you want to import a single component into a bundler rather than loading a monolithic script.

The other comparison is against libraries that assume React, Vue or another framework. Those give you declarative components that participate in the host framework's rendering and state. ZUI 3 gives you DOM APIs and CSS classes instead, which is less ergonomic inside a React tree but works anywhere. A React-only team gains little from that trade; a team with a server-rendered admin panel and a few interactive widgets gains a lot. The Tailwind and Preact choices in the tech stack also mean the styling layer is closer to utility CSS than to a bespoke class vocabulary, which is a different mental model if you are used to semantic component classes.

Licence, maintenance and what an upgrade actually costs

ZUI 3 is released under the MIT License, and the LICENSE file sits at the repository root alongside a licenses/ directory. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few obligations, but it also means no warranty and no support commitment from the project. Nothing in the repository describes a commercial support tier. This is a description of the licence text, not legal advice; have your own counsel review it if distribution terms matter to you.

On maintenance, the last push to the default branch was on 2026-09-24, and the repository is not archived. The most recent release listed is v3.0.0 from 2024-07-26, preceded by two alpha builds in 2023 and early 2024. So there is recent commit activity on main alongside a release line that has not produced a tagged version in roughly two years. That pattern is worth reading carefully: it suggests ongoing work that has not been cut into a release, and it means the version you install from a package registry may lag what main contains. Check the CHANGELOG before assuming a fix on main is in the published artifact.

Upgrade cost for consumers is low in one respect and unmeasured in another. The published package exposes stable entry points, and the CSS export is a single file. But the README does not document a deprecation policy, a semantic versioning commitment, or a migration guide between majors, so the practical cost of a future 4.0 cannot be estimated from the repository. For source contributors the cost is higher: pnpm check runs lint, typecheck, unit and DOM tests and skill tests, and the README asks contributors to add representative build tests, browser tests and matching single-library debug page verification for their changes.

Editorial conclusion

Adopt ZUI 3 if you need a UI layer that works in plain HTML as well as inside an existing frontend stack, and if you accept the Node 22.13 and pnpm 12.5.1 requirements for source work. Do not adopt it if you need a documented upgrade path between major versions: the README points to ZUI 1 on a separate branch and site, but never describes how to migrate. Before committing, verify that the components you need exist in lib/ and run pnpm check against your fork.

Frequently asked questions

Official sources

1. easysoft/zui on GitHub
2. License: MIT
3. Project website
4. README
5. Releases