# Variants
> Define reusable animation states and orchestrate complex animations across component trees
**Source:** [https://motion.svelte.page/docs/variants](https://motion.svelte.page/docs/variants)
---
Variants allow you to define named animation states that can be referenced throughout your component tree. They're perfect for creating reusable animations and orchestrating complex sequences.
## Basic usage
Instead of defining animation objects inline, you can create a `Variants` object with named states:
```svelte
isOpen = !isOpen}
>
Click me
```
> Live example: [/examples/variants-basic](https://motion.svelte.page/examples/variants-basic)
## Benefits
### 1. Reusable animation definitions
Define your animation states once and reference them by name throughout your components:
```svelte
```
### 2. Clean state management
Variants work beautifully with Svelte's reactive state:
```svelte
{status}
```
### 3. Simplified animation orchestration
Variants make it easy to coordinate animations across multiple elements without prop drilling.
## Variant propagation
One of the most powerful features of variants is **automatic propagation** through component trees. When a parent component changes its animation state, all children with matching variant names will animate automatically.
```svelte
Item 1Item 2Item 3
```
> Live example: [/examples/variants-propagation](https://motion.svelte.page/examples/variants-propagation)
### How propagation works
1. Parent component sets `animate="visible"`
2. Children with `variants` defined automatically inherit `"visible"`
3. Each child resolves its own `visible` variant from its local variants definition
4. No need to pass `animate` props to children!
## Stagger animations
You can create staggered animations by using the `delay` in individual item transitions:
```svelte
{#each items as item, i}
{item}
{/each}
```
## Complex example: Notifications Stack
Here's a real-world example showing how variants enable complex orchestration. The parent controls the animation state, and all children respond accordingly.
**Click the stack to see variants in action:**
> Live example: [/examples/notifications-stack](https://motion.svelte.page/examples/notifications-stack)
### Breaking down the code
The example uses three different variant definitions working together:
```svelte
Notifications
{#each notifications as notification, i}
isOpen = !isOpen}
>
{notification}
{/each}
```
**Key points:**
- Parent sets `animate={isOpen ? 'open' : 'closed'}`
- Children with `variants` automatically inherit this state
- Each child resolves its own variant definition
- No need to pass props to children!
See the [full source code](/examples/notifications-stack) for the complete implementation.
## Type safety
Variants are fully typed in TypeScript. The `Variants` type ensures your animation definitions are valid:
```typescript
import type { Variants } from '@humanspeak/svelte-motion'
const variants: Variants = {
visible: {
opacity: 1,
x: 0
},
hidden: {
opacity: 0,
x: -100
}
}
```
## Best practices
### 1. Use semantic names
Choose variant names that describe the state, not the animation:
```svelte
// ✅ Good - describes state
const variants = {
visible: { opacity: 1 },
hidden: { opacity: 0 }
}
// ❌ Avoid - describes animation
const variants = {
fadeIn: { opacity: 1 },
fadeOut: { opacity: 0 }
}
```
### 2. Keep variants focused
Each variant should represent a complete state:
```svelte
const buttonVariants: Variants = {
idle: { scale: 1, backgroundColor: 'gray' },
loading: { scale: 1.05, backgroundColor: 'royalblue' },
success: { scale: 1, backgroundColor: '#22c55e' },
error: { scale: 0.95, backgroundColor: '#ef4444' }
}
```
### 3. Combine with Svelte state
Variants work perfectly with Svelte's reactive state management:
```svelte
```
## API Reference
### Variants type
```typescript
type Variants = Record
```
A `Variants` object is a dictionary mapping variant names (strings) to animation definitions.
### Using variants
Variants can be passed to any motion component via the `variants` prop:
- `variants`: Object containing named animation states
- `initial`: Initial variant name (string or `string[]`)
- `animate`: Target variant name (string or `string[]`)
- `exit`: Exit variant name (string or `string[]`)
- `whileHover` / `whileTap` / `whileFocus` / `whileDrag` / `whileInView`: variant name (string or `string[]`)
```svelte
```
### Variant keys on gesture props
Pass a variant name to any `whileX` prop to reuse a named state across gestures — handy when the same animation target shows up in multiple places (a single `hover` variant can drive `whileHover` on every card in a list, for example).
```svelte
hover or tap
```
You can also pass an **array of variant keys** to combine multiple states. The keys merge left-to-right — later entries override earlier ones on key collisions.
```svelte
```
If a key is missing from `variants`, it's silently skipped — useful for conditional layering.
## Related
- [Motion Component](/docs) - Full API reference
- [Examples](/examples) - See variants in action