---
name: "up.Preview.prototype.insert"
area: "API"
kind: "Instance method"
parent: "up.Preview class"
url: "https://unpoly.com/api/up.Preview.prototype.insert"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.Preview class](https://unpoly.com/api/up.Preview.md)</nav>

# up.Preview.prototype.insert([reference], [position], newElement)

Temporarily inserts an element.

The element will be removed when the preview [ends](https://unpoly.com/learn/previews.md#ending).

<nav aria-label="Contents">

#### Contents

- [Providing the new element](#providing-the-new-element)
- [Cloning templates](#templates)
- [Controlling the insert position](#controlling-the-insert-position)
- [Compilation](#compilation)
- [Moving existing elements](#moving-existing-elements)
- [Parameters](#parameters)

</nav>

## Providing the new element {#providing-the-new-element}

The new element is passed as the last argument to the `insert()` method.

For example, this preview will insert a `.spinner` element as the last child of the targeted fragment:

```js
up.preview('spinner', function(preview) {
  let spinnerElement = up.element.createFromHTML('<span class="spinner">Please wait...</span>')
  preview.insert(spinnerElement)
})
```

You may also pass a string of HTML:

```js
up.preview('spinner', function(preview) {
  preview.insert('<span class="spinner">Please wait...</span>')
})
```

## Cloning templates {#templates}

If the given element is a [template](https://unpoly.com/learn/templates.md), it will be cloned before insertion.

Let's say we have a template for the spinner element:

```html
<template id="spinner-template">
  <span class="spinner">
    Please wait ...
  </span>
</template>
```

We can pass a selector for the template to clone:

```js
up.preview('spinner', function(preview) {
  preview.insert('#spinner-template')
})
```

Any [template variables](https://unpoly.com/learn/templates.md#dynamic) can be appended after the selector as [relaxed JSON](https://unpoly.com/api/relaxed-json.md):

```js
up.preview('spinner', function(preview) {
  preview.insert('#spinner-template { message: "One moment..." }')
})
```

For more control you may clone the template manually using [`up.template.clone()`](https://unpoly.com/api/up.template.clone.md):

```js
up.preview('spinner', function(preview) {
  let [spinnerElement] = up.template.clone('#spinner-template', { message: "One moment..." })
  spinnerElement.classList.add('big')
  preview.insert(spinnerElement)
})
```

## Controlling the insert position {#controlling-the-insert-position}

You can control where the new element is inserted by providing a _reference element_ and an _adjacent position_ relative to the reference argument.

For example, this preview will create a `.spinner` element as the _first_ child of the `<body>`:

```js
up.preview('spinner', function(preview) {
  preview.insert(document.body, 'afterbegin', '<span class="spinner">Please wait...</span>')
})
```

The following insert positions are supported:

| Value | Insert position |
| --- | --- |
| `"beforebegin"` | Insert before `reference`, as a new sibling. |
| `"afterbegin"` | Prepend to `reference`, before its first child. |
| `"beforeend"` | Append to `reference`, after its last child. |
| `"afterend"` | Insert after `reference`, as a new sibling. |

If the reference element is omitted, the new element will be inserted relative to the [targeted fragment](https://unpoly.com/api/up.Preview.prototype.fragment.md).

If the adjacent position is omitted, the new element will become the new last child of the reference element (`'beforeend'`).

## Compilation {#compilation}

When this function inserts a new element, it is [compiled](https://unpoly.com/learn/enhancing-elements.md).
When the preview [ends](https://unpoly.com/learn/previews.md#ending), the element is [destroyed](https://unpoly.com/learn/enhancing-elements.md#destructor).

## Moving existing elements {#moving-existing-elements}

When the last argument is an attached element, it is moved to the indicated position relative to the reference element. When the preview ends, the element is returned to its initial position.

Moved elements are neither [compiled nor destroyed](#compilation) by this function.

---

## Parameters {#parameters}

### [reference=this.fragment] {#reference}

(optional)

The reference element relative to which the new element will be inserted.

You may pass an [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) or a CSS selector.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | string

### [position='beforeend'] {#position}

(optional)

The insert position relative to the `reference` element.

Type: string

### newElement {#newElement}

(required)

The element to insert.

You may pass an [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element), a CSS selector or a snippet of HTML.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | string