Skip to main content

Documentation

Lightbox

Create a responsive lightbox gallery with images and videos.

The Lightbox component is fully responsive and supports touch and swipe navigation, as well as mouse drag for desktops. When swiping between slides the animation literally sticks to your fingertip or mouse cursor. Clicking fast on the previous and next navigation, will make animations even accelerate to keep up with your pace. All animations are hardware accelerated for a smoother performance.

Usage

To apply this component, add the uk-lightbox attribute to a container to turn all anchors inside that container into lightbox links.

<div uk-lightbox>
    <a href="image.jpg"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg">Open Lightbox</a>
</div>

Alt attribute

To add an alt attribute to the image in the lightbox, set the data-alt attribute on an anchor.

<div uk-lightbox>
    <a href="image.jpg" data-alt="Image"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-alt="Image">Open Lightbox</a>
</div>

Caption

To display a caption at the bottom of the lightbox, set the data-caption attribute on an anchor.

<div uk-lightbox>
    <a href="image.jpg" data-caption="Caption"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

Animations

By default, the Lightbox gallery uses a slide animation. You can set the animation option to use a different one. Possible values are slide, fade and scale.

<div uk-lightbox="animation: fade">
    <a href="image.jpg"></a>
</div>
Slide
Fade
Scale
<div class="uk-h3">Slide</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: slide">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Fade</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: fade">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Scale</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="animation: scale">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

By default, the lightbox shows a slidenav from the Slidenav component. To hide the slidenav, set the slidenav: false option. To show an item-based navigation, for example, from the Thumbnav component or Dotnav component, set the nav option to thumbnav or dotnav. 

<div uk-lightbox="slidenav: false; nav: thumbnav">
    <a href="image.jpg"></a>
</div>
Thumbnav
Dotnav
<div class="uk-h3">Thumbnav</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: thumbnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

<div class="uk-h3">Dotnav</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: dotnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

Counter

To show a counter with the current item number and the total number of items, add the counter: true option.

<div uk-lightbox="counter: true">
    <a href="image.jpg"></a>
</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="counter: true">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

Color mode

To adapt the color of the overlaying controls for better visibility depending on the lightbox content, use the data-attrs option to add the .uk-inverse-light or .uk-inverse.dark class from the Inverse component.

<div uk-lightbox>
    <a href="image.jpg" data-attrs="class: uk-inverse-light"></a>
</div>
<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="nav: thumbnav; slidenav: false">
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2" data-attrs="class: uk-inverse-light">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3" data-attrs="class: uk-inverse-dark">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

Content sources

A lightbox is not restricted to images. Other media, like videos, can be displayed as well. The video will pause whenever it's not visible and resume once it becomes visible again. To display a poster image for a video, set the data-poster attribute.

<div uk-lightbox>
    <a class="uk-button" href="video.mp4" data-poster="image.jpg"></a>
    <a class="uk-button" href="https://www.youtube.com/watch?v=c2pz2mlSfXA"></a>
    <a class="uk-button" href="https://vimeo.com/1084537"></a>
    <a class="uk-button" href="https://www.google.com/maps"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Image">Image</a>
    <a class="uk-button uk-button-default" href="https://yootheme.com/site/images/media/yootheme-pro.mp4" data-caption="Video">Video</a>
    <a class="uk-button uk-button-default" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-caption="YouTube">YouTube</a>
    <a class="uk-button uk-button-default" href="https://vimeo.com/1084537" data-caption="Vimeo">Vimeo</a>
    <a class="uk-button uk-button-default" href="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d4740.819266853735!2d9.99008871708242!3d53.550454675412404!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x0%3A0x3f9d24afe84a0263!2sRathaus!5e0!3m2!1sde!2sde!4v1499675200938" data-caption="Google Maps" data-type="iframe">Google Maps</a>
</div>

Note Use youtube-nocookie.com within the YouTube link and the lightbox will use the domain to embed the YouTube video.

Manual content type

The Lightbox uses the href attribute to figure out the type of the linked content. If no filename extension is defined in the path, just add the data-type attribute to the <a> tag.

Hint YouTube and Vimeo URLs will be handled automatically.

Option Description
data-type="image" The content type is an image.
data-type="video" The content type is a video.
data-type="iframe" The content type is a regular website.

Delay controls

By default, the controls are hidden after a short time if the mouse doesn't move. Set the delay-controls: 0 option to always show the controls.

