Getting Started
Installation
Link to InstallationUsing 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">
The Basics
Link to The BasicsAnimXYZ 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>
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
Link to How it WorksAnimXYZ 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
Link to Practical ExamplesMoving 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
Composing Animations
Contexts
Link to ContextsThe 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
Link to UtilitiesAnimXYZ 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
Link to VariablesYou 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
Link to DefaultsAll 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 |
Triggering Animations
Active Classes
Link to Active ClassesAnimXYZ 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
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
Link to NestingWhen 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
Animations
Fade
Link to FadeFade 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
Link to TransformTranslate, 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.
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
Link to PerspectiveTo 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
Link to OriginIf 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
Link to TimingTiming 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
Link to StaggerStaggering 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.
If you are using the provided Vue/React XyzTransitionGroup
components, AnimXYZ will automatically add the --xyz-index
and --xyz-index-rev
for 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
Link to IterateThe 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.
Vue Integration
Installation
Link to InstallationUsing a package manager
VueAnimXYZ can be installed using your favorite package manager:
# with npm
npm install @animxyz/vue
# with yarn
yarn add @animxyz/vue
# 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.
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(...)
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:
<script src="https://cdn.jsdelivr.net/npm/@animxyz/vue@0.3.0/dist/VueAnimXyz.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@animxyz/vue3@0.3.0/dist/VueAnimXyz.js"></script>
XyzTransition
Link to XyzTransitionThe <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
Link to XyzTransitionGroupThe <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
Link to v-xyzThe 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 Integration
React
Link to ReactThe react component library is currently in progress and will be released soon!
for this section.