Installation

Woah... I know kung fu.

Using a package manager

AnimXYZ can be installed using your favorite package manager:

# with npm
npm install @animxyz/core

# with yarn
yarn add @animxyz/core

After installation, you will need to import AnimXYZ into your project.

Import into a Webpack project

If your Webpack project uses css-loader you can import the CSS by putting this snippet anywhere in your javascript code:

import '@animxyz/core'

Import into a SASS project

AnimXYZ is built in SASS and provides useful functions and mixins for customization. Import it anywhere in your SASS code:

// Import the functions/mixins
@import '@animxyz/core';

// Add all the core/utilities selectors
@include xyz-all;
// --- Or for more control and granularity ---
@include xyz-core;
@include xyz-utilities;

Using jsDelivr

To add AnimXYZ using a CDN put this link in the <head> of your index.html file:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@animxyz/core@0.3.0/dist/animxyz.min.css">

Vue

React

If you are using AnimXYZ in a Vue or React project we strongly recommend you also use our AnimXYZ components. To add those, follow the installation instructions in the relevant sections Vue and React.

The Basics

Examples

Time to learn your XYZ's.

AnimXYZ is an easy way to animate elements without all the boilerplate of writing keyframes. Just describe the animation with some attributes and variables, and tell the element whether it's animating in or out of the scene with a class.

For example here is how you make an element fade and shrink in from above:

<div class="xyz-in" xyz="fade up big">I will animate in!</div>

Changing the class to xyz-out reverses the direction of the animation:

<div class="xyz-out" xyz="fade up big">I will animate out!</div>

See it in action here

For simple animations, that's all you need, but AnimXYZ can do so much more! Keep on reading to see how you can customize and control AnimXYZ to create exactly the animations you want.

How it Works

Try to realize the truth… there is no div.

AnimXYZ uses CSS Variables under the hood to modify a core @keyframes animation. These xyz-variables determine the timing and the values of the element properties that will be animated such as opacity and transform. Each value will be animated to and from depending on whether the element is animating in or out.

Instead of having to write keyframes for every unique animation, you just tell the one animation what to do. Here is a simplified version of whats going on behind the scenes:

@keyframes xyz-keyframes {
  from {
    opacity: var(--xyz-opacity);
    transform: translate3d(
      var(--xyz-translate-x),
      var(--xyz-translate-y),
      var(--xyz-translate-z)
    );
  }
}

.xyz-in, .xyz-out {
  animation-name: xyz-keyframes;
  animation-duration: var(--xyz-duration);
}

.xyz-in {
  animation-direction: forwards;
}

.xyz-out {
  animation-direction: reverse;
}

Practical Examples

Examples

Is this real life?

Moving squares around is all well and good, but what do you use AnimXYZ for in the real world? Here are just a few examples of common ways you can use AnimXYZ to make your UI more lively and interesting.

Emphasize what someone should look at first, or give a feature list some life. Animating the initial appearance of elements on a page is easy. Check out how the xyz-nested class and delay and stagger utilities allow you to orchestrate sequential animations. Page Example

Media galleries can clearly show which items are being added or removed with a small animation in and out. appear specific utilities let you differentiate the initial animation from subsequent changes. Grid Example

Usually modals just fade in at the same time as the overlay, but by adding an in-delay to the modal and an out-delay to the overlay you can make the animation feel much more alive. Modal Example

Tabs imply content hidden off-screen to the left or right of the current tab. With a dynamic xyz property determined by the tab's index you can make tab content slide in and out from the direction you expect it to. Tabs Example

A chat component feels much more natural if each text moves in from the side of its respective owner. Chat Example

Contexts

Examples

The div doesn't fall far from the tree.

The xyz attribute creates an animation context where any AnimXYZ animations that take place within will use the animation variables it sets. This can be very useful when applying the same animation to lists or groups of elements without having to add them to each element. Basic Example

To have a child element animate differently than it's parent context, add an xyz attribute to the child to override it. This new XYZ context resets all utilities and variables. Override Example

If you want to only override some of the parent context, add inherit along with the new xyz values. Inherit Example

Utilities

Examples

With our powers combined...

