Maz UI is a pick-and-mix component library for Vue 3 and Nuxt 3

What the library actually ships

Maz UI is described as a lightweight and efficient library for Vue and Nuxt, and the repository description puts it more precisely: a standalone components library for Vue.Js and Nuxt.Js.

The word standalone is the one to keep in mind. This is not a design system with a mandatory configuration and a fixed set of layers. The feature list leads with Cherry-pick components, use only what you need, and the README's usage example imports a single component by path:

import MazBtn from 'maz-ui/components/MazBtn'

Everything else is layered on top of that principle. The rest of the feature list names dark mode support built in, theming through CSS variables, a mobile-first responsive approach, full TypeScript type support, tree-shakeable output with no bloat, and server-side rendering readiness.

The packages directory in the repository confirms the structure. The README lists modules as Components, Plugins, Composables, Directives and Helpers, and packages as Themes, Translations, Icons, Nuxt, Utils, Node, MCP and EslintConfig.

Several of those deserve a note. Themes are the CSS variable layer, Translations is the internationalization package, Icons is a set of ready-to-use Vue icons, Node holds utilities that run outside the browser, and MCP is described as an AI assistant for documentation, which is a newer addition that points at a guide page of its own. The EslintConfig package is the project's own lint setup built on top of the @antfu/eslint-config package.

The project is TypeScript, the homepage is maz-ui.com, and the last push was on 2026-10-19 with beta releases landing on 2026-10-13 and earlier in October 2026.

Installing and wiring it into a Vue app

The install is one command:

npm install maz-ui

The Vue setup then needs three imports and a plugin registration, and the README gives the whole of main.ts:

import { mazUi } from '@maz-ui/themes/presets'
import { fr } from '@maz-ui/translations'
import { MazUi } from 'maz-ui/plugins/maz-ui'
// main.ts
import 'maz-ui/styles'

const app = createApp(App)

app.use(MazUi, {
  theme: {
    preset: mazUi,
  },
  translations: {
    messages: {
      fr,
    },
  },
})

Three things are worth pulling out of that snippet.

The styles are a separate import, maz-ui/styles, and they come before anything else in the file. A component library that ships its styles as a side-effect import rather than requiring them per component is making a choice about ordering, and getting that import after your own component code is a common source of a flash of unstyled content.

The theme is passed as a preset from the @maz-ui/themes package, and the translations are passed as messages to the plugin, keyed by locale. So theming and internationalisation are both plugin configuration, not per-component props, which is what makes them consistent across the app.

And the components themselves are not registered by the plugin in the Vue case. The README says to then import and use only the components, composables and more you need, which is what the MazBtn example above shows. The plugin handles the theme and the translations; the components are direct imports.

There is a shortcut for the imports themselves. Use provided resolvers to enjoy auto-imports and TypeScript support, with the resolvers documentation linked at maz-ui.com under Getting Started, under recommendations.

The Nuxt module and what it removes

Nuxt is the path with less to write, and the README describes what the module does for you in three bullets.

The Nuxt module automatically imports all components, plugins, composables and directives on-demand as auto-imports, includes the required styles, and provides TypeScript support out of the box.

The configuration is one line:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt'],
})

And then the components are simply used, with no import statement at all:

const toast = useToast()

in the script block, with the component used in the template. The README states the point plainly: no need to import components, plugins, composables or directives, they are all auto-imported.

That is a meaningful difference from the Vue path and it is not only about typing less. On-demand auto-import means your bundle only contains the components you actually reference, which is the same tree-shaking claim the feature list makes but delivered through the module system rather than through the bundler's analysis of your import statements.

The composable in the example, useToast, is what drives the Plugins category. A toast service used without importing anything means the plugin is registered globally by the module and the composable reaches it, which is the pattern Nuxt users expect.

The module has its own options page in the documentation at maz-ui.com under guide/nuxt, so the module is configurable rather than fixed.

Theming, dark mode and the design decisions

The theming story is CSS variables, and the README's Themes package description is easy to customise with CSS variables.

That choice has consequences worth naming. CSS variables are a runtime mechanism, not a build-time one, so a theme can be swapped at runtime without rebuilding, and a component can read a variable that a consumer overrides in their own stylesheet. That is how dark mode works here, as a built-in feature rather than a set of duplicated component styles.

The presets package, @maz-ui/themes/presets, is where the named presets come from, and the README's example imports mazUi from it as the default. A theme preset is therefore a set of variable values, and the design system is the component set plus the variable contract between them.

