Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

lity

jsor25kMIT2.4.1

Lightweight, accessible and responsive lightbox.

lightbox, modal, popup, lightweight, responsive, accessible, accessibility, a11y, jquery, jquery-plugin, ecosystem:jquery

readme

Lity

Lity is a ultra-lightweight, accessible and responsive lightbox plugin which supports images, iframes and inline content out of the box.

Minified and gzipped, its total footprint weights about 3kB.

It requires jQuery or Zepto (with the callbacks, deferred and data modules).

Installation

All ready-to-use files are located in the dist/ directory.

Include the Lity javascript and css files and its dependencies in your HTML document:

<link href="dist/lity.css" rel="stylesheet">
<script src="vendor/jquery.js"></script>
<script src="dist/lity.js"></script>

Lity can also be installed via Bower or npm.

Usage

Declarative

Add the data-lity attribute to <a> elements for which you want the links to be opened in a lightbox:

<a href="https://farm9.staticflickr.com/8642/16455005578_0fdfc6c3da_b.jpg" data-lity>Image</a>
<a href="#inline" data-lity>Inline</a>
<a href="https://www.youtube.com/watch?v=XSGBVzeBUbk" data-lity>iFrame Youtube</a>
<a href="https://vimeo.com/1084537" data-lity>iFrame Vimeo</a>
<a href="https://maps.google.com/maps?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA" data-lity>Google Maps</a>

<div id="inline" style="background:#fff" class="lity-hide">
    Inline content
</div>

If you want to open another URI than defined in the href attribute, just add a data-lity-target with the URI:

<a href="/image.html" data-lity data-lity-target="/image-preview.jpg">Image</a>

Programmatic

The lity function can be either used directly to open URLs (or HTML) in a lightbox or as an event handler.

Lity lity(string target, [Object options, [, HTMLElement|$ opener]])

Arguments

  • target: The URL or HTML to open.
  • options: Options as an object of key-value pairs.
  • opener: The element which triggered opening the lightbox (if used as a event handler, this is automatically set to the element which triggered the event).

Return value

A Lity instance.

Example

// Open a URL or HTML in a lightbox
lity('https://www.youtube.com/watch?v=XSGBVzeBUbk');
lity('<p>Some content to show...</p>');

// Bind as an event handler
$(document).on('click', '[data-my-lightbox]', lity);

The Lity instance

If you open a lightbox programmatically, the lity function returns a Lity instance you can use to interact with the lightbox.

The Lity instance is also passed as the second argument to the event handlers.

var instance = lity('https://www.youtube.com/watch?v=XSGBVzeBUbk');

API

Lity.close

Closes the lightbox and returns a promise which resolves once the closing animation is finished.

instance.close().then(function() {
    console.log('Lightbox closed');
});

Lity.element

Returns the root HTML element.

var element = instance.element();

Lity.opener

Returns the HTML element which triggered opening the lightbox.

var opener = instance.opener();

Note: The value might be undefined if the lightbox has been opened programmatically and not by a click event handler and no opener argument was provided.

Lity.options

Sets or returns options of the instance.

var allOptions = instance.options();

var template = instance.options('template');
instance.options('template', '<div>...</div>');

var closeOnEsc = instance.options('esc');
instance.options('esc', false);

Events

All events receive the Lity instance as the second argument.

Available events

lity:open

Triggered before the lightbox is opened.

$(document).on('lity:open', function(event, instance) {
    console.log('Lightbox opened');
});

lity:ready

Triggered when the lightbox is ready.

$(document).on('lity:ready', function(event, instance) {
    console.log('Lightbox ready');
});

lity:close

Triggered before the lightbox is closed.

$(document).on('lity:close', function(event, instance) {
    console.log('Lightbox closed');
});

lity:remove

Triggered when the closing animation is finished and just before the lightbox is removed from the DOM.

$(document).on('lity:remove', function(event, instance) {
    console.log('Lightbox removed');
});

lity:resize

Triggered when the instance is resized, usually when the user resizes the window.

$(document).on('lity:resize', function(event, instance) {
    console.log('Lightbox resized');
});

License

Copyright (c) 2015-2020 Jan Sorgalla. Released under the MIT license.

changelog

Changelog for 2.x

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

2.4.1 - 2020-04-26

  • Compatibility with jQuery 3.5.0 (#240).

2.4.0 - 2019-08-10

  • Allow 'autoplay' on YouTube (#222).

2.3.1 - 2018-04-20

  • Fix dist files not compiled correctly for 2.3.0 release.

2.3.0 - 2017-07-17

  • Add esc option. Setting this option to false prevents the lightbox from being closed when pressing the ESC key.

2.2.2 - 2016-12-14

  • Fix focus() not always available on active element, eg. for SVG elements in IE11 (#86).

2.2.1 - 2016-11-21

  • Fix focus not returned correctly when active element is the lightbox root element.

2.2.0 - 2016-10-08

  • Add support for Facebook Video URL's (#63, thanks @iamandrewluca).
  • Fix compatibility with Zepto and note requirement of the data module.

2.1.1 - 2016-09-19

  • Correctly transfer hashes for generated YouTube, Vimeo and Google Maps URLs. For example when linking to a specific video start time, eg. https://vimeo.com/1084537#t=1m15s.

2.1.0 - 2016-09-19

  • Images in ligtboxes now have an alt attribute set. The content is configurable through the data-lity-desc attribute on the opener element.
  • Initial focus is now set on the dialog element, not on the first focusable element inside the content. This prevents inline content scrolled down if the first focusable element is at the bottom of the content.
  • The global click event is now namespaced as click.lity for easier unbinding.

2.0.0 - 2016-09-09

New major release. See the upgrade guide for detailed information about upgrading from 1.x.

  • Lity is now fully accessible complying with the Web Content Accessibility Guidelines (WCAG) 2.0.
  • The lity function is now used directly to open a lightbox. There is no longer a function returned but a Lity instance.
  • All custom events triggered by Lity receive now one parameter: a Lity instance.
  • There are now dedicated youtube, vimeo and googlemaps handlers extracted from the iframe handler.

Older versions

  • The changelog for Lity 1.x can be found here.