AnimXYZ has the unique ability to mix and match animation utilities, letting you compose an enormous variety of animations without any extra code. For example xyz="up left small" will make an element move to and from the upper left while expanding in and contracting out. Spin an element while collapsing it to a sliver, expand an element while it swings in from its corner, the possibilities are endless! Here are just a few of the many combinations you can do:

😐 fade up
🙂 fade flip-up flip-left
😀 fade down-5 rotate-right-50% stagger
😃 fade front-3 flip-down-50% duration-10 stagger-5
🤪 fade up-100% flip-down flip-right-50% rotate-left-100% origin-bottom duration-10 stagger

Certain utilities won't work with other utilities if they both change the same property. For example xyz="up down" will not work because both up and down change the --xyz-translate-y variable. Check out the active classes section to learn how to use different utilities when animating in or out.

You can also combine a utility with an animation variable for more custom animations. For example xyz="fade tall" style="--xyz-rotate-z: 33deg" will make an element fade and change height by their default amounts, and rotate in and out by 33 degrees. Scroll down to learn more about AnimXYZ variables.

Variables

Examples

--xyz-gigawatts: 1.21

You can set the CSS variables that drive the core AnimXYZ animations to customize and create your own. For example set the value of --xyz-translate-x to -42% to animate an element to and from the left by 42% of it's width.

You have control over everything you need to animate an element, even transform origin, duration, or staggering. This lets you create unique animations beyond what the utilities can provide:

🐞 vw units
🎈 Yoink!
📺 Click.
🌀 It's gone spiral!
💫 Engage.

Keep in mind that CSS variables are inherited by child elements, so any element with an active class will animate with its parent's CSS variables unless specifically overridden or using an xyz attribute which overrides all AnimXYZ variables.

	Overall	In	Out	Appear
Keyframes	--xyz-keyframes	--xyz-in-keyframes	--xyz-out-keyframes	--xyz-appear-keyframes
Ease	--xyz-ease	--xyz-in-ease	--xyz-out-ease	--xyz-appear-ease
Duration	--xyz-duration	--xyz-in-duration	--xyz-out-duration	--xyz-appear-duration
Delay	--xyz-delay	--xyz-in-delay	--xyz-out-delay	--xyz-appear-delay
Stagger	--xyz-stagger	--xyz-in-stagger	--xyz-out-stagger	--xyz-appear-stagger
Stagger Reverse	--xyz-stagger-rev	--xyz-in-stagger-rev	--xyz-out-stagger-rev	--xyz-appear-stagger-rev
Iterate	--xyz-iterate	--xyz-in-iterate	--xyz-out-iterate	--xyz-appear-iterate
Origin	--xyz-origin	--xyz-in-origin	--xyz-out-origin	--xyz-appear-origin
Opacity	--xyz-opacity	--xyz-in-opacity	--xyz-out-opacity	--xyz-appear-opacity
Transform	--xyz-transform	--xyz-in-transform	--xyz-out-transform	--xyz-appear-transform
Perspective	--xyz-perspective	--xyz-in-perspective	--xyz-out-perspective	--xyz-appear-perspective
Translate X	--xyz-translate-x	--xyz-in-translate-x	--xyz-out-translate-x	--xyz-appear-translate-x
Translate Y	--xyz-translate-y	--xyz-in-translate-y	--xyz-out-translate-y	--xyz-appear-translate-y
Translate Z	--xyz-translate-z	--xyz-in-translate-z	--xyz-out-translate-z	--xyz-appear-translate-z
Rotate X	--xyz-rotate-x	--xyz-in-rotate-x	--xyz-out-rotate-x	--xyz-appear-rotate-x
Rotate Y	--xyz-rotate-y	--xyz-in-rotate-y	--xyz-out-rotate-y	--xyz-appear-rotate-y
Rotate Z	--xyz-rotate-z	--xyz-in-rotate-z	--xyz-out-rotate-z	--xyz-appear-rotate-z
Scale X	--xyz-scale-x	--xyz-in-scale-x	--xyz-out-scale-x	--xyz-appear-scale-x
Scale Y	--xyz-scale-y	--xyz-in-scale-y	--xyz-out-scale-y	--xyz-appear-scale-y
Scale Z	--xyz-scale-z	--xyz-in-scale-z	--xyz-out-scale-z	--xyz-appear-scale-z
Skew X	--xyz-skew-x	--xyz-in-skew-x	--xyz-out-skew-x	--xyz-appear-skew-x
Skew Y	--xyz-skew-y	--xyz-in-skew-y	--xyz-out-skew-y	--xyz-appear-skew-y

