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

# up.morph(oldElement, newElement, transition, [options])

Performs an animated transition between two elements.

Transitions are implemented by performing two animations in parallel, causing `oldElement` to disappear and `newElement` to appear.

- `newElement` is [inserted before](https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore) `oldElement`
- `oldElement` is removed from the [document flow](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning) with `position: absolute`. It will be positioned over its original place in the flow that is now occupied by `newElement`.
- Both `oldElement` and `newElement` are animated in parallel
- `oldElement` is removed from the DOM

<nav aria-label="Contents">

#### Contents

- [Named transitions](#named-transitions)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Named transitions {#named-transitions}

Unpoly ships with a number of [predefined transitions](https://unpoly.com/learn/transitions.md#available-transitions).

You can define additional named transitions using [`up.transition()`](https://unpoly.com/api/up.transition.md).

---

## Parameters {#parameters}

### Elements {#parameters-elements}

#### oldElement {#oldElement}

(required)

The old element to transition away from.

It will be removed from the DOM when the transition finishes.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/) | string

#### newElement {#newElement}

(required)

The new element that will remain in the DOM once the transition finishes.

It should be detached before calling `up.morph()`.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/) | string

### Transition {#parameters-transition}

#### transition {#transition}

(required)

Can either be:

- The name of a [registered](https://unpoly.com/api/up.transition.md) transition
- A function performing the transition (same contract as a function passed to [`up.transition()`](https://unpoly.com/api/up.transition.md))

Type: Function(oldElement, newElement, options) | string

#### [options.duration=175] {#options.duration}

(optional)

The duration of the transition, in milliseconds.

Type: number

#### [options.easing='ease'] {#options.easing}

(optional)

The timing function that controls the transition's acceleration.

See [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) for a list of pre-defined timing functions.

Type: string

---

## Return value {#return-value}

A promise that fulfills when the transition ends.

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