<div uk-lightbox="delay-controls: 0">
    <a href="image.jpg"></a>
</div>
<div uk-lightbox="delay-controls: 0">
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

BG close

By default, the lightbox closes if the background is clicked. To prevent this behavior, set the bg-close: false option.

<div uk-lightbox="bg-close: false">
    <a href="image.jpg"></a>
</div>
<div uk-lightbox="bg-close: false">
    <a class="uk-button uk-button-default" href="images/photo.jpg" data-caption="Caption">Open Lightbox</a>
</div>

Custom attributes

You can add custom attributes to lightbox content items by using the data-attrs attribute. The attributes are passed like the usual component options, e.g. data-attrs="width: 1280; height: 720;"

<div uk-lightbox>
    <a class="uk-button" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-attrs="width: 1280; height: 720;"></a>
</div>
<div uk-lightbox>
    <a class="uk-button uk-button-default" href="https://www.youtube.com/watch?v=c2pz2mlSfXA" data-caption="YouTube" data-attrs="width: 1280; height: 720;">YouTube</a>
</div>

Custom template

This is the default lightbox template.

<div class="uk-lightbox uk-overflow-hidden">
    <div class="uk-lightbox-items"></div>
    <div class="uk-position-top-right uk-position-small uk-transition-fade" uk-inverse>
        <button class="uk-lightbox-close uk-close-large" type="button" uk-close></button>
    </div>
    <div class="uk-position-center-left uk-position-medium uk-transition-fade" uk-inverse>
        <a class="uk-lightbox-slidenav" href uk-slidenav-previous uk-lightbox-item="previous"></a>
    </div>
    <div class="uk-position-center-right uk-position-medium uk-transition-fade" uk-inverse>
        <a class="uk-lightbox-slidenav" href uk-slidenav-next uk-lightbox-item="next"></a>
    </div>
    <div class="uk-position-center-right uk-position-medium" uk-inverse uk-toggle="cls: uk-position-center-right uk-position-bottom-center; mode: media; media: @s">
        <ul class="uk-lightbox-thumbnav uk-thumbnav uk-thumbnav-vertical" uk-toggle="cls: uk-thumbnav-vertical; mode: media; media: @s"></ul>
        <ul class="uk-lightbox-dotnav uk-dotnav uk-dotnav-vertical" uk-toggle="cls: uk-dotnav-vertical; mode: media; media: @s"></ul>
    </div>
    <div class="uk-lightbox-counter uk-text-large uk-position-top-left uk-position-small uk-transition-fade" uk-inverse></div>
    <div class="uk-lightbox-caption uk-position-bottom uk-text-center uk-transition-slide-bottom uk-transition-opaque"></div>
</div>

To override the default lightbox template, add the template: #ID option to link it to a template element with the new lightbox layout.

<template id="js-lightbox-template">…</template>

<div uk-lightbox="template: #js-lightbox-template">…</div>
<template id="js-lightbox-template">
    <div class="uk-lightbox uk-overflow-hidden">
        <div class="uk-lightbox-items"></div>
        <div class="uk-position-top-right uk-position-small uk-transition-fade" uk-inverse>
            <button class="uk-lightbox-close uk-close-large" type="button" uk-close></button>
        </div>
        <div class="uk-position-bottom uk-position-medium uk-text-center uk-transition-fade" uk-inverse>
            <div class="uk-grid-small uk-width-auto uk-flex-inline uk-flex-middle" uk-grid>
                <div><a class="uk-lightbox-slidenav" href uk-slidenav-previous uk-lightbox-item="previous"></a></div>
                <div><div class="uk-lightbox-counter"></div></div>
                <div><a class="uk-lightbox-slidenav" href uk-slidenav-next uk-lightbox-item="next"></a></div>
            </div>
        </div>
    </div>
</template>

<div class="uk-child-width-1-3@m" uk-grid uk-lightbox="template: #js-lightbox-template; counter: true">
    <div>
        <a class="uk-inline" href="images/photo.jpg" data-caption="Caption 1">
            <img src="images/photo.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/dark.jpg" data-caption="Caption 2">
            <img src="images/dark.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
    <div>
        <a class="uk-inline" href="images/light.jpg" data-caption="Caption 3">
            <img src="images/light.jpg" width="1800" height="1200" alt="">
        </a>
    </div>
</div>

Component options

