Maz UI

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.9.3 (as of 2026-08-03) 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