An accessible, open-source lightbox with no dependencies.
- Features
- Get Tobii
- Usage
- Media types
- Grouping
- Options
- API
- Events
- Browser support
- Contributing
- License
- No dependencies
- Supports multiple content types:
- Images
- Inline HTML
- Iframes
- Videos (YouTube, Vimeo)
- Grouping
- Events
- Customizable with settings and CSS
- Accessible:
- ARIA roles
- Keyboard navigation:
Prev
/Next
Keys: Navigate through slidesESCAPE
Key: Close TobiiTAB
Key: Focus elements within Tobii, not outside
- User preference media features:
prefers-reduced-motion
media query
- When Tobii opens, focus is set to the first focusable element in Tobii
- When Tobii closes, focus returns to what was in focus before Tobii opened
- Touch & Mouse drag support:
- Drag/ Swipe horizontal to navigate through slides
- Drag/ Swipe vertical to close Tobii
- Responsive
CSS: dist/tobii.min.css
JavaScript:
dist/tobii.min.js
: IIFE build for maximum browser support, including IE 11dist/tobii.mjs
: Build specially designed to work in all modern browsersdist/tobii.module.js
: ESM builddist/tobii.umd.js
: UMD builddist/tobii.js
: CommonJS/Node build
Tobii is also available on npm.
npm install @midzer/tobii --save
You can install Tobii by linking the .css
and .js
files to your HTML file. The HTML code may look like this:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Your page title</title>
<!-- CSS -->
<link href="tobii.min.css" rel="stylesheet">
</head>
<body>
<!-- Your HTML content -->
<!-- JS -->
<script src="tobii.min.js"></script>
</body>
</html>
Initialize the script by running:
const tobii = new Tobii()
The standard way of using Tobii is a linked thumbnail image with the class name lightbox
to a larger image:
<a href="path/to/image.jpg" class="lightbox">
<img src="path/to/thumbnail.jpg" alt="I am a caption">
</a>
Instead of a thumbnail, you can also refer to a larger image with a text link:
<a href="path/to/image.jpg" class="lightbox">
Open image
</a>
If you use a Markdown parser or CMS and want to make all images in a post automatically viewable in a lightbox, use the following JavaScript code to add all images to the same album:
document.addEventListener('DOMContentLoaded', () => {
// This assumes your article is wrapped in an element with the class "content-article".
document.querySelectorAll('.content-article img').forEach((articleImg) => {
// Add lightbox elements in blog articles for Tobii.
const lightbox = document.createElement('a');
lightbox.href = articleImg.src;
lightbox.classList.add('lightbox');
lightbox.dataset.group = 'article';
articleImg.parentNode.appendChild(lightbox);
lightbox.appendChild(articleImg);
});
});
For inline HTML, create an element with a unique ID:
<div id="selector">
<!-- Your HTML content -->
</div>
Then create a link with the class name lightbox
and a href
attribute that matches the ID of the element:
<a href="#selector" data-type="html" class="lightbox">
Open HTML content
</a>
or a button with the class name lightbox
and a data-target
attribute that matches the ID of the element:
<button type="button" data-type="html" data-target="#selector" class="lightbox">
Open HTML content
</button>
In both ways, the attribute data-type
with the value html
is required.
For an iframe, create a link with the class name lightbox
:
<a href="https://www.wikipedia.org" data-type="iframe" class="lightbox">
Open Wikipedia
</a>
or a button with the class name lightbox
and a data-target
attribute:
<button type="button" data-type="iframe" data-target="https://www.wikipedia.org" class="lightbox">
Open Wikipedia
</button>
In both ways, the attribute data-type
with the value iframe
is required.
data-height
set the height anddata-width
the width of the iframe.
For a YouTube video, create a link with the class name lightbox
and a data-id
attribute with the YouTube video ID:
<a href="#" data-type="youtube" data-id="KU2sSZ_90PY" class="lightbox">
Open YouTube video
</a>
or a button with the class name lightbox
and a data-id
attribute with the YouTube video ID:
<button type="button" data-type="youtube" data-id="KU2sSZ_90PY" class="lightbox">
Open YouTube video
</button>
In both ways, the attribute data-type
with the value youtube
is required.
data-controls
indicates whether the video player controls are displayed:0
do not display and1
display controls in the player.data-height
set the height anddata-width
the width of the player. I recommend using an external library for responsive iframes.
If you have a group of related types that you would like to combine into a set, add the data-group
attribute:
<a href="path/to/image_1.jpg" class="lightbox" data-group="vacation">
<img src="path/to/thumbnail_1.jpg" alt="I am a caption">
</a>
<a href="path/to/image_2.jpg" class="lightbox" data-group="vacation">
<img src="path/to/thumbnail_2.jpg" alt="I am a caption">
</a>
// ...
<a href="path/to/image_4.jpg" class="lightbox" data-group="birthday">
<img src="path/to/thumbnail_4.jpg" alt="I am a caption">
</a>
// ...
You can pass an object with custom options as an argument.
const tobii = new Tobii({
captions: false
})
The following options are available:
Property | Type | Default | Description |
---|---|---|---|
selector | string | ".lightbox" | All elements with this class triggers Tobii. |
captions | bool | true | Display captions, if available. |
captionsSelector | "self", "img" | "img" | Set the element where the caption is. Set it to "self" for the a tag itself. |
captionAttribute | string | "alt" | Get the caption from given attribute. |
captionText | function | null | Custom callback which returns the caption text for the current element. The first argument of the callback is the element. If set, captionsSelector and captionAttribute are ignored. |
nav | bool, "auto" | "auto" | Display navigation buttons. "auto" hides buttons on touch-enabled devices. |
navText | string | ["inline svg", "inline svg"] | Text or HTML for the navigation buttons. |
navLabel | string | ["Previous", "Next"] | ARIA label for screen readers. |
close | bool | true | Display close button. |
closeText | string | "inline svg" | Text or HTML for the close button. |
closeLabel | string | "Close" | ARIA label for screen readers. |
loadingIndicatorLabel | string | "Image loading" | ARIA label for screen readers. |
counter | bool | true | Display current image index. |
keyboard | bool | true | Allow keyboard navigation. |
zoom | bool | true | Display zoom icon. |
zoomText | string | "inline svg" | Text or HTML for the zoom icon. |
docClose | bool | true | Click outside to close Tobii. |
swipeClose | bool | true | Swipe up to close Tobii. |
draggable | bool | true | Use dragging and touch swiping. |
threshold | number | 100 | Touch and mouse dragging threshold (in px). |
autoplayVideo | bool | false | Videos will automatically start playing as soon as they can do so without stopping to finish loading the data. |
You can also use data attributes to customize HTML elements.
<a href="path/to/image.jpg" class="lightbox" data-group="custom-group">
Open image.
</a>
The following options are available:
Property | Description |
---|---|
data-type | Sets media type. Possible values: html ,iframe ,youtube . |
data-id | Required for youtube media type. |
data-target | Can be used to set target for "iframe" and "html" types. |
data-group | Set custom group |
data-width | Set container width for iframe or youtube types. |
data-height | Set container height for iframe or youtube types. |
data-controls | Indicates whether the video player controls are displayed: 0 do not display and 1 display controls in the player. |
data-allow | Allows to set allow attribute on iframes. |
data-srcset | Allows to have Responsive image or retina images |
data-zoom | Allows to enable or disable zoom icon. Values: "true" or "false" |
Function | Description |
---|---|
open(index) |
Open Tobii. Optional index (Integer), zero-based index of the slide to open. |
select(index) |
Select a slide with index (Integer), zero-based index of the slide to select. |
previous() |
Select the previous slide. |
next() |
Select the next slide. |
selectGroup(value) |
Select a group with value (string), name of the group to select. |
close() |
Close Tobii. |
add(element) |
Add element (DOM element). |
remove(element) |
Remove element (DOM element). |
isOpen() |
Check if Tobii is open. |
slidesIndex() |
Return the current slide index. |
slidesCount() |
Return the current number of slides. |
currentGroup() |
Return the current group name. |
reset() |
Reset Tobii. |
destroy() |
Destroy Tobii. |
Bind events with the .on()
and .off()
methods.
const tobii = new Tobii()
const listener = function listener () {
console.log('eventName happened')
}
// bind event listener
tobii.on(eventName, listener)
// unbind event listener
tobii.off(eventName, listener)
eventName | Description |
---|---|
open |
Triggered after Tobii has been opened. |
close |
Triggered after Tobii has been closed. |
previous |
Triggered after the previous slide is selected. |
next |
Triggered after the next slide is selected. |
Tobii supports the following browser (all the latest versions):
- Chrome
- Firefox
- Internet Explorer 11
- Edge
- Safari
- Open an issue or a pull request to suggest changes or additions
- Spread the word
Tobii is available under the MIT license. See the LICENSE file for more info.