The README describes the components as beautiful, accessible UI components. Accessibility is the claim to test rather than accept, and it is the one that matters most for a component library, because accessibility bugs in a shared component get inherited by every screen that uses it.

The plugin and composable categories cover the common cases. Plugins are for common use cases, with the dialog plugin linked as the example, and composables are reusable composition functions, with a form validator linked as the example. The form validator example is the more interesting one, because validation logic is exactly the kind of thing teams otherwise rewrite inconsistently.

Directives and helpers fill out the rest, with a fullscreen image directive and a currency helper named as the examples.

Repository structure, tooling and the release state

The repository is a monorepo, and the tooling says so.

The root package.json is a private root package named root at version 4.9.3, with packageManager set to [email protected] and a preinstall script running npx only-allow pnpm. The build is driven by Nx, with scripts like build:all running nx run-many -t build, build:packages targeting the @maz-ui scope, and separate targets for the docs, nuxt-app and vue-app example applications.

The workspace layout is pnpm-workspace.yaml plus pnpm-lock.yaml, with packages/ holding the published packages, apps/ the applications, tools/ the tooling, and plans/ a directory that has no counterpart in most monorepos and presumably holds the author's own planning documents.

There is a healthcheck script that runs lint, typecheck, unit tests, a package build and the docs build in sequence, which is the kind of single command a project uses to prove it is shippable. The unit test badge points at the lib-test-unit.yml workflow, and there is a codecov badge for coverage.

The release state is the part to note. The listed releases are all 5.0.0 betas, with beta.51 on 2026-10-13, beta.50 on 2026-10-09 and beta.49 on 2026-10-08. The version in the root package.json is still 4.9.3, which tells you the 4.x line is the stable one and the 5.x work is in preparation.

The same repository also hosts Relizy, an auto-release manager for packages and apps, which is a separate project with its own documentation at relizy.dev and its own repository. The README mentions it as the thing to check out if you are looking for a package or release manager, which suggests it is built on the same multi-package release tooling the monorepo needs.

Where Maz UI fits, and where it stops

The comparison worth making is with the large design systems and with writing the components yourself.

Against a full design system, the difference is scope and commitment. A design system gives you a coherent system with documented rules, and it asks you to accept its spacing scale, its type scale and its interaction patterns. Maz UI gives you components and a variable contract, and you can use one of them, MazBtn, in an application that otherwise has no design system at all. The trade is that coherence across a large product is not something this library supplies for you.

Against writing the components yourself, the difference is accessibility and consistency. The components are described as accessible, and that claim is the reason to use a library rather than a starting point, because the parts of an accessible button that are easy to get wrong, the focus management, the keyboard activation, the disabled semantics, are exactly the parts you would not notice you had missed.

The limits are worth being concrete about. The 5.x line is in beta, so the version you pin is a beta version and the API may still move. The package layout uses subpath imports, maz-ui/components/MazBtn and maz-ui/plugins/maz-ui, which is fine for a bundler but unusual enough that you need to check your tooling handles it, and the Nuxt module is the path with the least friction. The Nuxt integration also needs the module to register the styles in the right order, which the README covers.

And the licensing needs a second look. The README's License section links to an MIT LICENSE file, and the section above it describes the project as MIT licensed, while the root package.json records the license as ISC. Both cannot be the whole story, and the packages under packages/ may each carry their own licence field. For a company shipping this in a product, the file to read is the one in the package you are actually depending on, not the one the README links.

For a Vue 3 or Nuxt 3 team that wants decent components quickly and is willing to own the theming decisions, this is a well-organised library with a real monorepo behind it. For a team that needs a documented, stable component contract with a long support window, the 4.x line and its MIT file are the things to evaluate.

Editorial conclusion

Maz UI suits a Vue 3 or Nuxt 3 team that wants accessible components without adopting a whole design system, since every component, plugin, composable and directive is imported individually and the theming runs on CSS variables rather than a configuration object. It is the wrong tool if you need a stable release line, because the published versions are 5.0.0 betas and the main branch carries the development work, and it is the wrong tool if your project is on Vue 2. Before adopting it, check the licensing yourself, because the README points at an MIT LICENSE file while the root package.json records ISC, and read the Getting Started page on maz-ui.com for the resolvers that give you auto-imports and TypeScript support.

Frequently asked questions

Official sources

1. Issues
2. LouisMazel/maz-ui on GitHub
3. Project website
4. README
5. Releases