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

# up.layer.config

Configures default attributes for new overlays.

All options for [`up.layer.open()`](https://unpoly.com/api/up.layer.open.md) can be configured. The configuration will also be used for [`[up-layer=new]`](https://unpoly.com/api/up-layer-new.md) links.

Defaults are configured separately for each [layer mode](https://unpoly.com/learn/overlays.md#layer-modes):

| Object | Effect |
| --- | --- |
| `up.layer.config.root` | Defaults for the root layer |
| `up.layer.config.modal` | Defaults for modal overlays |
| `up.layer.config.drawer` | Defaults for drawer overlays |
| `up.layer.config.popup` | Defaults for popup overlays |
| `up.layer.config.cover` | Defaults for cover overlays |

For convenience, you can configure options that affect all layer modes or all overlay modes:

| Object | Effect |
| --- | --- |
| `up.layer.config.any` | Defaults for all layers |
| `up.layer.config.overlay` | Defaults for all overlays |

<nav aria-label="Contents">

#### Contents

- [Configuration inheritance](#configuration-inheritance)
- [Example](#example)
- [Value](#value)

</nav>

## Configuration inheritance {#configuration-inheritance}

Options configured this way are inherited. For example, when you open a new drawer overlay, defaults from `up.layer.config.drawer`, `up.layer.config.overlay`, and `up.layer.config.any` will be used (in decreasing priority).

## Example {#example}

To make all modal overlays move in from beyond the top edge of the screen:

```js
up.layer.config.modal.openAnimation = 'move-from-top'
```

To configure an additional [main target](https://unpoly.com/api/up-main.md) for overlays of any mode:

```js
up.layer.config.overlay.mainTargets.unshift('.content')
```

---

## Value {#value}

### [config.mode='modal'] {#config.mode}

(optional)

The default [mode](https://unpoly.com/learn/overlays.md#layer-modes) used when opening a new overlay.

Type: string

### config.any {#config.any}

Defaults for all layer modes.

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

### config.any.mainTargets {#config.any.mainTargets}

An array of CSS selectors matching default [render targets](https://unpoly.com/learn/targeting-fragments.md).

This is an alias for [`up.fragment.config.mainTargets`](https://unpoly.com/api/up.fragment.config.md#config.mainTargets).

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

### config.root {#config.root}

Defaults for the [root layer](https://unpoly.com/learn/overlays.md#layer-modes).

Inherits from `up.layer.config.any`.

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

### config.root.mainTargets {#config.root.mainTargets}

An array of CSS selectors matching default [render targets](https://unpoly.com/learn/targeting-fragments.md) for the [root layer](https://unpoly.com/learn/overlays.md#layer-modes), but not for overlays.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

### config.overlay {#config.overlay}

Defaults for all [overlays](https://unpoly.com/learn/overlays.md#layer-modes).

In addition to the options documented here, all options for [`up.layer.open()`](https://unpoly.com/api/up.layer.open.md) may also be configured.

Inherits from `up.layer.config.any`.

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

### config.overlay.openAnimation {#config.overlay.openAnimation}

The opening animation.

Type: string | Function

### config.overlay.openDuration {#config.overlay.openDuration}

The duration of the opening animation.

Type: number

### config.overlay.openEasing {#config.overlay.openEasing}

The easing function for the opening animation.

Type: string

### config.overlay.closeAnimation {#config.overlay.closeAnimation}

The closing animation.

Type: string | Function

### config.overlay.closeDuration {#config.overlay.closeDuration}

The duration of the closing animation.

Type: number

### config.overlay.closeEasing {#config.overlay.closeEasing}

The easing function for the closing animation.

Type: string

### config.overlay.dismissLabel {#config.overlay.dismissLabel}

The label for the dismiss icon in the top-right corner.

Type: string

### config.overlay.dismissARIALabel {#config.overlay.dismissARIALabel}

The accessibility label for the dismiss icon in the top-right corner.

Type: string

### [config.overlay.history='auto'] {#config.overlay.history}

(optional)

Whether the layer's location or title will be visible in the browser's address bar and window title.

If set to `'auto'`, the overlay has [visible history](https://unpoly.com/learn/history-in-overlays.md) if its initial fragment is an [auto history target](https://unpoly.com/api/up.fragment.config.md#config.autoHistoryTargets).

If set to `true`, the overlay always has visible history. If set to `false`, the overlay never has visible history.

Type: string | boolean

### config.overlay.trapFocus {#config.overlay.trapFocus}

Whether to [trap focus](https://unpoly.com/learn/focus.md#overlay-focus-trap) within the overlay while it is in [front](https://unpoly.com/api/up.layer.front.md).

By default focus is trapped for all overlays except [popups](https://unpoly.com/learn/overlays.md#layer-modes).

Type: boolean

### [config.overlay.class] {#config.overlay.class}

(optional)

An HTML class for the overlay's container element.

See [overlay classes](https://unpoly.com/learn/customizing-overlays.md#overlay-classes).

Type: string

### config.modal {#config.modal}

Defaults for [modal overlays](https://unpoly.com/learn/overlays.md#layer-modes).

Inherits from `up.layer.config.overlay` and `up.layer.config.any`.

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

### config.cover {#config.cover}

Defaults for [cover overlays](https://unpoly.com/learn/overlays.md#layer-modes).

Inherits from `up.layer.config.overlay` and `up.layer.config.any`.

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

### config.drawer {#config.drawer}

Defaults for [drawer overlays](https://unpoly.com/learn/overlays.md#layer-modes).

Inherits from `up.layer.config.overlay` and `up.layer.config.any`.

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

### config.popup {#config.popup}

Defaults for [popup overlays](https://unpoly.com/learn/overlays.md#layer-modes).

Inherits from `up.layer.config.overlay` and `up.layer.config.any`.

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

### config.foreignOverlaySelectors {#config.foreignOverlaySelectors}

An array of CSS selectors matching overlays not constructed by Unpoly.

Other JavaScript libraries often attach their overlay elements to the end of the `<body>`, which makes Unpoly consider these overlays to be part of the root layer. This can cause Unpoly to steal focus from foreign overlays, or cause Unpoly overlays to close incorrectly when the foreign overlay is clicked. Adding a selector to this array will cause Unpoly to be less opinionated about user interactions within matching elements.

By default, this contains a selector matching the [`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>