Top

Usage

A mask can be used for in-between loading states, like waiting for an AJAX request, to conceal the contents of an element. The mask element is appended and positioned absolutely within the target.

The mask component must be initialized on the element, the target, that we want to conceal.

$('.js-mask-target').mask();

The mask will not be shown until show() or toggle() is called on the mask object. The mask object can be retrieved by calling toolkit('mask') on the target collection.

$('.js-mask-target').toolkit('mask', 'toggle');
Applying a mask to body will cover the entire viewport.
Target elements will be styled with overflow hidden and position relative.

Custom Masks

If we want to customize the markup found within a mask, we can manually place the mask element within the target. This custom mask will be used instead of creating a new mask.

<div class="article js-mask-target">
    ...

    <div class="mask hide" data-mask>
        <div class="mask-message" data-mask-message">
            <!-- Custom markup -->
        </div>
    </div>
</div>
The data-mask-* attributes are required so that the JavaScript layer can find or bind elements in the DOM.

Automatic Toggling

Instead of toggling the display manually through the mask object, we can bind a click event to a button or element that triggers the toggle by defining the selector option.

$('.js-mask-target').mask({
    selector: '.js-mask-toggle'
});

Notes

  • Target elements will have a .is-maskable class applied.
  • Target elements will also have .is-masked applied when the mask is activated.
Top

Variables

Variable Default Description
$mask-class .mask CSS class name for the mask element.
$mask-class-message .mask-message CSS class name for the mask message.
$mask-class-target .is-maskable CSS class name for the mask target.
$mask-opacity 0.85 The alpha transparency for the masking element.
$mask-transition .3s The transition time for fading in and out.
$mask-zindex 500 The z-index for the mask element.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
messageTemplate string <div class="mask-message" data-mask-message></div> The loading message markup. The data-mask-message is required.
messageContent string The content to use as the message that appears in the center of the mask.
revealOnClick bool false Reveal the content and remove the mask when the mask is clicked.
template string <div class="mask" data-mask></div> The mask markup. The data-mask is required.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description Found With
mask element The mask element that covers the target element. Can be found as a child within the target element. [data-mask]
message element The message element found within the center of the mask element. [data-mask-message]
Top

Methods

Inherits all methods from the parent Component.

Method Description Bound To
toggle() Toggle the display of the mask. selector option