Defaults

Examples

TBD

All AnimXYZ variables are provided with default values that determine what animations basic xyz utilities like fade or left set when not provided a utility scale such as left-3. Some default values are shared across related utilities, for example --xyz-translate-default is the default value for X, Y, and Z translations.

You can change these default values by setting their respective variables. To change them across your entire site set them at the :root.

You can also change default values on an element, but keep in mind they will apply to all child elements as well.

	Variable	Value
Ease	--xyz-ease-default	ease
Duration	--xyz-duration-default	0.5s
Delay	--xyz-delay-default	0s
Stagger	--xyz-stagger-default	0.3s
Iterate	--xyz-iterate-default	1
Origin	--xyz-origin-default	center
Opacity	--xyz-opacity-default	0
Perspective	--xyz-perspective-default	0px
Translate	--xyz-translate-default	25%
Translate Z	--xyz-translate-z-default	300px
Rotate	--xyz-rotate-default	0.25turn
Scale	--xyz-scale-default	0.5
Skew	--xyz-skew-default	30deg

Active Classes

Examples

Element goes in, element goes out, you can't explain that.

AnimXYZ animates elements in and out when activated by their respective classes: .xyz-in animates elements from the values set by XYZ utilities and variables, while .xyz-out animates elements to those values.

For example an element with .xyz-in and xyz="fade" will fade from 0 to its natural opacity, while .xyz-out will fade it from its natural opacity to 0.

By default AnimXYZ utilities and variables apply to both the in and out classes, but you can set specific animations for each direction. Utilities and variables have in and out variants which apply only to the corresponding direction. For example an element with xyz="in-left in-rotate-left out-right out-rotate-right" will slide/rotate in from the left and slide/rotate out to the right. See example

Direction-specific utilities and variables take precedence over the basic variants. For example an element with xyz="big-100% out-big-25%" will have a more pronounced scale effect in the in direction than in the out direction. See example

You can combine direction-specific utilities and variables to achieve some very cool effects. See example

Vue

React

The Vue and React libraries also expose an .xyz-appear class and a full set of appear utilities and variables that you can use to define a specific animation for when an element initially appears on the page.

Nesting

Examples

It's <turtles> all the way down.

When dynamically applying AnimXYZ active classes with a JavaScript framework or the AnimXYZ Vue and React components, it's common to want child elements to animate in sync with the element you are controlling without having to apply the same class logic to each child.

Elements with an .xyz-nested class trigger their animations when a parent element has an XYZ active class such as .xyz-in or .xyz-out. See example

Each .xyz-nested element can have its own unique XYZ properties. See example

If a parent element has an xyz="stagger", then the .xyz-nested elements will animate once the parent animation begins. See example

Fade

Examples

Beam me up Scotty!

Fade is one of the most commonly used animations and combines well other animations.

Fade utilities and variables define the starting (.xyz-in) or ending (.xyz-out) opacity of the animating element. Apply xyz="fade" to an element to use the default value, or use one of the utilities like xyz="fade-50%" to fade from and to a predefined value.

You can also override --xyz-opacity with a custom value in your CSS or with inline styling for more granular control.

Variables

	Overall	In	Out	Appear
Opacity	--xyz-opacity	--xyz-in-opacity	--xyz-out-opacity	--xyz-appear-opacity

See the variables section to learn more.

Defaults

	Variable	Value
Opacity	--xyz-opacity-default	0

See the defaults section to learn more.

Transform

Examples

Elements, roll out!

Translate, rotate, and scale your elements along any axis. We call it AnimXYZ for a reason!

Transform utilities and variables define the starting (.xyz-in) or ending (.xyz-out) transform of the animating element. For example xyz="up" will apply a translateY() to an element, translating it from above its normal position when animating in and to that same position when animating out.

You can also override any of the provided transform variables with a custom value in your CSS or with inline styling for more granular control.

If an element already has a transform applied to it that you want to maintain during the animation, pass it as custom values to the relevant CSS variables. For example if an element has transform: translateX(-50%) applied to it, and you want to use xyz="up", you can set its --xyz-translate-x variable to -50% and it will maintain that translate through the entire up animation.

