Using A-Frame's Animation Component for Declarative Motion

What the animation component does

The animation component is built into A‑Frame and lets you change any numeric attribute over time — such as position, rotation, scale, or material properties like opacity — by declaring start‑end values, duration, easing, delay, and repeat directly in HTML.

Basic syntax

Attach the component to an entity and give it a unique name (the part after the double underscore). Inside the value you set property, to (or from), dur (milliseconds), easing, and optional dir, loop, or delay.

<a-entity id="box"
          geometry="primitive: box; width: 1; height: 1; depth: 1"
          material="color: red"
          animation__move="property: position; to: 5 0 0; dur: 2000; easing: ease-in-out; dir: alternate; loop: true">
</a-entity>

This example moves the red box back and forth along the X‑axis from its original position to (5,0,0) and then returns, repeating forever.

How it works

When the scene loads, the animation component reads the attributes, creates a tween that updates the targeted property each frame using the specified easing function, and respects dir (forward, reverse, or alternate) and loop count. No JavaScript is required unless you need to start or stop the animation programmatically.

Limits and common mistakes

Numeric‑only properties

The component can only tween values that are numbers or vectors of numbers. Attempting to animate a string‑based property like material.shader or a texture offset will have no effect; you need a custom component or the animation‑mixer for GLTF skeletal animations.

Name collisions

If you attach two animations with the same name (e.g., two animation__move) on the same entity, the later definition overwrites the earlier one. Use distinct names such as animation__moveX and animation__fade to run them simultaneously.

Performance considerations

Running many simultaneous animations on many entities can lower frame rate because each tick updates the DOM‑like scene graph. For large numbers of objects, consider updating properties yourself in a tick handler or using the animation‑mixer component which is optimized for skeletal animations.

Typical pitfalls

• Setting dur to 0 causes an instant jump rather than a smooth transition.
• Using non‑numeric values in to or from (e.g., to: "red") is ignored.
• Expecting CSS‑style keyframes; the component only supports a single start‑to‑end tween per animation instance.
• Forgetting to include the component at all — while it is built‑in, you must still add the animation__* attribute to an entity.