Maz-UI v4 - Vue & Nuxt Component Library

Maz-UI is a comprehensive, standalone component library for Vue 3 and Nuxt 3 applications, offering 50+ production-ready components, powerful theming, internationalization, and exceptional developer experience.

Latest Version: 4.3.3 (as of 2025-12-29) Package: maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons

Quick Start

Vue 3 Installation

Install core packages

pnpm add maz-ui @maz-ui/themes

Or with npm

npm install maz-ui @maz-ui/themes

Setup in main.ts :

import { createApp } from 'vue' import { MazUi } from 'maz-ui/plugins/maz-ui' import { mazUi } from '@maz-ui/themes' import { en } from '@maz-ui/translations' import 'maz-ui/styles' import App from './App.vue'

const app = createApp(App)

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

app.mount('#app')

Use Components:

<script setup> import MazBtn from 'maz-ui/components/MazBtn' import MazInput from 'maz-ui/components/MazInput' import { ref } from 'vue'

const inputValue = ref('') </script>

<template> <MazInput v-model="inputValue" label="Name" /> <MazBtn color="primary">Submit</MazBtn> </template>

Nuxt 3 Installation

Install Nuxt module

pnpm add @maz-ui/nuxt

Setup in nuxt.config.ts :

export default defineNuxtConfig({ modules: ['@maz-ui/nuxt'] // That's it! Auto-imports enabled 🎉 })

Use Components (no imports needed):

<script setup> // Auto-imported composables const theme = useTheme() const toast = useToast() const inputValue = ref('') </script>

<template> <!-- Auto-imported components --> <MazInput v-model="inputValue" label="Name" /> <MazBtn color="primary" @click="toast.success('Submitted!')"> Submit </MazBtn> </template>

Core Capabilities

🎨 Components (50+)

Forms & Inputs:

• MazInput

• Text input with validation states

• MazSelect

• Dropdown select

• MazTextarea

• Multi-line text input

• MazCheckbox

• Checkbox with label

• MazRadio

• Radio buttons

• MazSwitch

• Toggle switch

• MazSlider

• Range slider

• MazInputPhoneNumber

• International phone input with validation

• MazInputCode

• Code/PIN input

• MazInputPrice

• Currency input with formatting

• MazInputTags

• Tag/chip input

• MazDatePicker

• Date picker

• MazChecklist

• Searchable checklist

UI Elements:

• MazBtn

• Button with variants

• MazCard

• Container card

• MazBadge

• Label badge

• MazAvatar

• User avatar

• MazIcon

• Icon display

• MazSpinner

• Loading spinner

• MazTable

• Data table with sorting/pagination

• MazTabs

• Tab navigation

• MazStepper

• Step indicator

• MazPagination

• Pagination controls

Overlays & Modals:

• MazDialog

• Modal dialog

• MazDialogConfirm

• Confirmation dialog

• MazDrawer

• Slide-out drawer

• MazBottomSheet

• Mobile bottom sheet

• MazBackdrop

• Overlay backdrop

• MazPopover

• Floating popover

• MazDropdown

• Dropdown menu

Feedback & Animation:

• MazFullscreenLoader

• Loading overlay

• MazLoadingBar

• Progress bar

• MazCircularProgressBar

• Circular progress

• MazReadingProgressBar

• Reading progress indicator

• MazAnimatedText

• Text animations

• MazAnimatedElement

• Element animations

• MazAnimatedCounter

• Number counter animation

• MazCardSpotlight

• Card with spotlight effect

Layout & Display:

• MazCarousel

• Image carousel

• MazGallery

• Image gallery

• MazAccordion

• Collapsible panels

• MazExpandAnimation

• Expand/collapse animation

• MazLazyImg

• Lazy-loaded image

• MazPullToRefresh

• Pull-to-refresh gesture

• MazChart

• Chart.js integration

🔧 Composables (14+)

Theming:

• useTheme()
• Theme and dark mode management

Translations:

• useTranslations()
• i18n management

UI Interactions:

• useToast()

• Toast notifications

• useDialog()

• Programmatic dialogs

• useWait()

• Loading states

Utilities:

• useBreakpoints()

• Responsive breakpoints

• useWindowSize()

• Window dimensions

• useTimer()

• Timer/countdown

• useFormValidator()

• Form validation (Valibot)

• useIdleTimeout()

• Idle detection

• useUserVisibility()

• Page visibility

• useSwipe()

• Swipe gestures

• useReadingTime()

• Reading time calculation

• useStringMatching()

• String utilities

• useDisplayNames()

• Localized display names

📌 Directives (5)

• v-tooltip

• Tooltips

• v-click-outside

• Outside click detection

• v-lazy-img

• Lazy loading

• v-zoom-img

• Image zoom

• v-fullscreen-img

• Fullscreen image viewer

🔌 Plugins (4)

• AOS - Animations on scroll

• Dialog - Template-free dialogs

• Toast - Notifications

• Wait - Global loading states

Key Features

✅ Standalone Components - Import only what you need, zero bloat ✅ SSR/SSG Ready - Full Nuxt 3 support with auto-imports ✅ TypeScript-First - Complete type safety out of the box ✅ Dark Mode - Built-in dark/light theme switching ✅ Tree-Shakable - Optimized bundle sizes ✅ Responsive - Mobile-first design ✅ Accessible - ARIA-compliant components ✅ Themeable - 4 built-in presets + custom themes ✅ i18n - Multi-language support with @maz-ui/translations ✅ 840+ Icons - Optimized SVG icon library (@maz-ui/icons)

Template Structure

Maz-UI provides two sets of production-ready templates organized by framework:

Vue 3 + Vite Templates (templates/vue/ )

• ✅ Pure Vue 3 with Vite

• ✅ Uses standard fetch() API

• ✅ Explicit imports for all dependencies

• ✅ No framework-specific dependencies

• ✅ Optimized for SPA development

Use when: Building Vue 3 applications with Vite

Available templates:

• setup/vite.config.ts

• Vite configuration with auto-imports

• components/form-basic.vue

• Basic form validation

• components/form-multi-step.vue

• Multi-step form with stepper

• components/dialog-confirm.vue

• Dialog confirmation patterns

• components/data-table.vue

• Data table with pagination, search, sort

Nuxt 3 Templates (templates/nuxt/ )

• ✅ Nuxt 3 optimized

• ✅ Uses $fetch (Nuxt's ofetch wrapper)

• ✅ Leverages auto-imports for components and composables

• ✅ Showcases SSR patterns and server routes

• ✅ Optimized for full-stack Nuxt development

Use when: Building Nuxt 3 applications

Available templates:

• setup/nuxt.config.ts

• Nuxt configuration with Maz-UI module

• components/form-basic.vue

• Basic form validation (auto-imports)

• components/form-multi-step.vue

• Multi-step form (auto-imports)

• components/dialog-confirm.vue

• Dialog patterns (auto-imports)

• components/data-table.vue

• Data table with reactive data loading

Both template sets:

• ✅ Fix all validation, type inference, and pagination issues

• ✅ Follow framework best practices

• ✅ Are production-ready and fully tested

• ✅ Include setup configs and component examples

When to Load References

Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:

Components (4 files)

• components-forms.md

• Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePicker

• components-feedback.md

• Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlight

• components-navigation.md

• Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPagination

• components-layout.md

• Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallery

Setup & Configuration (2 files)

• setup-vue.md

• Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimization

• setup-nuxt.md

• Integrating with Nuxt 3, module configuration, theme strategies (hybrid/buildtime/runtime), SSR/SSG considerations

Core Features (5 files)

• composables.md

• Using all 14 composables: useToast, useTheme, useBreakpoints, useFormValidator, useTimer, useDialog, useTranslations, etc.

• directives.md

• Adding directives: v-tooltip, v-click-outside, v-lazy-img, v-zoom-img, v-fullscreen-img

• plugins.md

• Enabling plugins: AOS (animations on scroll), Dialog, Toast, Wait (loading states)

• resolvers.md

• CRITICAL: Auto-import configuration with MazComponentsResolver, MazDirectivesResolver, MazModulesResolver for optimal tree-shaking

• translations.md

• Implementing multi-language support (8 built-in languages), custom locales, lazy loading, SSR hydration

Tools & Integrations (3 files)

• icons.md

• Using @maz-ui/icons package (840+ icons), MazIcon component, icon sizing, colors, animations

• cli.md

• Using @maz-ui/cli (legacy v3), theme configuration, migration to v4 themes system

• mcp.md

• Setting up Model Context Protocol server for AI assistant integration (Claude Code, Claude Desktop, Cursor, Windsurf)

Advanced Topics (5 files)

• theming.md

• Customizing themes, dark mode, color schemes, CSS variables, 4 built-in presets (mazUi, ocean, pristine, obsidian)

• performance.md

• Bundle optimization, tree-shaking, lazy loading, code splitting, reducing bundle size from ~300KB to ~15KB

• ssr-ssg.md

• Comprehensive SSR/SSG guide: theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generation

• accessibility.md

• WCAG 2.1 AA compliance, keyboard navigation, screen reader support, ARIA attributes, color contrast

• form-validation.md

• useFormValidator deep dive, Valibot integration, 5 validation modes (lazy, aggressive, eager, blur, progressive), TypeScript type inference

Troubleshooting (2 files)

• migration-v4.md

• Upgrading from Maz-UI v3 to v4, breaking changes, API changes, component renames, TypeScript updates

• troubleshooting.md

• Debugging errors, common issues, configuration problems, SSR hydration, bundle size issues

Top 6 Common Errors

1. Missing Theme Plugin Error

Error: "useTheme must be used within MazUi plugin installation"

Cause: MazUi plugin not installed or theme composable disabled Fix:

// Vue app.use(MazUi, { theme: { preset: mazUi } })

// Nuxt export default defineNuxtConfig({ mazUi: { composables: { useTheme: true }, theme: { preset: 'maz-ui' } } })

2. Auto-Import Not Working (Nuxt)

Error: Components/composables not found despite Nuxt module installed Cause: Module not properly configured or cache issue Fix:

Clear Nuxt cache

rm -rf .nuxt node_modules/.cache pnpm install

Verify nuxt.config.ts :

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

3. Styles Not Applied

Error: Components render but have no styling Cause: CSS not imported Fix Vue:

import 'maz-ui/styles' // Add this line

Fix Nuxt:

export default defineNuxtConfig({ mazUi: { css: { injectMainCss: true } // Ensure this is true } })

4. TypeScript Errors with Components

Error: Cannot find module 'maz-ui/components/MazBtn'

Cause: Missing type definitions or incorrect import path Fix:

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

// Or with auto-import (Nuxt) // No import needed, just use <MazBtn>

Ensure tsconfig.json includes:

{ "compilerOptions": { "types": ["maz-ui/types"] } }

5. Phone Input Country Detection Fails

Error: MazInputPhoneNumber doesn't detect country or shows wrong flag Cause: Missing libphonenumber-js dependency or country data not loaded Fix:

Install peer dependency

pnpm add libphonenumber-js

<MazInputPhoneNumber v-model="phone" default-country-code="US" preferred-countries="['US', 'CA', 'GB']" />

6. Translations Not Loading or Showing Raw Keys

Error: Translation keys showing as raw strings like inputPhoneNumber.phoneInput.example instead of translated text Causes:

• Missing locale import

• Lazy loading not awaited properly

• Language file failed to load asynchronously

• Missing preloadFallback configuration

• SSR hydration mismatch (Nuxt)

Fix Vue (Immediate Loading):

import { fr } from '@maz-ui/translations'

app.use(MazUi, { translations: { locale: 'fr', fallbackLocale: 'en', preloadFallback: true, messages: { fr } // Import immediately } })

Fix Vue (Lazy Loading):

app.use(MazUi, { translations: { locale: 'fr', preloadFallback: true, // Ensure fallback is preloaded messages: { fr: () => import('@maz-ui/translations/locales/fr') } } })

// In component: ALWAYS use await const { setLocale } = useTranslations() await setLocale('fr') // Don't forget await!

Fix Nuxt (Avoid Hydration):

import { fr } from '@maz-ui/translations'

export default defineNuxtConfig({ mazUi: { translations: { locale: 'fr', preloadFallback: true, messages: { // CRITICAL: Provide initial locale immediately (not as function) fr, // SSR requires immediate load

    // Other languages can be lazy
    es: () => import('@maz-ui/translations/locales/es')
  }
}

} })

Error Handling:

<script setup> const { setLocale } = useTranslations() const toast = useToast()

async function switchLanguage(locale) { try { await setLocale(locale) toast.success(Language changed to ${locale}) } catch (error) { console.error('Translation loading error:', error) toast.error('Failed to load translations') } } </script>

Learn More: Load references/translations.md for comprehensive i18n setup, lazy loading strategies, and production patterns.

Tree-Shaking Best Practices

Direct Imports (Most Optimized):

// ✅✅✅ Best - smallest bundle import MazBtn from 'maz-ui/components/MazBtn' import { useToast } from 'maz-ui/composables/useToast' import { vClickOutside } from 'maz-ui/directives/vClickOutside'

Index Imports (Good):

// ✅ Good - tree-shakable import { MazBtn, MazInput } from 'maz-ui/components' import { useToast, useTheme } from 'maz-ui/composables'

Avoid (Not Tree-Shakable):

// ❌ Imports everything import * as MazUI from 'maz-ui'

Advanced Topics

Performance Optimization

Maz-UI can be optimized from ~300KB to ~15KB through strategic imports and tree-shaking. Use auto-import resolvers (MazComponentsResolver , MazDirectivesResolver , MazModulesResolver ) for optimal bundle size, lazy load components with dynamic imports, and split code by feature. Load performance.md for comprehensive bundle optimization strategies.

SSR & SSG

Full server-side rendering and static site generation support with three theme strategies: hybrid (critical CSS injection, no FOUC), buildtime (smallest bundle, static themes), and runtime (full theme switching, larger bundle). Prevent hydration mismatches by wrapping client-only components in <ClientOnly> . Load ssr-ssg.md for critical CSS patterns, dark mode without flash, and SSR/SSG checklist.

Accessibility

All Maz-UI components are WCAG 2.1 AA compliant with proper ARIA attributes, keyboard navigation, focus management, and screen reader support. Components include semantic HTML, color contrast ratios >4.5:1, and accessible form validation. Load accessibility.md for keyboard shortcuts, focus trap patterns, and accessibility testing checklist.

Form Validation

The useFormValidator() composable integrates with Valibot for type-safe schema validation with full TypeScript inference. Supports 5 validation modes (lazy, aggressive, eager, blur, progressive), async validation, custom validators, and real-time error messages. Load form-validation.md for comprehensive validation patterns and real-world examples.

Auto-Import Resolvers

Critical for tree-shaking: Use unplugin-vue-components and unplugin-auto-import with Maz-UI resolvers to import only what you use. Reduces bundle size by 60-90% compared to global imports. Configure prefix handling to avoid naming conflicts with other libraries. Load resolvers.md for complete resolver configuration and troubleshooting.

Progressive Disclosure Summary

This SKILL.md provides:

• Quick Start - Get running in <5 minutes

• Core Capabilities - Overview of all features

• Error Prevention - Top 5 common issues solved

For detailed implementation:

• Load reference files based on your current task (see "When to Load References" above)

• Each reference contains comprehensive guides, code examples, and advanced configurations

• References are organized by domain (components, setup, theming, etc.) for easy navigation

Package Ecosystem

• maz-ui - Core component library

• @maz-ui/nuxt - Nuxt 3 module with auto-imports

• @maz-ui/themes - Theming system and presets

• @maz-ui/translations - i18n support (8 built-in languages: en, fr, es, de, it, pt, ja, zh-CN)

• @maz-ui/icons - 840+ optimized SVG icons

• @maz-ui/mcp - AI agent documentation server

Official Resources

• Documentation: https://maz-ui.com

• GitHub: https://github.com/LouisMazel/maz-ui

• NPM: https://www.npmjs.com/package/maz-ui

• Discord: https://discord.gg/maz-ui

• Changelog: https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md