Warning

There is a bug in Safari (Mac and iOS) which prevents certain elements from rendering during an animation set to scale(0), scaleX(0), or scaleY(0). All elements with border, border-radius, or box-shadow are affected.

If you encounter this issue, an easy fix is setting the scale variable to a low value, for example: --xyz-scale-x: 0.001; --xyz-scale-y: 0.001;.

Variables

	Overall	In	Out	Appear
Transform	--xyz-transform	--xyz-in-transform	--xyz-out-transform	--xyz-appear-transform
Translate X	--xyz-translate-x	--xyz-in-translate-x	--xyz-out-translate-x	--xyz-appear-translate-x
Translate Y	--xyz-translate-y	--xyz-in-translate-y	--xyz-out-translate-y	--xyz-appear-translate-y
Translate Z	--xyz-translate-z	--xyz-in-translate-z	--xyz-out-translate-z	--xyz-appear-translate-z
Rotate X	--xyz-rotate-x	--xyz-in-rotate-x	--xyz-out-rotate-x	--xyz-appear-rotate-x
Rotate Y	--xyz-rotate-y	--xyz-in-rotate-y	--xyz-out-rotate-y	--xyz-appear-rotate-y
Rotate Z	--xyz-rotate-z	--xyz-in-rotate-z	--xyz-out-rotate-z	--xyz-appear-rotate-z
Scale X	--xyz-scale-x	--xyz-in-scale-x	--xyz-out-scale-x	--xyz-appear-scale-x
Scale Y	--xyz-scale-y	--xyz-in-scale-y	--xyz-out-scale-y	--xyz-appear-scale-y
Scale Z	--xyz-scale-z	--xyz-in-scale-z	--xyz-out-scale-z	--xyz-appear-scale-z
Skew X	--xyz-skew-x	--xyz-in-skew-x	--xyz-out-skew-x	--xyz-appear-skew-x
Skew Y	--xyz-skew-y	--xyz-in-skew-y	--xyz-out-skew-y	--xyz-appear-skew-y

See the variables section to learn more.

Defaults

	Variable	Value
Translate	--xyz-translate-default	25%
Translate Z	--xyz-translate-z-default	300px
Rotate	--xyz-rotate-default	0.25turn
Scale	--xyz-scale-default	0.5
Skew	--xyz-skew-default	30deg

See the defaults section to learn more.

Perspective

Examples

From a certain point of view.

To take full advantage of CSS 3D animations, your animating elements should have a perspective applied to them. This can be done by adding a perspective property on a parent of the animating elements, for example by adding perspective: 500px. However if you want to set a perspective on each element only while it is animating you can use a perspective XYZ utility.

Smaller perspective values will result in a more pronounced effect.

Variables

	Overall	In	Out	Appear
Perspective	--xyz-perspective	--xyz-in-perspective	--xyz-out-perspective	--xyz-appear-perspective

See the variables section to learn more.

Defaults

	Variable	Value
Perspective	--xyz-perspective-default	0px

See the defaults section to learn more.

Origin

Examples

You spin my bottom-right round, baby.

If you want to animate an element like a swinging door, or have it expand from a particular corner, use an origin utility to apply a transform-origin during the animation. This should be used along with a rotate or scale animation.

For example setting xyz="small-100% origin-right" on an element will scale it to its right center edge.

If you want to place the transform-origin in a more precise location than the utilities provide, override --xyz-origin with a custom value in your CSS or with inline styling for more granular control. For example --xyz-origin: 50px 50px will set the origin to a point 50px down and to the right from the top left.

Variables

	Overall	In	Out	Appear
Origin	--xyz-origin	--xyz-in-origin	--xyz-out-origin	--xyz-appear-origin

See the variables section to learn more.

Defaults

	Variable	Value
Origin	--xyz-origin-default	center

See the defaults section to learn more.

Timing

Examples

How did it get so late so soon?

Timing utilities let you set the animation-duration, animation-delay, and animation-timing-function of an animation. AnimXYZ animations default to a duration of 0.5s, a delay of 0s, and a timing-function of ease.

Changing the timing of an animation can have a large impact on how it feels. For example xyz="ease-out-back" will add a slight overshoot at the end of an animation.

