Working with captions

Out of the box a caption is the title attribute of the image inside the link. Four options decide where the text is read from: captions, captionSelector, captionType and captionsData.

<a href="images/dune.jpg">
    <img src="images/thumbs/dune.jpg" alt="Red dune" title="Red dune under a deep blue sky">
</a>

The defaults are captionSelector: 'img', captionType: 'attr' and captionsData: 'title'. Set captions: false to switch captions off completely.

Many sites already write a good alt text for every image. Reading the caption from it avoids keeping two texts in sync:

new SimpleLightbox('.gallery a', { captionsData: 'alt' });

This works best when the alt text describes what the photo shows. If your alt texts are short labels such as “photo 1”, keep a separate title.

With captionType: 'data' the text comes from a data attribute. captionsData is the name after data-, and captionSelector: 'self' reads it from the link itself:

// <a href="images/dune.jpg" data-caption="Red dune under a deep blue sky">…</a>
new SimpleLightbox('.gallery a', {
    captionSelector: 'self',
    captionType: 'data',
    captionsData: 'caption'
});

captionType: 'text' takes the content of an element instead of an attribute, so captions can contain formatting. captionSelector may also be a function that receives the link and returns the element — handy when the caption lives next to the link, as in a <figure>:

new SimpleLightbox('figure a', {
    captionSelector: function (link) {
        return link.parentNode.querySelector('figcaption');
    },
    captionType: 'text'
});

• captionPosition — 'bottom' (default), 'top' or 'outside'. An outside caption can end up below the visible area on tall images.
• captionDelay — milliseconds to wait before the caption appears, useful when it should not compete with the image transition.
• captionClass — one or several extra classes for the caption element, separated by spaces or commas.
• fadeSpeed — also controls how fast captions fade in and out.

Colours and sizes come from the stylesheet. With SASS, change $sl-caption-color, $sl-caption-background and $sl-caption-fontsize; with plain CSS, target the caption class you set in captionClass.

A caption is read in the second it takes to look at the photo. Keep it to one line, say what is in the picture or where it was taken, and leave out what the page title already says. Credits and dates fit at the end, after a separator.

The gallery below reads its captions from data-caption on the links and shows them at the top:

• Migrating from 1.x to 2.x
• Dynamic galleries and refresh()
• Touch, swipe and zoom settings

Or go back to the full list of options.