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

# up.preview(name, callback)

Registers a named [preview](https://unpoly.com/learn/previews.md) function.

Preview functions are applied using the [`[up-preview]`](https://unpoly.com/api/up-preview.md) attribute or [`{ preview }`](https://unpoly.com/api/up.render.md#options.preview) option. See [Previews](https://unpoly.com/learn/previews.md) for an overview.

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Accepting parameters](#parameters)
- [Parameters](#parameters)

</nav>

## Example {#example}

This preview sets a temporary `[app-loading=true]` attribute on the targeted fragment:

```js
up.preview('loading-attr', function(preview) {
  preview.setAttrs({ 'app-loading': true })
})
```

The `preview` argument is an [`up.Preview`](https://unpoly.com/api/up.Preview.md) instance that offers many utilities to make temporary changes. For example, you can use it to insert or move elements, add classes or set attributes.

We can use the `loading-attr` preview in any link or form by setting an [`[up-preview]`](https://unpoly.com/api/up-preview.md) attribute:

```html
<a href="/edit" up-follow up-preview="loading-attr">Edit page</a>
```

## Accepting parameters {#parameters}

Preview functions can accept an options object as a second argument. This is useful to define multiple variations of a preview effect.

For example, the following preview accepts a `{ size }` option to show a spinner of varying size:

```js
up.preview('spinner', function(preview, { size = 50 }) {
  let spinner = up.element.createFromSelector('img', { src: 'spinner.gif', width: size })
  preview.insert(preview.fragment, spinner)
})
```

From HTML you can append the options to the [`[up-preview]`](https://unpoly.com/api/up-preview.md) argument, after the preview name:

```html
<a href="/edit" up-follow up-preview="spinner { size: 100 }">Edit page</a>
```

---

## Parameters {#parameters}

### name {#name}

(required)

The name of the preview.

Type: string

### callback {#callback}

(required)

The function that applies the temporary page mutation.

Any [preview parameters](#parameters) will be passed as a second argument.

Type: Function([up.Preview](https://unpoly.com/api/up.Preview.md), [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects))