https://github.com/jsor/lity
Lightweight, accessible and responsive lightbox.
https://github.com/jsor/lity
accessibility accessible javascript lightbox lightweight lity modal responsive
Last synced: 25 days ago
JSON representation
Lightweight, accessible and responsive lightbox.
- Host: GitHub
- URL: https://github.com/jsor/lity
- Owner: jsor
- License: mit
- Created: 2015-02-24T14:20:53.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-07-28T23:01:02.000Z (almost 2 years ago)
- Last Synced: 2025-04-06T17:08:22.198Z (2 months ago)
- Topics: accessibility, accessible, javascript, lightbox, lightweight, lity, modal, responsive
- Language: HTML
- Homepage: https://sorgalla.com/lity/
- Size: 2.63 MB
- Stars: 1,161
- Watchers: 38
- Forks: 194
- Open Issues: 85
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
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](https://jquery.com) or [Zepto](http://zeptojs.com)
(with the [callbacks](https://github.com/madrobby/zepto/blob/master/src/callbacks.js),
[data](https://github.com/madrobby/zepto/blob/master/src/data.js),
[deferred](https://github.com/madrobby/zepto/blob/master/src/deferred.js) and
[event](https://github.com/madrobby/zepto/blob/master/src/event.js) modules).
Installation
------------
All ready-to-use files are located in the [`dist/`](dist/) directory.
Include the Lity javascript and css files and its dependencies in your HTML
document:
```html
```
Lity can also be installed via Bower or [npm](https://www.npmjs.com/package/lity).
Usage
-----
### Declarative
Add the `data-lity` attribute to `` elements for which you want the links to
be opened in a lightbox:
```html
Image
Inline
iFrame Youtube
iFrame Vimeo
Google Maps
Inline content
```
If you want to open another URI than defined in the `href` attribute, just add
a `data-lity-target` with the URI:
```html
Image
```
### 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`](#the-lity-instance) instance.
#### Example
```javascript
// Open a URL or HTML in a lightbox
lity('https://www.youtube.com/watch?v=XSGBVzeBUbk');
lity('
Some content to show...
');
// 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](#events).
```javascript
var instance = lity('https://www.youtube.com/watch?v=XSGBVzeBUbk');
```
### API
* [Lity.close](#lityclose)
* [Lity.element](#lityelement)
* [Lity.opener](#lityopener)
* [Lity.content](#litycontent)
* [Lity.options](#lityoptions)
#### Lity.close
Closes the lightbox and returns a promise which resolves once the closing
animation is finished.
```javascript
instance.close().then(function() {
console.log('Lightbox closed');
});
```
#### Lity.element
Returns the root HTML element.
```javascript
var element = instance.element();
```
#### Lity.opener
Returns the HTML element which triggered opening the lightbox.
```javascript
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.content
Returns the content HTML element.
```javascript
var content = instance.content();
```
**Note**: The value is undefined while the content is loading.
#### Lity.options
Sets or returns options of the instance.
```javascript
var allOptions = instance.options();
var template = instance.options('template');
instance.options('template', '
...');
var closeOnEsc = instance.options('esc');
instance.options('esc', false);
```
Events
------
All events receive the [`Lity`](#the-lity-instance) instance as the second
argument.
### Available events
* [lity:open](#lityopen)
* [lity:ready](#lityready)
* [lity:close](#lityclose)
* [lity:remove](#lityremove)
* [lity:resize](#lityresize)
#### lity:open
Triggered before the lightbox is opened.
```javascript
$(document).on('lity:open', function(event, instance) {
console.log('Lightbox opened');
});
```
#### lity:ready
Triggered when the lightbox is ready.
```javascript
$(document).on('lity:ready', function(event, instance) {
console.log('Lightbox ready');
});
```
#### lity:close
Triggered before the lightbox is closed.
```javascript
$(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.
```javascript
$(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.
```javascript
$(document).on('lity:resize', function(event, instance) {
console.log('Lightbox resized');
});
```
License
-------
Copyright (c) 2015-2020 Jan Sorgalla.
Released under the [MIT](LICENSE?raw=1) license.
