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/components-feedback.md
View on GitHub# Maz-UI Feedback & Animation Components Reference
Comprehensive guide to all Maz-UI feedback and animation components for creating engaging user experiences.
## Overview
Maz-UI provides **8 powerful feedback and animation components** for visual feedback, loading states, and interactive animations:
**Loading Indicators** (4 components):
- `MazFullscreenLoader` - Full-screen loading overlay
- `MazLoadingBar` - Horizontal progress bar
- `MazCircularProgressBar` - Circular progress indicator
- `MazReadingProgressBar` - Reading progress indicator
**Animations** (4 components):
- `MazAnimatedText` - Animated text effects
- `MazAnimatedElement` - Element animations on scroll/mount
- `MazAnimatedCounter` - Number counter animation
- `MazCardSpotlight` - Interactive spotlight effect on cards
**Key Features**:
- ✅ **Customizable** - Color, size, duration controls
- ✅ **Responsive** - Adapts to all screen sizes
- ✅ **Smooth Animations** - CSS-based for optimal performance
- ✅ **Accessible** - ARIA attributes and semantic HTML
- ✅ **SSR Compatible** - Works with Nuxt 3 server-side rendering
---
## MazFullscreenLoader
Full-screen loading overlay with customizable content and backdrop.
### Basic Usage
```vue
<script setup>
import { ref } from 'vue'
import MazFullscreenLoader from 'maz-ui/components/MazFullscreenLoader'
const isLoading = ref(false)
async function loadData() {
isLoading.value = true
try {
await fetchData()
} finally {
isLoading.value = false
}
}
</script>
<template>
<MazFullscreenLoader v-if="isLoading">
<p class="text-lg">Loading data...</p>
</MazFullscreenLoader>
<MazBtn @click="loadData">Load Data</MazBtn>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `color` | `string` | Backdrop color | `'rgba(0,0,0,0.5)'` |
| `blur` | `boolean` | Enable backdrop blur | `false` |
| `zIndex` | `number` | Z-index value | `9999` |
### Slots
| Slot | Description |
|------|-------------|
| `default` | Custom loader content (spinner, text, etc.) |
### Examples
**With Custom Spinner**:
```vue
<template>
<MazFullscreenLoader v-if="isLoading">
<MazSpinner size="lg" color="primary" />
<p class="mt-4 text-white">Please wait...</p>
</MazFullscreenLoader>
</template>
```
**With Blur Effect**:
```vue
<template>
<MazFullscreenLoader v-if="isProcessing" blur>
<div class="text-center">
<MazCircularProgressBar :percentage="progress" />
<p class="mt-2">Processing: {{ progress }}%</p>
</div>
</MazFullscreenLoader>
</template>
```
**Click to Dismiss**:
```vue
<script setup>
const showLoader = ref(true)
</script>
<template>
<MazFullscreenLoader
v-if="showLoader"
@click="showLoader = false"
>
<p>Click anywhere to close</p>
</MazFullscreenLoader>
</template>
```
---
## MazLoadingBar
Horizontal progress bar for page loading or task progress.
### Basic Usage
```vue
<script setup>
import MazLoadingBar from 'maz-ui/components/MazLoadingBar'
</script>
<template>
<MazLoadingBar color="primary" />
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `color` | `'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | Bar color | `'primary'` |
| `height` | `string` | Bar height (px, em, rem) | `'4px'` |
| `position` | `'top' \| 'bottom'` | Bar position | `'top'` |
| `speed` | `number` | Animation speed (ms) | `300` |
### Examples
**Page Loading Indicator**:
```vue
<script setup>
import { useRouter } from 'vue-router'
import { ref } from 'vue'
const router = useRouter()
const isLoading = ref(false)
router.beforeEach(() => {
isLoading.value = true
})
router.afterEach(() => {
isLoading.value = false
})
</script>
<template>
<MazLoadingBar v-if="isLoading" color="success" position="top" />
</template>
```
**Custom Styling**:
```vue
<template>
<MazLoadingBar
color="warning"
height="8px"
position="bottom"
:speed="500"
/>
</template>
```
---
## MazCircularProgressBar
Circular progress indicator with percentage display and animations.
### Basic Usage
```vue
<script setup>
import { ref } from 'vue'
import MazCircularProgressBar from 'maz-ui/components/MazCircularProgressBar'
const percentage = ref(75)
</script>
<template>
<MazCircularProgressBar
:percentage="percentage"
suffix="%"
/>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `percentage` | `number` | Progress percentage (0-100) | `0` |
| `size` | `string` | Component size (px, em, rem) | `'10rem'` |
| `color` | `'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | Progress color | `'primary'` |
| `autoColor` | `boolean` | Auto color based on percentage | `false` |
| `duration` | `number` | Animation duration (ms) | `1000` |
| `suffix` | `string` | Suffix text (e.g., '%') | `''` |
| `prefix` | `string` | Prefix text (e.g., '$') | `''` |
### Auto-Color Behavior
When `autoColor` is enabled:
- **0-49%** → `destructive` (red)
- **50-99%** → `warning` (orange)
- **100%** → `success` (green)
### Examples
**Different Sizes**:
```vue
<template>
<div class="flex gap-4">
<MazCircularProgressBar :percentage="75" size="3em" />
<MazCircularProgressBar :percentage="75" size="100px" />
<MazCircularProgressBar :percentage="75" size="10rem" />
<MazCircularProgressBar :percentage="75" size="15rem" />
</div>
</template>
```
**Custom Duration**:
```vue
<template>
<!-- Slow animation over 5 seconds -->
<MazCircularProgressBar
:percentage="100"
:duration="5000"
/>
</template>
```
**Different Colors**:
```vue
<template>
<div class="flex gap-4">
<MazCircularProgressBar :percentage="75" color="primary" />
<MazCircularProgressBar :percentage="75" color="secondary" />
<MazCircularProgressBar :percentage="75" color="success" />
<MazCircularProgressBar :percentage="75" color="warning" />
<MazCircularProgressBar :percentage="75" color="destructive" />
</div>
</template>
```
**Auto-Color Mode**:
```vue
<template>
<div class="flex gap-4">
<MazCircularProgressBar :percentage="0" auto-color /> <!-- Red -->
<MazCircularProgressBar :percentage="25" auto-color /> <!-- Red -->
<MazCircularProgressBar :percentage="50" auto-color /> <!-- Orange -->
<MazCircularProgressBar :percentage="100" auto-color /> <!-- Green -->
</div>
</template>
```
**Custom Slot Content**:
```vue
<template>
<MazCircularProgressBar :percentage="50">
2/4
</MazCircularProgressBar>
<MazCircularProgressBar :percentage="75">
<MazIcon name="check" />
</MazCircularProgressBar>
</template>
```
---
## MazReadingProgressBar
Reading progress indicator for articles and long-form content.
### Basic Usage
```vue
<script setup>
import MazReadingProgressBar from 'maz-ui/components/MazReadingProgressBar'
</script>
<template>
<MazReadingProgressBar color="primary" position="top" />
<article>
<!-- Long article content -->
</article>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `color` | `'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | Bar color | `'primary'` |
| `height` | `string` | Bar height | `'4px'` |
| `position` | `'top' \| 'bottom'` | Bar position | `'top'` |
| `target` | `string` | Target element selector | `'body'` |
### Examples
**Article Progress**:
```vue
<template>
<div>
<MazReadingProgressBar
color="success"
position="top"
height="6px"
target="#article-content"
/>
<div id="article-content">
<h1>Article Title</h1>
<p>Long article content...</p>
<!-- More content -->
</div>
</div>
</template>
```
**Custom Target Element**:
```vue
<template>
<div>
<MazReadingProgressBar target=".content-wrapper" />
<div class="content-wrapper">
<!-- Target content -->
</div>
</div>
</template>
```
---
## MazAnimatedText
Animated text effects with various animation styles.
### Basic Usage
```vue
<script setup>
import MazAnimatedText from 'maz-ui/components/MazAnimatedText'
</script>
<template>
<MazAnimatedText animation="fade-in">
Welcome to Maz-UI
</MazAnimatedText>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `animation` | `'fade-in' \| 'slide-up' \| 'slide-down' \| 'zoom-in' \| 'type'` | Animation type | `'fade-in'` |
| `duration` | `number` | Animation duration (ms) | `600` |
| `delay` | `number` | Animation delay (ms) | `0` |
| `once` | `boolean` | Animate only once | `true` |
### Animation Types
**fade-in**:
```vue
<template>
<MazAnimatedText animation="fade-in">
Fade in animation
</MazAnimatedText>
</template>
```
**slide-up**:
```vue
<template>
<MazAnimatedText animation="slide-up">
Slide up from bottom
</MazAnimatedText>
</template>
```
**zoom-in**:
```vue
<template>
<MazAnimatedText animation="zoom-in" :duration="1000">
Zoom in effect
</MazAnimatedText>
</template>
```
**type** (typewriter effect):
```vue
<template>
<MazAnimatedText animation="type" :duration="2000">
Typewriter effect...
</MazAnimatedText>
</template>
```
### Examples
**Delayed Animation**:
```vue
<template>
<div>
<MazAnimatedText animation="slide-up" :delay="0">
First line
</MazAnimatedText>
<MazAnimatedText animation="slide-up" :delay="200">
Second line (200ms delay)
</MazAnimatedText>
<MazAnimatedText animation="slide-up" :delay="400">
Third line (400ms delay)
</MazAnimatedText>
</div>
</template>
```
**Repeating Animation**:
```vue
<template>
<MazAnimatedText animation="fade-in" :once="false">
This animates every time it enters viewport
</MazAnimatedText>
</template>
```
---
## MazAnimatedElement
Generic element animation wrapper with scroll-triggered animations.
### Basic Usage
```vue
<script setup>
import MazAnimatedElement from 'maz-ui/components/MazAnimatedElement'
</script>
<template>
<MazAnimatedElement animation="fade-up">
<MazCard>
<h2>Animated Card</h2>
<p>This card animates when scrolled into view</p>
</MazCard>
</MazAnimatedElement>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `animation` | `string` | Animation name (AOS-compatible) | `'fade-up'` |
| `duration` | `number` | Animation duration (ms) | `600` |
| `delay` | `number` | Animation delay (ms) | `0` |
| `once` | `boolean` | Animate only once | `true` |
| `offset` | `number` | Trigger offset (px) | `120` |
### Animation Names
All AOS animations are supported:
- **Fade**: `fade-up`, `fade-down`, `fade-left`, `fade-right`
- **Zoom**: `zoom-in`, `zoom-out`, `zoom-in-up`, `zoom-in-down`
- **Slide**: `slide-up`, `slide-down`, `slide-left`, `slide-right`
- **Flip**: `flip-left`, `flip-right`, `flip-up`, `flip-down`
### Examples
**Card Grid Animation**:
```vue
<template>
<div class="grid grid-cols-3 gap-4">
<MazAnimatedElement
v-for="(item, i) in items"
:key="item.id"
animation="fade-up"
:delay="i * 100"
>
<MazCard>
{{ item.title }}
</MazCard>
</MazAnimatedElement>
</div>
</template>
```
**Different Animations**:
```vue
<template>
<MazAnimatedElement animation="zoom-in">
<div>Zooms in</div>
</MazAnimatedElement>
<MazAnimatedElement animation="slide-left">
<div>Slides from right</div>
</MazAnimatedElement>
<MazAnimatedElement animation="flip-up">
<div>Flips up</div>
</MazAnimatedElement>
</template>
```
---
## MazAnimatedCounter
Animated number counter with prefix/suffix support.
### Basic Usage
```vue
<script setup>
import { ref } from 'vue'
import MazAnimatedCounter from 'maz-ui/components/MazAnimatedCounter'
const count = ref(1000)
</script>
<template>
<MazAnimatedCounter :count="count" />
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `count` | `number` | Target number to count to | `0` |
| `duration` | `number` | Animation duration (ms) | `1000` |
| `prefix` | `string` | Prefix text (e.g., '$') | `''` |
| `suffix` | `string` | Suffix text (e.g., '%') | `''` |
| `decimals` | `number` | Decimal places | `0` |
### Slots
| Slot | Description |
|------|-------------|
| `prefix` | Custom prefix content |
| `suffix` | Custom suffix content |
### Examples
**Currency Counter**:
```vue
<template>
<MazAnimatedCounter :count="2999.99" prefix="$" :decimals="2" />
<!-- Output: $2,999.99 -->
</template>
```
**Percentage Counter**:
```vue
<template>
<MazAnimatedCounter :count="75" suffix="%" />
<!-- Output: 75% -->
</template>
```
**Custom Duration**:
```vue
<template>
<MazAnimatedCounter
:count="10000"
:duration="5000"
prefix="$"
/>
<!-- Counts to $10,000 over 5 seconds -->
</template>
```
**Prefix/Suffix Slots**:
```vue
<template>
<MazAnimatedCounter :count="20">
<template #prefix>
<MazIcon name="dollar" class="mr-1" />
</template>
<template #suffix>
<span class="ml-1 text-sm">USD</span>
</template>
</MazAnimatedCounter>
</template>
```
**Reactive Counter**:
```vue
<script setup>
import { ref, onMounted } from 'vue'
const count = ref(0)
onMounted(() => {
// Update counter every 3 seconds
setInterval(() => {
count.value = Math.floor(Math.random() * 10000)
}, 3000)
})
</script>
<template>
<MazAnimatedCounter :count="count" prefix="$" />
</template>
```
---
## MazCardSpotlight
Interactive card with animated spotlight effect that follows cursor.
### Basic Usage
```vue
<script setup>
import MazCardSpotlight from 'maz-ui/components/MazCardSpotlight'
</script>
<template>
<MazCardSpotlight>
<h3>Spotlight Card</h3>
<p>Hover to see the spotlight effect</p>
</MazCardSpotlight>
</template>
```
### Props
| Prop | Type | Description | Default |
|------|------|-------------|---------|
| `color` | `string` | Spotlight color (CSS color) | `'rgba(255,255,255,0.1)'` |
| `intensity` | `number` | Spotlight intensity (0-1) | `0.3` |
| `size` | `number` | Spotlight size (px) | `300` |
| `disabled` | `boolean` | Disable spotlight effect | `false` |
### Examples
**Custom Spotlight Color**:
```vue
<template>
<MazCardSpotlight color="rgba(59, 130, 246, 0.2)">
<h3>Blue Spotlight</h3>
<p>Custom blue spotlight effect</p>
</MazCardSpotlight>
</template>
```
**Intense Spotlight**:
```vue
<template>
<MazCardSpotlight :intensity="0.8" :size="500">
<h3>Intense Effect</h3>
<p>Larger, more intense spotlight</p>
</MazCardSpotlight>
</template>
```
**Conditional Spotlight**:
```vue
<script setup>
const isPremium = ref(true)
</script>
<template>
<MazCardSpotlight :disabled="!isPremium">
<h3>{{ isPremium ? 'Premium' : 'Basic' }} Card</h3>
<p>Spotlight only for premium users</p>
</MazCardSpotlight>
</template>
```
**Card Grid with Spotlights**:
```vue
<template>
<div class="grid grid-cols-3 gap-4">
<MazCardSpotlight
v-for="product in products"
:key="product.id"
color="rgba(16, 185, 129, 0.15)"
>
<h4>{{ product.name }}</h4>
<p>{{ product.price }}</p>
<MazBtn color="success">Buy Now</MazBtn>
</MazCardSpotlight>
</div>
</template>
```
---
## Best Practices
### Loading States
**DO**:
- Use `MazFullscreenLoader` for critical operations that block user interaction
- Use `MazLoadingBar` for page/route transitions
- Use `MazCircularProgressBar` to show determinate progress
- Provide meaningful loading messages
**DON'T**:
- Use fullscreen loader for minor operations
- Show multiple loading indicators simultaneously
- Leave users without feedback during long operations
```vue
<!-- ✅ Good: Clear loading state with message -->
<MazFullscreenLoader v-if="isProcessing">
<MazCircularProgressBar :percentage="progress" />
<p class="mt-2">Processing {{ currentFile }} ({{ progress }}%)</p>
</MazFullscreenLoader>
<!-- ❌ Bad: No context or progress indication -->
<MazFullscreenLoader v-if="isProcessing" />
```
### Progress Indicators
**DO**:
- Use `auto-color` for intuitive progress feedback
- Show percentage when possible
- Animate progress smoothly
- Update progress in real-time
**DON'T**:
- Show fake progress without actual data
- Use indeterminate progress for long operations
- Forget to handle 100% completion state
```vue
<!-- ✅ Good: Real progress with auto-color -->
<MazCircularProgressBar
:percentage="uploadProgress"
auto-color
suffix="%"
/>
<!-- ❌ Bad: Static fake progress -->
<MazCircularProgressBar :percentage="50" />
```
### Animations
**DO**:
- Use subtle animations for better UX
- Set appropriate animation durations (300-600ms)
- Use `once: true` for performance
- Match animation style to content
**DON'T**:
- Over-animate every element
- Use very long animations (>2s)
- Animate critical content on every scroll
```vue
<!-- ✅ Good: Subtle, performant animations -->
<MazAnimatedElement
v-for="item in items"
:key="item.id"
animation="fade-up"
:duration="400"
once
>
<MazCard>{{ item.title }}</MazCard>
</MazAnimatedElement>
<!-- ❌ Bad: Excessive animation -->
<MazAnimatedElement
animation="flip-left"
:duration="3000"
:once="false"
>
<p>Critical navigation content</p>
</MazAnimatedElement>
```
---
## Accessibility
### Screen Readers
All feedback components include proper ARIA attributes:
```vue
<!-- Fullscreen loader with ARIA -->
<MazFullscreenLoader
v-if="isLoading"
role="status"
aria-live="polite"
aria-label="Loading content"
>
<p>Loading...</p>
</MazFullscreenLoader>
<!-- Progress bar with ARIA -->
<MazCircularProgressBar
:percentage="75"
role="progressbar"
:aria-valuenow="75"
aria-valuemin="0"
aria-valuemax="100"
aria-label="Upload progress"
/>
```
### Reduced Motion
Respect user's motion preferences:
```vue
<script setup>
import { ref, computed, onMounted } from 'vue'
const prefersReducedMotion = ref(false)
// ✅ Client-only: Access window after mount
onMounted(() => {
prefersReducedMotion.value = window.matchMedia('(prefers-reduced-motion: reduce)').matches
})
const animationDuration = computed(() =>
prefersReducedMotion.value ? 0 : 600
)
</script>
<template>
<MazAnimatedText :duration="animationDuration">
Respects motion preferences
</MazAnimatedText>
</template>
```
---
## SSR Compatibility
All feedback components are SSR-safe:
```vue
<!-- Nuxt 3 - Works automatically -->
<template>
<div>
<MazFullscreenLoader v-if="isLoading" />
<MazAnimatedElement animation="fade-up">
<MazCard>SSR-safe content</MazCard>
</MazAnimatedElement>
</div>
</template>
```
**Hydration Notes**:
- Animations trigger after hydration completes
- Progress states sync correctly server → client
- No layout shift issues with loaders
---
## Related Documentation
- **[Components Forms](./components-forms.md)** - Form input components
- **[Components Navigation](./components-navigation.md)** - Navigation components
- **[Components Layout](./components-layout.md)** - Layout and container components
- **[Composables Reference](./composables.md)** - useWait, useAos composables
- **[Plugins Reference](./plugins.md)** - AOS plugin for scroll animations
---
**Version**: Maz-UI v4.9.3
**Last Updated**: 2025-12-14
**Component Count**: 8 feedback & animation components
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 |