NOTE: This version of the documentation tracks unstable development happening on A-Frame’s
masterbranch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 0.9.0 version
The animation component lets us animate and tween values including:
- Component values (e.g.,
- Component property values (e.g.,
We can also tween values directly for better performance versus going through
.setAttribute, such as by animating values:
- On the
- Directly within a component (e.g.,
For example, translating a box:
<a-box position="0 1.6 0" animation="property: position; to: 5 1.6 0; dur: 1500; easing: linear"></a-box>
Or orbiting a sphere in a 5-meter radius:
<a-entity rotation="0 0 0" animation="property: rotation; to: 0 360 0; loop: true; dur: 10000">
Read more below for additional options and discovering how to properly animate different types of values.
|property||Property to animate. Can be a component name, a dot-delimited property of a component (e.g.,
|isRawProperty||Flag to animate an arbitrary object property outside of A-Frame components for better performance. If set to true, for example, we can set
|from||Initial value at start of animation. If not specified, the current property value of the entity will be used (will be sampled on each animation start). It is best to specify a
|to||Target value at end of animation.||null|
|type||Right now only supports
|delay||How long (milliseconds) to wait before starting.||0|
|dir||Which dir to go from
|dur||How long (milliseconds) each cycle of the animation is.||1000|
|easing||Easing function of animation. To ease in, ease out, ease in and out.||easeInQuad||See easings|
|elasticity||How much to bounce (higher is stronger).||400|
|loop||How many times the animation should repeat. If the value is
|round||Whether to round values.||false|
|startEvents||Comma-separated list of events to listen to trigger a restart and play. Animation will not autoplay if specified.
|pauseEvents||Comma-separated list of events to listen to trigger pause. Can be resumed with
|resumeEvents||Comma-separated list of events to listen to trigger resume after pausing.||null|
|autoplay||Whether or not the animation should
|enabled||If disabled, animation will stop and startEvents will not trigger animation start.||true|
The component’s base name is
animation. We can attach multiple animations to
one entity by name-spacing the component with double underscores (
<a-entity animation="property: rotation"
Easings define the accelerations and speed throughout the cycle of the animation.
|animationbegin||Animation began. Event detail contains
|animationcomplete||Animation completed. Event detail contains
||Animation completed if animation has an ID (e.g.,
|config||Config passed to anime.js.|
We can use the
startEvents property to animate upon events:
<a-entity id="mouseCursor" cursor="rayOrigin: mouse"></a-entity>
We’ll go over different cases of animating different types of values.
We can animate a single-property component value (e.g.,
we’ll go over booleans in a bit) or animate a property of a multi-property
component using a dot
. as a separator (e.g.,
If the property is a
vec3, that is also supported (e.g.,
someComponent.vec3Value; to: 5 5 5).
However, animating component values this way is not the most optimal way as it
.setAttribute on each frame of the animation. For an animation
here or there, it won’t be a big deal, but we can save time and memory by
animating values directly.
A special note to try not to animate values of the
geometry component as that
will recreate the geometry on each tick. Rather animate
scale if we want to
animate the size.
We can “animate” boolean values where the
to value will be applied at the end
of the animation. Like
property: visible; from: false; to: true; dur: 1.
The animation component supports animating values directly through
For example, we can animate values on
object3D.position.z; to: 5 which will tween the entity’s
value directly without calling
.setAttribute; it’s the most direct way and
lets us animate a single axis at a time. Note, for
Or we can animate values by reaching into
components. For example, rather than
property: material.opacity which would call
.setAttribute on each
frame, we can animate the opacity value directly with
components.material.material.opacity. We use a dot-delimited path to walk the
object tree to find the value we want to animate, and the animation process
under the hood reduces down to changing a number.
We can animate three.js color values directly, but we’ll need to specify
color. So rather than animating
property: material.color, we can do
property: components.material.material.color; type: color.
A note on color values, we can specify color values using hex, color names,
hsl, or rgb (e.g.,
from: red; to: #FFCCAA or
from: rgb(100, 100, 100); to:
hsl(213, 100%, 70%))..
anime is a popular and powerful animation engine. The component prefers to do
just basic tweening and touches the surface of what anime can do (e.g.,
timelines, motion paths, progress, seeking). If we need more animation
features, create a separate component that invokes anime.js directly. anime is