Qwik UI: a headless and styled component library for Qwik

Two packages, two philosophies, published separately

Qwik UI is described as Qwik's Headless and styled component library, and the split is visible in the npm packages and their versions.

The headless package is @qwik-ui/headless, and the styled package is @qwik-ui/styled, with a top-level qwik-ui package alongside it. The most recent releases are @qwik-ui/headless at 0.7.4 from 2025-10-26, qwik-ui at 0.4.3 from 2025-10-07, and @qwik-ui/styled at 0.4.1 from 2025-10-07. The two packages are versioned independently, and the headless one is a good deal further along, which suggests it is the layer that receives most of the work.

The headless idea is worth spelling out. A headless component carries the behaviour, the accessibility semantics and the keyboard handling, but renders almost nothing of its own, leaving the markup and the classes to the consumer. That is a real difference in how much you have to argue about with a design system later: with a headless primitive you own the pixels, and with a styled one you own only the theme.

The topic tags confirm the audience and the technology: a11y, headless, qwik, qwik-city, qwik-framework, styled, tailwind and ui. Accessibility and Tailwind are both first-class concerns rather than afterthoughts, and the styled package is built on the headless one, which is why the two version lines differ.

The project is MIT licensed, and the documentation lives at qwikui.com.

Installing the headless package, and what the docs have to cover

The readme gives one install command, and it is for the headless package:

npm install -D @qwik-ui/headless

The -D flag is the interesting detail, since it installs the package as a development dependency. For a component library that is compiled into the application bundle rather than shipped as runtime code to the browser, that is the correct classification, and it matches how Qwik's resumability model works, where the component code is build-time input.

The readme is otherwise extremely short, and the documentation is delegated to the website. To read the complete docs, the readme says to visit qwikui.com, and the site is the package's homepage in the project listing as well.

That is a reasonable arrangement for a component library, since the real content is the component inventory, the props each component accepts, and the examples, and that is a lot of reference content that does not belong in a README. It does mean the README alone cannot tell you what is in the library, so the site is where you should look before deciding.

The repository structure supports the same picture. There is an apps/ directory for the website, a packages/ directory for the published packages, tools/ for build scripts, a migrations.json for component migration handling, and a .verdaccio/ directory, which is a local npm registry used to test the packages against each other before publication.

The monorepo machinery: Nx, changesets, and a local registry

The root package.json is a private container named qwik-ui-repo with version 0.0.0, describing itself as the Qwik UI Components Monorepo, requiring Node 16.0.0 or above, and declaring type module.

Almost every script is an Nx target, which is the tool that coordinates the packages, the website and the component tests. The build target is nx build website, there is a separate build.headless for the headless package, build.qwik-ci runs the build across packages/*, and the release.prepare target runs the build across every package with the cache skipped.

The dev scripts show how the project is worked on. dev serves the website with a host flag, and dev.ct serves the component-tests project, so the component tests have their own application rather than living inside the docs site.

The release process is the part worth reading closely, because it is where the local registry earns its place. release.prepare builds every package, release.setroot moves a prepared pnpm-workspace.yaml to the root and copies a release-specific workspace file into place, release.publish runs changeset publish, and release.resetroot restores the original workspace file. The local registry is what makes that possible, since publishing from a workspace with cross-package dependencies needs a registry that resolves the not-yet-published versions, and Verdaccio provides one.

Versioning itself is handled by changesets, with a changeset.version script that runs changeset version, installs without the frozen lockfile, and stages everything. There is also a custom changelog formatter, build.changelog-formatter, compiled from a TypeScript file in .changeset/ and rewritten to CommonJS after compilation, which tells you the changelog output is custom rather than the default.

Component tests, the accessibility angle and the Tailwind question

The topic tags and the tooling suggest what the project is actually trying to get right, and accessibility is the first of them.

A headless component that claims accessibility has to be correct about focus management, keyboard interaction and ARIA semantics, and those are the parts that a styled wrapper would otherwise paper over. The a11y tag is on the repository, and the styled package is built on the headless one, which means the accessibility contract lives in the layer that behaves and the visual contract lives in the layer that looks. That ordering is the right way round: an accessible primitive that is hard to style is still useful, whereas a beautiful component with broken focus handling is not.

The Tailwind tag raises a question the readme does not answer directly. If the styled package is built with Tailwind, then adopting it means adopting Tailwind, or at least accepting a stylesheet pipeline based on it. The readme does not state the styling approach for the styled package, so this is one of the things the documentation site has to cover.

The component-tests application is the other signal worth noting. A library whose components are headless has to test behaviour, not pixels, and the dev.ct script serving a dedicated component-tests app suggests the tests run against a real application rather than shallow render snapshots.

For an adopter, the practical checks are therefore about the component inventory, the keyboard and focus behaviour of each primitive, and how the styled layer handles theming, and all three live on the site rather than in the repository.

Two independent version lines, and a repository that has not moved since August

The maintenance picture is the part that deserves a straight answer.

The repository is not archived, and the last push was on 2026-08-07, which is more than two months before the release tags tell a different story. The recent releases are @qwik-ui/headless at 0.7.4 from 2025-10-26, and qwik-ui at 0.4.3 and @qwik-ui/styled at 0.4.1 both from 2025-10-07.

So the npm packages were last published in October 2025, while the repository has seen commits up to August 2026. That gap has two possible explanations, and the readme does not say which applies: work is landing on the repository but not yet released, or the project has slowed. The .changeset/ directory and the changeset-based release scripts are configured for the first case, and the presence of a migrations.json file hints at a versioning or migration story for the components that is still in progress.

For an adopter, the practical questions are concrete. Does the version on npm match the code in the repository you are reading? Is the headless package's higher version number a sign of active work on that layer, or of a split versioning policy? And if you are on Qwik, is the Qwik version this library targets still the one your application uses?

None of that is a reason to avoid the library, and the fact that the framework itself moves quickly is part of the context. It is a reason to pin versions and to read the release notes on the site before upgrading, and to check the publish dates of the two packages separately rather than assuming a single qwik-ui version covers both.

Editorial conclusion

Qwik UI fits a Qwik team that wants accessible component behaviour with markup and styling left under its own control, and it does not fit a team that wants a single styled library with no decisions to make, or a project on a different framework. Before adopting it, read the docs at qwikui.com for the component inventory, decide whether you want the headless package alone or the styled layer as well, and check the release dates of the two npm packages, since they are versioned independently and the headless package is ahead.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. qwikifiers/qwik-ui on GitHub
4. README
5. Releases