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

# [up-keep]

Elements with an `[up-keep]` attribute will be kept when rendering.

<nav aria-label="Guides">

- [Learn: Keeping elements](https://unpoly.com/learn/keeping-elements.md)

</nav>

<nav aria-label="Contents">

#### Contents

- [Basic example](#basic-example)
- [Limitations](#limitations)
- [Modifying attributes](#attributes)

</nav>

## Basic example {#basic-example}

A common use case is to keep the playback state of media elements:

```html
<article>
  <p>Content</p>
  <audio id="player" up-keep src="song.mp3"></audio>
</article>
```

When [targeting](https://unpoly.com/learn/targeting-fragments.md) the `<article>` fragment, the `<audio>` element and its playback state will be the same before and after the update. All other elements (like the `<p>`) will be updated with new content.

See [Keeping elements](https://unpoly.com/learn/keeping-elements.md) for elaborate examples.

## Limitations {#limitations}

- The `[up-keep]` attribute is only supported for elements within the `<body>`.
- If an `<audio up-keep>` or `<video up-keep>` element is a _direct_ child of the `<body>`, it will lose its playback state during a fragment update. To keep its playback state in all browsers, insert a container element between the `<body>` and the media element.

---

## Modifying attributes {#attributes}

### [up-keep='true'] {#up-keep}

(optional)

How long to keep the element.

When set to `'true'` (the default), the element is kept as long as its [derived target](https://unpoly.com/learn/target-derivation.md) can be correlated in both the old and new content.

When set to `'same-html'`, the element is kept as long as its outer HTML does not change between versions. See [Keeping an element until its HTML changes](https://unpoly.com/learn/keeping-elements.md#same-html).

When set to `'same-data'`, the element is kept as long as its [data](https://unpoly.com/learn/data.md) does not change between versions. See [Keeping an element until its data changes](https://unpoly.com/learn/keeping-elements.md#same-data).

When set to `'false'` the element is never kept. A new element with `[up-keep="false"]` will always replace an existing element, even if that existing element has `[up-keep="true"]`. See [Forcing an update](https://unpoly.com/learn/keeping-elements.md#forcing-updates).

### [up-on-keep] {#up-on-keep}

(optional)

Code to run before an existing element is kept during a page update.

Calling `event.preventDefault()` will prevent the element from being kept. It will then be swapped with `newFragment`.

The code may use the variables `event` (of type [`up:fragment:keep`](https://unpoly.com/api/up:fragment:keep.md)), `this` (the old fragment), `newFragment` and `newData`.