API Customizing overlays

Overlays ship with minimal styling and common default behavior. That look and feel can be customized.

Picking the right mode

The default appearance and behavior is governed by the overlay's mode. The mode is set when the overlay is opened.

The following modes are available:

When building a custom overlay, start with the closest mode and customize the look and feel using one of the methods below.

Understanding the HTML structure

The various overlay modes have an HTML structure like this:

<up-modal size="medium">                     <!-- container with attributes -->
  <up-modal-backdrop></up-modal-backdrop>    <!-- semi-transparent background -->
  <up-modal-viewport>                        <!-- scroll bar -->
    <up-modal-box>                           <!-- white box with padding -->
      <up-modal-content>...</div>            <!-- content parent (unstyled) -->
      <up-modal-dismiss>×</up-modal-dismiss> <!-- dismiss icon -->
    </up-modal-box>
  </up-modal-viewport>
</up-modal>

For drawers and cover modals replace the <up-modal> elements with <up-drawer> or <up-cover> accordingly.

Popups have a simpler markup as they don't have a backdrop, scroll bar or dismiss icon:

<up-popup size="medium" position="bottom" align="left">
  <up-popup-box>
    <up-popup-content>...</div>
  </up-popup-box>
</up-popup>

Customizing overlays with CSS

Unpoly ships with some basic CSS styles for the various overlay modes.

You may override Unpoly's default styles in your CSS:

up-modal-box {
  background-color: #eeeeee;
  padding: 20px;
}

You may also style overlays with a particular property. E.g. the following selector would only match the box of a right-aligned popup:

up-popup[align=right] up-popup-box {
  ...
}

Overlay sizes

When opening an overlay you may pass an [up-size] attribute or { size } option that give the overlay a width:

<a href="/path" up-layer="new" up-size="small">open small modal</a>
<a href="/path" up-layer="new" up-size="medium">open medium modal</a>
<a href="/path" up-layer="new" up-size="large">open large modal</a>
<a href="/path" up-layer="new" up-size="grow">open growing modal</a>
<a href="/path" up-layer="new" up-size="full">open full-width modal</a>

If you don't pass a size you get a medium overlay.

Sizes set a maximum width for the overlay's box element (e.g. <up-modal-box>). The default widths are:

You can customize sizes with CSS:

up-modal[size=medium] up-modal-box {
  width: 500px;
}

Regardless of size, overlays never grow wider than the screen width.

Customizing dismiss controls

By default the user can dismiss an overlay user by pressing Escape, by clicking outside the overlay box or by pressing an "X" icon in the top-right corner.

You may customize the dismiss controls available to the user.

Overlay classes

Overlays are currently limited to the built-in overlay modes.

You may however make a variant of an existing mode, by passing an [up-class] attribute or { class } option when opening an overlay:

<a href="/confirm-erase"
   up-method="delete"
   up-layer="new"
   up-class="warning">
  Erase disk
</a>

The class will be assigned to the overlay's container element:

<up-modal class="warning">
...
</up-modal>

You can now style "warning modals" in your CSS:

up-modal.warning up-modal-box {
  background-color: yellow
}

Customizing overlay elements

The overlay HTML structure is static and cannot be changed through an option.

If you need to customize the overlay elements, you may use the up:layer:opened event. The event is emitted after the overlay was inserted into the DOM, but before it is being rendered by the browser.

up.on('up:layer:opened', function(event) {
  if (isChristmas()) {
    up.element.affix(event.layer.element, '.santa-hat', { text: 'Merry Christmas!' })
  }
})

Make sure to not remove any of the existing overlay elements or things will break.

Open and close animatios

When opening an overlay, you can configure an animation for the opening and closing sequence:

<a href="/details" up-layer="new" up-animation="move-from-top" up-close-animation="move-to-bottom">
  Open details
</a> 

Default animations can be configured in up.layer.config.

Popup position

By default popups will open below the link that opened it (the { origin }). You may control the position of the popup relative to the origin by assigning [up-position] and [up-align] attributes to the opening link:

<a href="/help" up-layer="new popup" up-position="top" up-align="right">Show help</a>

When opening an overlay with JavaScript, use { position, align } options.

The following combinations are supported:

Drawer position

By default, drawers will slide in on the left edge of the screen.

You can open a drawer on the edge by setting an [up-position="right"] attribute:

<a href="/settings" up-layer="new drawer" up-position="right">Settings</a>

From JavaScript, pass a { position: 'right' } option.