You can set your own custom duration, delay, and timing function using the --xyz-duration, --xyz-delay, and --xyz-ease variables respectively.

Variables

	Overall	In	Out	Appear
Ease	--xyz-ease	--xyz-in-ease	--xyz-out-ease	--xyz-appear-ease
Duration	--xyz-duration	--xyz-in-duration	--xyz-out-duration	--xyz-appear-duration
Delay	--xyz-delay	--xyz-in-delay	--xyz-out-delay	--xyz-appear-delay

See the variables section to learn more.

Defaults

	Variable	Value
Ease	--xyz-ease-default	ease
Duration	--xyz-duration-default	0.5s
Delay	--xyz-delay-default	0s

See the defaults section to learn more.

Stagger

Examples

For the nth time!

Staggering increases the animation-delay for each element in a list so that their animation is triggered one following the other, like dominoes.

AnimXYZ will apply this staggered delay to the first 20 elements (or last 20 if using stagger-rev) based on their nth-child index. Alternatively you can pass your own index to each element with the --xyz-index or --xyz-index-rev variables if you want more than 20 elements to stagger or want to change the staggering order in other ways.

You can also override the --xyz-stagger and --xyz-stagger-rev variables with a custom time value in your CSS or with inline styling for more granular control.

Vue

React

If you are using the provided Vue/React XyzTransitionGroup components, AnimXYZ will automatically add the --xyz-index and --xyz-index-revfor all elements in the group.

Since Vue and React add/remove elements when their enter/exit animations end, staggered elements that are not position: absolute may cause the group layout to change as each element enters or exits in order.

Variables

	Overall	In	Out	Appear
Stagger	--xyz-stagger	--xyz-in-stagger	--xyz-out-stagger	--xyz-appear-stagger
Stagger Reverse	--xyz-stagger-rev	--xyz-in-stagger-rev	--xyz-out-stagger-rev	--xyz-appear-stagger-rev

See the variables section to learn more.

Defaults

	Variable	Value
Stagger	--xyz-stagger-default	0.3s

See the defaults section to learn more.

Iterate

Examples

Two hops this time!

The iterate utilities and variables set the animation-iteration-count of an animation. This allows you to have the animation repeat a set number of times or indefinitely.

Variables

	Overall	In	Out	Appear
Iterate	--xyz-iterate	--xyz-in-iterate	--xyz-out-iterate	--xyz-appear-iterate

See the variables section to learn more.

Defaults

	Variable	Value
Iterate	--xyz-iterate-default	1

See the defaults section to learn more.

Installation

May the force be with Vue.

Using a package manager

VueAnimXYZ can be installed using your favorite package manager:

Vue 2.x

# with npm
npm install @animxyz/vue

# with yarn
yarn add @animxyz/vue

Vue 3.x

# with npm
npm install @animxyz/vue3

# with yarn
yarn add @animxyz/vue3

After installation, you will need to import VueAnimXYZ into your project and tell the Vue instance to use the plugin. This has to be done before you instantiate your Vue app.

Vue 2.x

import Vue from 'vue'
import VueAnimXYZ from '@animxyz/vue'
import '@animxyz/core' // Import css here if you haven't elsewhere

Vue.use(VueAnimXYZ)

// Instantiate your Vue instance after using plugins
// new Vue(...)

Vue 3.x

import { createApp } from 'vue'
import VueAnimXyz from '@animxyz/vue3'
import '@animxyz/core' // Import css here if you haven't elsewhere
import App from './App.vue' // Your entry component

const app = createApp(App)

app.use(VueAnimXyz)

// Mount your Vue instance after using plugins
// app.mount(...)

Using jsDelivr

To install VueAnimXYZ using a CDN put this script in the <head> of your index.html file:

Vue 2.x

<script src="https://cdn.jsdelivr.net/npm/@animxyz/vue@0.3.0/dist/VueAnimXyz.js"></script>

Vue 3.x

<script src="https://cdn.jsdelivr.net/npm/@animxyz/vue3@0.3.0/dist/VueAnimXyz.js"></script>

XyzTransition

Examples

The <XyzTransition> component is an extended version of the <Transition> Vue component used to animate single elements in and out of the page or to animate switching between elements. The component exposes the same props and events as the Vue component with some presets to work seamlessly with AnimXYZ and some quality of life improvements.

