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 at 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>
Copy to clipboard
  • <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>
Copy to clipboard
  • <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>
Copy to clipboard
  • <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>
Copy to clipboard
  • Slide
    Fade
    Scale
  • <div class="uk-h3 uk-margin">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 uk-margin">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 uk-margin">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>

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="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    data-poster="image.jpg"
  ></a>
  <a class="uk-button" href="https://www.youtube.com/watch?v=aqz-KE-bpKQ"></a>
  <a class="uk-button" href="https://vimeo.com/1084537"></a>
  <a class="uk-button" href="https://www.google.com/maps"></a>
</div>
Copy to clipboard
  • <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.

OptionDescription
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.

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=aqz-KE-bpKQ"
    data-attrs="width: 1280; height: 720;"
  ></a>
</div>
Copy to clipboard
  • <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>

Component options

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

OptionValueDefaultDescription
animationStringslideLightbox animation mode (slide, fade or scale).
autoplayBooleanfalseLightbox autoplays.
autoplay-intervalNumber7000The delay between switching slides in autoplay mode.
pause-on-hoverBooleanfalsePause autoplay mode on hover.
video-autoplayBooleanfalseLightbox videos autoplay.
indexString, Number0Lightbox item to show. 0 based index.
toggleCSS selectoraToggle 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.

OptionValueDefaultDescription
animationStringslideLightbox animation mode (slide, fade or scale).
autoplayBooleanfalseLightbox autoplays.
autoplay-intervalNumber7000The delay between switching slides in autoplay mode.
pause-on-hoverBooleanfalsePause autoplay mode on hover.
video-autoplayBooleanfalseLightbox videos autoplay.
indexNumber0The initial item to show. (zero based)
velocityNumber2The animation velocity (pixel/ms).
preloadNumber1The number of items to preload. (left and right of the currently active item)
itemsArray[]An array of items to display, e.g. [{source: '/images/size1.jpg', caption: '900x600'}]
templateStringDefault markupThe template string.
delay-controlsNumber3000Delay time before controls fade out in ms.
containerStringbodyDefine 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:

NameDescription
beforeshowFires before the Lightbox is shown.
beforehideFires before the Lightbox is hidden.
showFires after the Lightbox is shown.
shownFires after the Lightbox’s show animation has completed.
hideFires after the Lightbox’s hide animation has started.
hiddenFires after the Lightbox is hidden.
itemloadFires when an item loads.
beforeitemshowFires before an item is shown.
itemshowFires after an item is shown.
itemshownFires after an item’s show animation has completed.
beforeitemhideFires before an item is hidden.
itemhideFires after an item’s hide animation has started.
itemhiddenFires 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.

NameTypeDefaultDescription
indexString, Number0Lightbox 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 lightbox has the dialog role, the aria-modal property and the aria-roledescription property set to carousel.
  • The slide list has an ID, the presentation role and the aria-live property.
  • The slides have an ID, the group role, the aria-roledescription property set to slide and an aria-label property.

The previous/next navigation adheres to the button pattern.

  • The prev/next navigation items have the button role, the aria-controls property set to the ID of the slide list, and an aria-label property.

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

  • The close icon has the aria-label property, and if an <a> element is used, the button role.

Keyboard interaction

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

  • The left/right arrow keys navigate through the slides. If the focus is on the last slide, it moves to the first slide.
  • The home or end keys move the focus to the first or last slide.
  • The esc key closes the lightbox.

Internationalization

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

KeyDefaultDescription
nextNext Slidearia-label for next slide button.
previousPrevious Slidearia-label for previous slide button.
slideLabel%s of %saria-label for slide.
closeClosearia-label for close button.

Theme development

On your tailwind.config.js file, add the Lightbox component within the ui() plugin.

import ui from "franken-ui";

ui({
    components: {
        lightbox: {
            hooks: {}
        }
    }
}),

Available hooks

Note If you are developing theme from scratch, you can use all these hooks. If you’re using the shadcn/ui theme, some hooks might not work as they were already in use or removed. Learn more about using hooks.

Hook NameAffected Classes
hook-lightbox.uk-lightbox
hook-item.uk-lightbox-items > *
hook-toolbar.uk-lightbox-toolbar
hook-toolbar-icon.uk-lightbox-toolbar-icon
hook-toolbar-icon-hover.uk-lightbox-toolbar-icon:hover
hook-button.uk-lightbox-button
hook-button-hover.uk-lightbox-button:hover
hook-button-active.uk-lightbox-button:active
hook-misc*