secondsky/claude-skills / plugins/maz-ui/skills/maz-ui
maz-ui
VerifiedMaz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/accessibility.md | markdown | 16.2 KB |
| references/cli.md | markdown | 10.8 KB |
| references/components-feedback.md | markdown | 19.1 KB |
| references/components-forms.md | markdown | 8.4 KB |
| references/components-layout.md | markdown | 17.8 KB |
| references/components-navigation.md | markdown | 19.5 KB |
| references/composables.md | markdown | 28.3 KB |
| references/directives.md | markdown | 17.0 KB |
| references/form-validation.md | markdown | 22.7 KB |
| references/icons.md | markdown | 14.9 KB |
| references/mcp.md | markdown | 13.6 KB |
| references/migration-v4.md | markdown | 21.0 KB |
| references/performance.md | markdown | 17.0 KB |
| references/plugins.md | markdown | 25.1 KB |
| references/resolvers.md | markdown | 26.2 KB |
| references/setup-nuxt.md | markdown | 26.0 KB |
| references/setup-vue.md | markdown | 21.7 KB |
| references/ssr-ssg.md | markdown | 13.9 KB |
| references/theming.md | markdown | 7.2 KB |
| references/translations.md | markdown | 20.1 KB |
| references/troubleshooting.md | markdown | 9.0 KB |
references/form-validation.md
View on GitHub---
name: "Maz-UI Form Validation Reference"
description: "Complete guide to form validation in Maz-UI using useFormValidator composable with Valibot integration"
version: "4.9.3"
framework: "Vue 3 / Nuxt 3"
---
# Maz-UI Form Validation Guide
Complete guide to form validation in Maz-UI using the `useFormValidator` composable with Valibot integration.
## Overview
Maz-UI provides a powerful form validation system through the `useFormValidator` composable, offering:
- 🔒 TypeScript type safety (automatic type inference from schemas)
- 📝 5 validation modes (lazy, aggressive, eager, blur, progressive)
- ✅ Valibot integration (60+ built-in validators)
- 🎯 Field-level validation states
- 🚀 Async validation support
- ♿ Accessibility built-in (ARIA attributes)
---
## Basic Setup
### Installation
```bash
npm install valibot
```
### Framework Differences: Vue vs Nuxt
This guide shows examples for both **Vue 3** and **Nuxt 3**. The key differences:
**Vue 3 + Vite**:
- ✅ Explicit imports required: `import { ref } from 'vue'`
- ✅ Import Maz-UI: `import { useFormValidator } from 'maz-ui/composables'`
- ✅ Import Valibot: `import { string, email, pipe } from 'valibot'`
**Nuxt 3**:
- ✅ Auto-imports enabled (no import statements needed)
- ✅ `ref`, `computed`, `watch` - auto-imported from Vue
- ✅ `useFormValidator`, `useToast` - auto-imported from Maz-UI
- ✅ `string`, `email`, `pipe` - auto-imported from Valibot
Throughout this guide, examples will show both versions where they differ.
---
### Simple Form Validation
#### Vue 3 + Vite
```vue
<script setup lang="ts">
import { useFormValidator } from 'maz-ui/composables'
import { string, email, pipe, minLength, nonEmpty } from 'valibot'
// Define validation schema
const schema = {
email: pipe(
string('Email is required'),
nonEmpty('Email is required'),
email('Invalid email format')
),
password: pipe(
string('Password is required'),
minLength(8, 'Password must be at least 8 characters')
)
}
// Initialize form validator
const {
model,
isSubmitting,
errorMessages,
fieldsStates,
handleSubmit
} = useFormValidator({ schema })
// Submit handler
const onSubmit = handleSubmit(async (formData) => {
console.log('Valid form data:', formData)
// formData is fully typed from schema
await api.login(formData.email, formData.password)
})
</script>
<template>
<form @submit.prevent="onSubmit">
<MazInput
v-model="model.email"
label="Email"
type="email"
:error="errorMessages.email"
:success="fieldsStates.email.valid"
/>
<MazInput
v-model="model.password"
label="Password"
type="password"
:error="errorMessages.password"
:success="fieldsStates.password.valid"
/>
<MazBtn type="submit" :loading="isSubmitting">
Login
</MazBtn>
</form>
</template>
```
#### Nuxt 3
```vue
<script setup lang="ts">
// ✅ No imports needed - auto-imported!
// useFormValidator, string, email, pipe, minLength, nonEmpty all available
// Define validation schema
const schema = {
email: pipe(
string('Email is required'),
nonEmpty('Email is required'),
email('Invalid email format')
),
password: pipe(
string('Password is required'),
minLength(8, 'Password must be at least 8 characters')
)
}
// Initialize form validator
const {
model,
isSubmitting,
errorMessages,
fieldsStates,
handleSubmit
} = useFormValidator({ schema })
// Submit handler
const onSubmit = handleSubmit(async (formData) => {
console.log('Valid form data:', formData)
// formData is fully typed from schema
// ✅ Nuxt: Use $fetch
await $fetch('/api/login', {
method: 'POST',
body: { email: formData.email, password: formData.password }
})
})
</script>
<template>
<form @submit.prevent="onSubmit">
<MazInput
v-model="model.email"
label="Email"
type="email"
:error="errorMessages.email"
:success="fieldsStates.email.valid"
/>
<MazInput
v-model="model.password"
label="Password"
type="password"
:error="errorMessages.password"
:success="fieldsStates.password.valid"
/>
<MazBtn type="submit" :loading="isSubmitting">
Login
</MazBtn>
</form>
</template>
```
---
## Validation Modes
### Lazy Mode (Default)
**Validates**: On submit only
```typescript
const { model, handleSubmit } = useFormValidator({
schema,
mode: 'lazy' // Default
})
```
**Best for**:
- Simple forms
- One-time submission
- Minimal validation UX
**User experience**:
- No validation on input
- Errors appear after submit attempt
- Fast initial interaction
---
### Aggressive Mode
**Validates**: On every keystroke
```typescript
const { model } = useFormValidator({
schema,
mode: 'aggressive'
})
```
**Best for**:
- Complex validation rules
- Real-time feedback needed
- Password strength meters
**User experience**:
- Immediate validation feedback
- Can be overwhelming for users
- Best for technical users
**Example**: Password strength indicator
```vue
<script setup lang="ts">
// ✅ Vue 3: Explicit imports
import { useFormValidator } from 'maz-ui/composables'
import { pipe, string, minLength, custom } from 'valibot'
const schema = {
password: pipe(
string(),
minLength(8),
custom((value) => {
const hasUppercase = /[A-Z]/.test(value)
const hasLowercase = /[a-z]/.test(value)
const hasNumber = /[0-9]/.test(value)
const hasSpecial = /[!@#$%^&*]/.test(value)
return hasUppercase && hasLowercase && hasNumber && hasSpecial
}, 'Password must include uppercase, lowercase, number, and special character')
)
}
const { model, errorMessages } = useFormValidator({
schema,
mode: 'aggressive' // Instant feedback
})
</script>
<template>
<MazInput
v-model="model.password"
label="Password"
type="password"
:error="errorMessages.password"
hint="Must include uppercase, lowercase, number, and special character"
/>
</template>
```
---
### Eager Mode
**Validates**: On input change after first blur
```typescript
const { model } = useFormValidator({
schema,
mode: 'eager'
})
```
**Best for**:
- Most forms (recommended)
- Balance between UX and validation
- Standard web applications
**User experience**:
- No validation until user leaves field
- Then validates on every change
- Good balance of feedback
---
### Blur Mode
**Validates**: Only when field loses focus
```typescript
const { model } = useFormValidator({
schema,
mode: 'blur'
})
```
**Best for**:
- Long forms
- Reduced visual noise
- Mobile forms (less intrusive)
**User experience**:
- Validation appears after leaving field
- Less intrusive than aggressive
- Cleaner form appearance
---
### Progressive Mode
**Validates**: Progressively as form is filled
```typescript
const { model } = useFormValidator({
schema,
mode: 'progressive'
})
```
**Best for**:
- Multi-step forms
- Wizard-style interfaces
- Sequential input patterns
**User experience**:
- Validates completed fields first
- Guides user through form
- Reduces cognitive load
---
## Valibot Schema Patterns
### Basic Validators
```typescript
import {
string,
number,
boolean,
array,
object,
pipe,
nonEmpty,
email,
url,
minLength,
maxLength,
minValue,
maxValue,
regex
} from 'valibot'
const schema = {
// String validation
name: pipe(
string('Name is required'),
nonEmpty('Name cannot be empty'),
minLength(2, 'Name must be at least 2 characters')
),
// Email validation
email: pipe(
string(),
email('Invalid email format')
),
// Number validation
age: pipe(
number('Age must be a number'),
minValue(18, 'Must be 18 or older'),
maxValue(120, 'Invalid age')
),
// Boolean validation
terms: pipe(
boolean(),
custom((value) => value === true, 'You must accept the terms')
),
// URL validation
website: pipe(
string(),
url('Invalid URL format')
),
// Pattern validation
phone: pipe(
string(),
regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number')
)
}
```
---
### Custom Validators
```typescript
import { custom, string, pipe } from 'valibot'
const schema = {
username: pipe(
string(),
minLength(3),
custom((value) => {
// No spaces allowed
return !value.includes(' ')
}, 'Username cannot contain spaces'),
custom((value) => {
// Only alphanumeric and underscore
return /^[a-zA-Z0-9_]+$/.test(value)
}, 'Username can only contain letters, numbers, and underscores')
),
// Password strength
password: pipe(
string(),
minLength(8),
custom((value) => {
const strength = calculatePasswordStrength(value)
return strength >= 3 // Strong password
}, 'Password is too weak')
)
}
function calculatePasswordStrength(password: string): number {
let strength = 0
if (password.length >= 8) strength++
if (/[A-Z]/.test(password)) strength++
if (/[0-9]/.test(password)) strength++
if (/[!@#$%^&*]/.test(password)) strength++
return strength
}
```
---
### Async Validation
```typescript
import { customAsync } from 'valibot'
const schema = {
username: pipe(
string(),
minLength(3),
customAsync(async (value) => {
// Check if username is available
const response = await fetch(`/api/check-username?username=${value}`)
const { available } = await response.json()
return available
}, 'Username is already taken')
),
email: pipe(
string(),
email(),
customAsync(async (value) => {
// Check if email is registered
const response = await fetch(`/api/check-email?email=${value}`)
const { exists } = await response.json()
return !exists
}, 'Email is already registered')
)
}
```
---
### Conditional Validation
```typescript
import { object, string, pipe, optional, custom } from 'valibot'
const schema = object({
shippingMethod: string(),
// Only validate if shipping method is 'express'
expressDate: pipe(
string(),
custom((value, context) => {
const shippingMethod = context.dataset.shippingMethod
if (shippingMethod === 'express' && !value) {
return false
}
return true
}, 'Express shipping requires a delivery date')
),
// Optional field with validation when provided
promoCode: optional(pipe(
string(),
regex(/^PROMO[0-9]{4}$/, 'Invalid promo code format')
))
})
```
---
## Real-World Form Examples
### Multi-Step Registration Form
```vue
<script setup lang="ts">
// ✅ Vue 3: Explicit imports
import { ref } from 'vue'
import { useFormValidator } from 'maz-ui/composables'
import { string, email, pipe, minLength, boolean } from 'valibot'
const currentStep = ref(1)
// Step 1: Personal Info
const step1Schema = {
firstName: pipe(string(), minLength(2)),
lastName: pipe(string(), minLength(2)),
email: pipe(string(), email())
}
const step1 = useFormValidator({
schema: step1Schema,
mode: 'eager'
})
// Step 2: Account
const step2Schema = {
username: pipe(string(), minLength(3)),
password: pipe(string(), minLength(8))
}
const step2 = useFormValidator({
schema: step2Schema,
mode: 'eager'
})
// Step 3: Preferences
const step3Schema = {
newsletter: boolean(),
notifications: boolean()
}
const step3 = useFormValidator({
schema: step3Schema
})
const nextStep = step1.handleSubmit(() => {
currentStep.value = 2
})
const nextStep2 = step2.handleSubmit(() => {
currentStep.value = 3
})
const finalSubmit = step3.handleSubmit(async () => {
const allData = {
...step1.model,
...step2.model,
...step3.model
}
await api.register(allData)
toast.success('Registration complete!')
})
</script>
<template>
<MazStepper v-model="currentStep" :steps="3" />
<!-- Step 1: Personal Info -->
<form v-if="currentStep === 1" @submit.prevent="nextStep">
<MazInput
v-model="step1.model.firstName"
label="First Name"
:error="step1.errorMessages.firstName"
/>
<MazInput
v-model="step1.model.lastName"
label="Last Name"
:error="step1.errorMessages.lastName"
/>
<MazInput
v-model="step1.model.email"
label="Email"
type="email"
:error="step1.errorMessages.email"
/>
<MazBtn type="submit">Next</MazBtn>
</form>
<!-- Step 2: Account -->
<form v-if="currentStep === 2" @submit.prevent="nextStep2">
<MazInput
v-model="step2.model.username"
label="Username"
:error="step2.errorMessages.username"
/>
<MazInput
v-model="step2.model.password"
label="Password"
type="password"
:error="step2.errorMessages.password"
/>
<MazBtn @click="currentStep = 1">Back</MazBtn>
<MazBtn type="submit">Next</MazBtn>
</form>
<!-- Step 3: Preferences -->
<form v-if="currentStep === 3" @submit.prevent="finalSubmit">
<MazCheckbox
v-model="step3.model.newsletter"
label="Subscribe to newsletter"
/>
<MazCheckbox
v-model="step3.model.notifications"
label="Enable notifications"
/>
<MazBtn @click="currentStep = 2">Back</MazBtn>
<MazBtn type="submit" :loading="step3.isSubmitting">
Complete Registration
</MazBtn>
</form>
</template>
```
---
### Dynamic Form with Conditional Fields
```vue
<script setup lang="ts">
// ✅ Vue 3: Explicit imports
import { ref, computed, watch } from 'vue'
import { useFormValidator } from 'maz-ui/composables'
import { string, email, pipe, minLength, regex } from 'valibot'
const accountType = ref('personal')
const schema = computed(() => ({
accountType: string(),
// Personal account fields
...(accountType.value === 'personal' && {
firstName: pipe(string(), minLength(2)),
lastName: pipe(string(), minLength(2))
}),
// Business account fields
...(accountType.value === 'business' && {
companyName: pipe(string(), minLength(2)),
taxId: pipe(string(), regex(/^\d{2}-\d{7}$/))
}),
email: pipe(string(), email())
}))
const { model, errorMessages, handleSubmit } = useFormValidator({
schema,
mode: 'eager'
})
watch(accountType, (newType) => {
model.accountType = newType
})
const onSubmit = handleSubmit(async (data) => {
await api.createAccount(data)
})
</script>
<template>
<form @submit.prevent="onSubmit">
<MazSelect
v-model="accountType"
label="Account Type"
:options="[
{ value: 'personal', label: 'Personal' },
{ value: 'business', label: 'Business' }
]"
/>
<!-- Personal fields -->
<template v-if="accountType === 'personal'">
<MazInput
v-model="model.firstName"
label="First Name"
:error="errorMessages.firstName"
/>
<MazInput
v-model="model.lastName"
label="Last Name"
:error="errorMessages.lastName"
/>
</template>
<!-- Business fields -->
<template v-if="accountType === 'business'">
<MazInput
v-model="model.companyName"
label="Company Name"
:error="errorMessages.companyName"
/>
<MazInput
v-model="model.taxId"
label="Tax ID"
placeholder="XX-XXXXXXX"
:error="errorMessages.taxId"
/>
</template>
<MazInput
v-model="model.email"
label="Email"
type="email"
:error="errorMessages.email"
/>
<MazBtn type="submit">Create Account</MazBtn>
</form>
</template>
```
---
## Error Handling Patterns
### Field-Level Errors
```vue
<script setup lang="ts">
const { model, errorMessages, fieldsStates } = useFormValidator({ schema })
</script>
<template>
<MazInput
v-model="model.email"
label="Email"
:error="errorMessages.email"
:success="fieldsStates.email.valid"
:warning="fieldsStates.email.validating"
/>
</template>
```
---
### Global Error Messages
```vue
<script setup lang="ts">
const { errorMessages, hasErrors } = useFormValidator({ schema })
const globalErrors = computed(() => {
return Object.values(errorMessages).filter(Boolean)
})
</script>
<template>
<MazAlert v-if="hasErrors" color="destructive">
<ul>
<li v-for="error in globalErrors" :key="error">
{{ error }}
</li>
</ul>
</MazAlert>
</template>
```
---
### Custom Error Messages
```typescript
const schema = {
password: pipe(
string(),
minLength(8, 'Too short!'), // Custom message
custom((value) => {
return /[A-Z]/.test(value)
}, 'Needs uppercase letter') // Custom message
)
}
```
---
## TypeScript Type Inference
### Automatic Type Safety
```typescript
const schema = {
name: string(),
age: number(),
email: pipe(string(), email()),
newsletter: boolean()
}
const { model, handleSubmit } = useFormValidator({ schema })
// model is fully typed:
// {
// name: string
// age: number
// email: string
// newsletter: boolean
// }
const onSubmit = handleSubmit((data) => {
// data is fully typed (same as model)
console.log(data.name) // ✅ string
console.log(data.age) // ✅ number
// console.log(data.unknown) // ❌ TypeScript error
})
```
---
### Complex Type Inference
```typescript
import { object, array, string, number } from 'valibot'
const schema = object({
user: object({
name: string(),
age: number()
}),
tags: array(string()),
settings: object({
notifications: boolean()
})
})
const { model } = useFormValidator({ schema })
// model is typed as:
// {
// user: {
// name: string
// age: number
// }
// tags: string[]
// settings: {
// notifications: boolean
// }
// }
```
---
## Performance Optimization
### Debouncing Validation
```vue
<script setup lang="ts">
import { useDebounceFn } from '@vueuse/core'
const schema = {
username: pipe(
string(),
customAsync(async (value) => {
const { available } = await api.checkUsername(value)
return available
}, 'Username taken')
)
}
const { model, errorMessages } = useFormValidator({
schema,
mode: 'eager'
})
// Debounce username validation to avoid excessive API calls
const debouncedValidation = useDebounceFn(() => {
// Validation happens automatically via useFormValidator
}, 500)
watch(() => model.username, debouncedValidation)
</script>
<template>
<MazInput
v-model="model.username"
label="Username"
:error="errorMessages.username"
hint="Checking availability..."
/>
</template>
```
---
### Conditional Validation
Only validate when necessary:
```typescript
const schema = computed(() => {
const base = {
email: pipe(string(), email())
}
// Only add password validation for new users
if (!props.isEditing) {
base.password = pipe(string(), minLength(8))
}
return base
})
const { model } = useFormValidator({ schema })
```
---
## Testing Form Validation
### Unit Testing
```typescript
// forms/login.test.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import LoginForm from './LoginForm.vue'
describe('LoginForm', () => {
it('should show error for invalid email', async () => {
const wrapper = mount(LoginForm)
const emailInput = wrapper.find('input[type="email"]')
await emailInput.setValue('invalid-email')
await emailInput.trigger('blur')
await wrapper.vm.$nextTick()
expect(wrapper.text()).toContain('Invalid email format')
})
it('should submit with valid data', async () => {
const wrapper = mount(LoginForm)
await wrapper.find('input[type="email"]').setValue('user@example.com')
await wrapper.find('input[type="password"]').setValue('password123')
await wrapper.find('form').trigger('submit')
// Assert API was called with correct data
expect(mockApi.login).toHaveBeenCalledWith({
email: 'user@example.com',
password: 'password123'
})
})
})
```
---
### E2E Testing
```typescript
// e2e/registration.spec.ts
import { test, expect } from '@playwright/test'
test('registration form validation', async ({ page }) => {
await page.goto('/register')
// Submit without filling form
await page.click('button[type="submit"]')
// Check error messages appear
await expect(page.locator('text=Email is required')).toBeVisible()
await expect(page.locator('text=Password is required')).toBeVisible()
// Fill valid data
await page.fill('input[name="email"]', 'user@example.com')
await page.fill('input[name="password"]', 'SecurePass123!')
// Submit
await page.click('button[type="submit"]')
// Check success
await expect(page.locator('text=Registration successful')).toBeVisible()
})
```
---
## Accessibility Considerations
### ARIA Attributes
```vue
<template>
<MazInput
v-model="model.email"
label="Email"
:error="errorMessages.email"
:aria-invalid="!!errorMessages.email"
:aria-describedby="errorMessages.email ? 'email-error' : undefined"
/>
<span
v-if="errorMessages.email"
id="email-error"
role="alert"
class="error-message"
>
{{ errorMessages.email }}
</span>
</template>
```
**Generated HTML**:
```html
<input
type="email"
aria-invalid="true"
aria-describedby="email-error"
/>
<span id="email-error" role="alert">
Invalid email format
</span>
```
---
### Live Regions
```vue
<template>
<div aria-live="polite" aria-atomic="true">
<span v-if="fieldsStates.email.validating">
Checking email availability...
</span>
<span v-else-if="fieldsStates.email.valid">
Email is available
</span>
</div>
</template>
```
---
## Validation Checklist
### Form-Level
- [ ] **Validation mode** chosen based on UX requirements
- [ ] **Error messages** clear and actionable
- [ ] **Success states** shown for valid fields
- [ ] **Submit button** disabled during submission
- [ ] **Loading states** shown during async validation
- [ ] **ARIA attributes** properly set (`aria-invalid`, `aria-describedby`)
### Field-Level
- [ ] **Required fields** marked with `*` or "(required)"
- [ ] **Password fields** use `type="password"`
- [ ] **Email fields** use `type="email"` + email validator
- [ ] **Number fields** use appropriate min/max validators
- [ ] **Custom validators** have clear error messages
- [ ] **Async validators** debounced to avoid excessive API calls
---
## Related Documentation
- **[Composables](./composables.md)** - useFormValidator API reference
- **[Components Forms](./components-forms.md)** - Form components
- **[Accessibility](./accessibility.md)** - Form accessibility
- **[Troubleshooting](./troubleshooting.md)** - Common validation errors
---
## External Resources
- **[Valibot Documentation](https://valibot.dev/)** - Complete Valibot guide
- **[Valibot Validators](https://valibot.dev/api/)** - All built-in validators
- **[ARIA Forms](https://www.w3.org/WAI/ARIA/apg/patterns/forms/)** - ARIA form patterns
---
**Form Validation Version**: Maz-UI v4.9.3 + Valibot
**Last Updated**: 2025-12-29
::: tip Validation Mode Recommendation
For most forms, use `mode: 'eager'` for the best balance between user experience and validation feedback. It validates after the first blur, then on every change.
:::
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |