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

# up.transition(name, transition)

Defines a named transition that [morphs](https://unpoly.com/api/up.morph.md) from one element to another.

<nav aria-label="Contents">

#### Contents

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

</nav>

## Example {#example}

Here is the definition of the pre-defined `cross-fade` transition:

```js
up.transition('cross-fade', function(oldElement, newElement, options) {
  return Promise.all([
    up.animate(oldElement, 'fade-out', options),
    up.animate(newElement, 'fade-in', 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 logic 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 transition has ended.
4. If during the transition an event [`up:motion:finish`](https://unpoly.com/api/up:motion:finish.md) is emitted on either element, the transition 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 transition.

Type: string

### transition {#transition}

(required)

The callback function that executes the transition.

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