Unlike the complexity of the Vue component, with <XyzTransition> you only need to care about the appear, appear-visible, duration, and mode props.

<XyzTransition
  appear={ boolean }
  appear-visible={ boolean | IntersectionObserverOptions }
	duration={ number | 'auto' | { appear: number | 'auto', in: number | 'auto', out: number | 'auto' } }
	mode={ 'out-in' | 'in-out' }
>
	<child />
</XyzTransition>

Properties

appear

When set to true will animate elements in on initial render. You can set appear-specific behaviour using the appear-specific xyz utilities and variables. See active classes for more information.

You can learn more about using this property in the Vue docs.

appear-visible

You can use this property instead of appear to pause the appear animation until the element is visible within the viewport. This uses an IntersectionObserver behind the scenes which can be customized by passing the IntersectionObserver options to the property such as :appear-visible="{ threshold: 0.5, rootMargin: '50px' }".

duration

Sets the behavior of how long to apply the active class for the animation. By default the class will be applied only for the duration of the animation, however if you have nested animations you will want them to complete before removing the class. To do this we've added duration="auto" which conviently waits for all nested animations to finish before removing the class.

To apply the class for a specific amount of time you can use a number in milliseconds like :duration="2000".

You can also specify direction-specific behavior using an object describing the behavior for each direction such as :duration="{ appear: 'auto', in: 2000, out: 1000 }".

You can learn more about using this property in the Vue docs.

mode

Sets the sequencing of element switch transitions. By default the new element will transition in simultanously to the old element transitioning out. Setting mode="out-in" will transition the old element out first and setting mode="in-out" will transition the new element in first.

You can learn more about using this property in the Vue docs.

	Default	Syntax
appear	--	boolean
appear-visible	--	boolean \| IntersectionObserverOptions
duration	--	number \| 'auto' \| { in: number \| 'auto', out: number \| 'auto', appear: number \| 'auto' }
mode	--	'out-in' \| 'in-out'

XyzTransitionGroup

Examples

The <XyzTransitionGroup> component is an extended version of the <TransitionGroup> Vue component used to animate groups/lists of elements. The component exposes the same props and events as the Vue component with some presets to work seamlessly with AnimXYZ and some quality of life improvements.

Unlike the complexity of the Vue component, with <XyzTransitionGroup> you only need to care about the appear, appear-visible, duration, and tag props.

<XyzTransitionGroup
  appear={ boolean }
  appear-visible={ boolean | IntersectionObserverOptions }
	duration={ number | 'auto' | { appear: number | 'auto', in: number | 'auto', out: number | 'auto' } }
	tag={ string }
>
	<child />
	<child />
	<child />
	...
</XyzTransitionGroup>

Properties

appear

Same as the <XyzTransition> component.

appear-visible

Same as the <XyzTransition> component.

duration

Same as the <XyzTransition> component.

tag

Specifies the tag to use for the wrapper element. Defaults to 'span'.

	Default	Syntax
appear	--	boolean
appear-visible	--	boolean \| IntersectionObserverOptions
duration	--	number \| 'auto' \| { in: number \| 'auto', out: number \| 'auto', appear: number \| 'auto' }
tag	'div'	string

v-xyz

Examples

The v-xyz directive allows you to dynamically set the xyz attribute using a similar syntax to the Vue dynamic class and style bindings. For instance you can conditionally apply a transform on an element like so:

<div v-xyz="{ 'left-5': isTransformed }"></div>

Or set the utility level dynamically:

<div v-xyz="[`left-${utilityLevel}`]"></div>

To dynamically set XYZ variables simply use the existing dynamic :style binding:

<div :style="{ '--xyz-translate-x': translateAmount }"></div>

React

For every action, there is an equal and opposite React component.

The react component library is currently in progress and will be released soon!

Back to

There are no examples
for this section.

Getting Started

Using a package manager

Import into a Webpack project

Import into a SASS project

Using jsDelivr

Composing Animations

Triggering Animations

Animations

Variables

Defaults

Variables

Defaults

Variables

Defaults

Variables

Defaults

Variables

Defaults

Variables

Defaults

Variables

Defaults

Vue Integration

Using a package manager

Using jsDelivr

Properties

appear

appear-visible

duration

mode

Properties

appear

appear-visible

duration

tag

React Integration