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

# up.hello(element, [options])

Manually compiles a page fragment that has been inserted into the DOM by external code.

All registered [compilers](https://unpoly.com/learn/enhancing-elements.md) and [macros](https://unpoly.com/api/up.macro.md) will be called with matches in the given `element`.

The [`up:fragment:inserted`](https://unpoly.com/api/up:fragment:inserted.md) event is emitted on the compiled element.

<nav aria-label="Guides">

- [Learn: Enhancing elements with JavaScript](https://unpoly.com/learn/enhancing-elements.md#hello)

</nav>

<nav aria-label="Contents">

#### Contents

- [Unpoly automatically calls `up.hello()`](#unpoly-automatically-calls-uphello)
- [Recompiling elements](#recompiling-elements)
- [Detecting compiler errors](#detecting-compiler-errors)
- [Awaiting asynchronous compilation](#async)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Unpoly automatically calls `up.hello()` {#unpoly-automatically-calls-uphello}

When the page is manipulated using Unpoly functions or `[up-*]` attributes, Unpoly will automatically call `up.hello()` on new fragments:

```js
let link = document.querySelector('a[href]')
let { fragment } = await up.follow(link)
// The fragment is already compiled. No need to call up.hello().
```

You only need to use `up.hello()` after creating DOM elements without Unpoly's involvement, for example:

- Creating elements with `document.createElement()`
- Setting the `innerHTML` property on an existing element
- Parsing HTML into elements using browser APIs like `DOMParser()`
- Elements created by other libraries

In this case, compilers will _not_ run automatically and some of Unpoly's own `[up-*]` attributes will not be active. We can address this by manually calling `up.hello()` on new elements:

```js
let element = document.createElement('div')
element.innerHTML = '<a href="/path" up-follow>click me</a>'
// The element is not compiled yet. We must compile it manually:
up.hello(element)
```

## Recompiling elements {#recompiling-elements}

It is safe to call `up.hello()` multiple times with the same elements. In particular, every compiler function is guaranteed to run only once for each matching element.

If a new compiler is registered after initial compilation, that new compiler is [run automatically on current elements](https://unpoly.com/api/up.compiler.md#late).

## Detecting compiler errors {#detecting-compiler-errors}

If a compiler function throws an error, `up.hello()` will still finish the compilation and _not_ throw an error.

Instead, compiler errors will print to the [error console](https://developer.mozilla.org/en-US/docs/Web/API/console/error) and emit an [`error` event on `window`](https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event):

```js
window.addEventListener('error', function(event) {
  alert("Got an error " + event.error.name)
})

up.hello(element)
```

See [errors in user code](https://unpoly.com/learn/render-lifecycle.md#errors-in-user-code) for details.

## Awaiting asynchronous compilation {#async}

Unpoly supports [`async` compiler functions](https://unpoly.com/api/up.compiler.md#async):

```js
up.compiler('textarea.wysiwyg', async function(textarea) {
  let editor = await import('wysiwyg-editor')
  await editor.init(textarea)
  return () => editor.destroy(textarea)
})
```

The `up.hello()` function returns a promise that fulfills when all synchronous and asynchronous compilers have terminated:

```js
let textarea = up.element.createFromHTML('<textarea class="wysiwyg"></textarea>')
document.body.append(textarea)
await up.hello(textarea)
// WYSIWYG editor is now initialized
```

The fulfillment value is the same element that was passed as an argument:

```js
let textarea = up.element.affix(document.body, 'textarea.wysiwyg')
let compiled = await up.hello(textarea) // compiled === textarea
```

---

## Parameters {#parameters}

### element {#element}

(required)

The root element of the new page fragment.

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

### [options.data] (Experimental) {#options.data}

(optional)

Overrides properties from the new fragment's [`[up-data]`](https://unpoly.com/api/up-data.md) with the given [data object](https://unpoly.com/learn/data.md).

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

### [options.meta={}] (Experimental) {#options.meta}

(optional)

An object containing [information about this compiler pass](https://unpoly.com/learn/enhancing-elements.md#meta).

This typically contains `{ layer, revalidating }` properties.

It will be passed as a third [compiler](https://unpoly.com/learn/enhancing-elements.md) argument.

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

---

## Return value {#return-value}

A promise that fulfills when the element has finished compilation.

The fulfillment value is the `element` argument.

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