Any of these options can be applied to the component attribute. Separate multiple options with a semicolon. Learn more

Option Value Default Description
animation String slide Lightbox animation mode (slide, fade or scale).
autoplay Boolean false Lightbox autoplays.
autoplay-interval Number 7000 The delay between switching slides in autoplay mode.
pause-on-hover Boolean false Pause autoplay mode on hover.
video-autoplay Boolean, String false Lightbox videos autoplay. A value of inline will autoplay the video, make it muted and without controls.
counter Boolean false Lightbox shows counter.
nav Boolean, String false Lightbox navigation (dotnav, thumbnav).
slidenav Boolean true Lightbox shows slidenav controls.
index String, Number 0 Lightbox item to show. 0 based index.
delay-controls Number 3000 Delay time before controls fade out in ms. Setting 0 will prevent hiding controls.
toggle CSS selector a Toggle selector - opens the Lightbox Panel upon click.

JavaScript

Learn more about JavaScript components.

Initialization

// To apply lightbox to a group of links
UIkit.lightbox(element, options);

// To dynamically initialize the lightbox panel
UIkit.lightboxPanel(panelOptions);

Methods

The following methods are available for the component:

Show

UIkit.lightbox(element).show(index);

Shows the Lightbox's Panel and item.

Hide

UIkit.lightbox(element).hide();

Hides the Lightbox's Panel.

If you only want to use the lightbox panel directly through the JS API, you can set the following options.

Option Value Default Description
animation String slide Lightbox animation mode (slide, fade or scale).
autoplay Boolean false Lightbox autoplays.
autoplay-interval Number 7000 The delay between switching slides in autoplay mode.
pause-on-hover Boolean false Pause autoplay mode on hover.
video-autoplay Boolean, String false Lightbox videos autoplay. A value of inline will autoplay the video, make it muted and without controls.
counter Boolean false Lightbox shows counter.
nav Boolean, String false Lightbox navigation (dotnav, thumbnav).
slidenav Boolean true Lightbox shows slidenav controls.
index Number 0 The initial item to show. (zero-based)
velocity Number 2 The animation velocity (pixel/ms).
preload Number 1 The number of items to preload. (left and right of the currently active item)
items Array [] An array of items to display, e.g. [{source: 'images/size1.jpg', caption: '900x600'}]
template String Default markup The template string.
delay-controls Number 3000 Delay time before controls fade out in ms. Setting 0 will prevent hiding controls.
container String body Define a target container via a selector to specify where the Lightbox should be appended in the DOM.

Events

The following events will be triggered on elements with this component attached:

Name Description
beforeshow Fires before the Lightbox is shown.
beforehide Fires before the Lightbox is hidden.
show Fires after the Lightbox is shown.
shown Fires after the Lightbox's show animation has completed.
hide Fires after the Lightbox's hide animation has started.
hidden Fires after the Lightbox is hidden.
itemload Fires when an item loads.
beforeitemshow Fires before an item is shown.
itemshow Fires after an item is shown.
itemshown Fires after an item's show animation has completed.
beforeitemhide Fires before an item is hidden.
itemhide Fires after an item's hide animation has started.
itemhidden Fires after an item's hide animation has completed.

Methods

The following methods are available for the component:

Show

UIkit.lightboxPanel(element).show(index);

Shows the Lightbox Panel and item.

Name Type Default Description
index String, Number 0 Lightbox item to show. 0 based index.

Hide

UIkit.lightboxPanel(element).hide();

Hides the Lightbox Panel.

startAutoplay

UIkit.lightboxPanel(element).startAutoplay();

Starts the Lightbox's autoplay.

stopAutoplay

UIkit.lightboxPanel(element).stopAutoplay();

Stops the Lightbox's autoplay.

Accessibility

The Lightbox component adheres to the Dialog (Modal) WAI-ARIA design pattern and the Carousel WAI-ARIA design pattern and automatically sets the appropriate WAI-ARIA roles, states and properties.

The previous/next navigation adheres to the button pattern.

The Close component automatically sets the appropriate WAI-ARIA roles and properties.

Keyboard interaction

The lightbox gallery can be accessed through the keyboard using the following keys.

Internationalization

The Lightbox component uses the following translation strings. Learn more about translating components.

Key Default Description
next Next Slide aria-label for next slide button.
previous Previous Slide aria-label for previous slide button.
slideLabel %s of %s aria-label for slide.
close Close aria-label for close button.