---
name: "up.animation"
area: "API"
kind: "JavaScript function"
parent: "up.motion module"
url: "https://unpoly.com/api/up.animation"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.motion module](https://unpoly.com/api/up.motion.md)</nav>

# up.animation(name, animation)

Defines a named animation.

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Callback contract](#callback-contract)
- [Parameters](#parameters)

</nav>

## Example {#example}

Here is the definition of the pre-defined `fade-in` animation:

```js
up.animation('fade-in', function(element, options) {
  element.style.opacity = 0
  return up.animate(element, { opacity: 1 }, options)
})
```

## Callback contract {#callback-contract}

For animations that can be expressed through [CSS transitions](https://www.w3schools.com/css/css3_transitions.asp), we recommend that your definitions end by calling [`up.animate()`](https://unpoly.com/api/up.animate.md) with an object argument, passing along your `options` and returning the result.

If you choose to _not_ use [`up.animate()`](https://unpoly.com/api/up.animate.md) and roll your own animation code instead, your code must honor the following contract:

1. It must honor the options `{ duration, easing }`, if given.
2. It must _not_ remove any of the given elements from the DOM.
3. It returns a promise that is fulfilled when the animation has ended.
4. If during the animation an event [`up:motion:finish`](https://unpoly.com/api/up:motion:finish.md) is emitted on the given element, the animation instantly jumps to the last frame and resolves the returned promise.

Calling [`up.animate()`](https://unpoly.com/api/up.animate.md) with an object argument will take care of all these points.

---

## Parameters {#parameters}

### name {#name}

(required)

The name of the new animation.

Type: string

### animation {#animation}

(required)

The callback function that executes the animation.

Type: Function(element, options): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)