Maz-UI

Getting Started ​

Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library

Why Maz-UI?

  • 🌱 Tree-shaking - Import only what you need
  • 🛠️ TypeScript-first - Full type safety out of the box
  • 🚀 Performance - Tree-shaking benefits and maximum optimization
  • 🎨 Theming system - Customizable themes and dark mode support (5 presets available) - @maz-ui/themes
  • 💨 Optional Tailwind bridge - Already have a Tailwind v4 setup? Expose your active maz-ui theme tokens (colors, radius, breakpoints, custom utilities) to your own Tailwind config - Tailwind integration
  • 🌐 Internationalization - Locale management and tree-shakable imports - @maz-ui/translations
  • 🎨 Icon library - Comprehensive collection of SVG icons designed for performance and flexibility (860+ icons) - @maz-ui/icons
  • 🧰 Nuxt module - Effortless Maz-UI integration with auto-imports - @maz-ui/nuxt
  • 🤖 AI agents - Make Claude Code, Cursor, Copilot and Codex use maz-ui instead of re-implementing it - AI agents, @maz-ui/mcp

Migrating from v4?

Run npx @maz-ui/upgrade ./ to handle the mechanical part of the migration (CSS subpath imports, prop renames, CSS var renames, Nuxt config keys, custom preset color keys, and package.json version bumps). See the v5 migration guide for the rest.

Guides ​

Start by choosing your framework:

Vue Users Guide

Vue guide

Nuxt Users Guide

Nuxt guide

Ecosystem Packages ​

Extend Maz-UI with our specialized companion packages:

@maz-ui/themes ​

Advanced Theming System

Modern theme system with OKLCh color scales, runtime preset switching, and dark mode support.

bash
npm install @maz-ui/themes

Features:

  • 🎨 Native light-dark() + color-scheme + OKLCh scales via relative color syntax
  • 🌓 Smart dark mode — class or media strategies, with smooth transitions on toggle
  • ✨ Optional animated theme switch via View Transitions (setColorMode(..., { animate: true }))
  • ⚡ runtime and buildtime rendering strategies
  • 🍪 Active preset persisted across reloads (opt-out)
  • 🛡️ Full TypeScript support

→ View Theme Documentation

@maz-ui/translations ​

Internationalization (i18n)

Internationalization library for Maz-UI.

bash
npm install @maz-ui/translations

Features:

  • 🌐 Internationalization of Maz-UI components
  • 🔄 Locale management
  • 📦 Tree-shakable imports
  • 🛠️ TypeScript support

→ View Translations Documentation

@maz-ui/icons ​

Optimized Icon Library

Comprehensive collection of SVG icons designed for performance and flexibility.

bash
npm install @maz-ui/icons

Features:

  • 860+ icons
  • Usable as Vue components (e.g. <MazStar />)
  • Tree-shakable imports
  • Multiple sizes and variants
  • Full TypeScript definitions

→ Browse Icon Library

@maz-ui/mcp ​

Make your AI coding agents use maz-ui

bash
npx @maz-ui/mcp init

Features:

  • Rules for Claude Code, Cursor, GitHub Copilot, Codex... without touching your own instructions
  • MCP server: search by need, component APIs, icons, Tailwind theme tokens, docs of the installed version
  • Code review against the installed maz-ui, in the agent loop and in CI
  • Claude Code plugin and automatic setup with the Nuxt module

→ View AI agents guide

Performance Optimizations ​

Tree-Shaking Benefits ​

Maz-UI v5 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:

typescript
/**
 * Components
 */

// ✅ Import specific components (good)
import { MazBtn, MazCard, MazInput } from 'maz-ui/components'
// ✅✅ Direct component import (most optimized)
import MazBtn from 'maz-ui/components/MazBtn'
import MazCard from 'maz-ui/components/MazCard'
import MazInput from 'maz-ui/components/MazInput'

/**
 * Composables
 */

// ✅ Import composable from index file
import { useBreakpoints, useToast } from 'maz-ui/composables'

// ✅✅ Direct composable import (most optimized)
import { useToast } from 'maz-ui/composables/useToast'
import { useBreakpoints } from 'maz-ui/composables/useBreakpoints'

/**
 * Directives
 */

// ✅ Import directive from index file
import { vClickOutside } from 'maz-ui/directives'

// ✅✅ Direct directive import (most optimized)
import { vClickOutside } from 'maz-ui/directives/vClickOutside'

// ✅✅✅ Even better: auto-import does this automatically
// Components, composables, and utilities are imported only when used

/**
 * Plugins
 */

// ✅ Import plugin from index file
import { MazUi } from 'maz-ui/plugins'
// ✅✅ Direct plugin import (most optimized)
import { MazUi } from 'maz-ui/plugins/maz-ui'

/**
 * Utilities
 */

// ❌ Avoid importing everything
import { formatCurrency, debounce } from '@maz-ui/utils'
// ✅ Import from @maz-ui/utils
import { debounce } from '@maz-ui/utils/helpers/debounce'
import { formatCurrency } from '@maz-ui/utils/helpers/formatCurrency'

Maximum Optimization

Direct imports (e.g., import MazBtn from 'maz-ui/components/MazBtn') are the most optimized approach as they bypass index files completely. This ensures the smallest possible bundle size and fastest build times.

Next Steps ​

Explore Components ​

Browse the component library with live examples and API documentation.

Customize Themes ​

Learn about theming and customization to match your brand.

Internationalization ​

Learn about internationalization to support multiple languages.

Lazy Loading with MazUiProvider ​

Use MazUiProvider to defer Maz-UI initialization to lazy-loaded pages for zero entry-bundle overhead.

Get Help ​

Browse GitHub discussions or open an issue on GitHub.

Made by LouisMazel with 🖤