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/NextKeys: Navigate through slidesESCAPEKey: Close TobiiTABKey: Focus elements within Tobii, not outside
- User preference media features:
prefers-reduced-motionmedia 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/swipe support:
- Horizontal to navigate through slides
- Vertical up to close Tobii
- Double click, pinch and wheel zoom:
- Hold pointer to pan
- Responsive
CSS: dist/tobii.min.css
JavaScript:
dist/tobii.min.js: minified IIFE builddist/tobii.modern.js: 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-heightset the height anddata-widththe 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-controlsindicates whether the video player controls are displayed:0do not display and1display controls in the player.data-heightset the height anddata-widththe 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. |
| captionHTML | bool | false | Allow HTML captions. |
| captionToggle | bool | true | Allows users to hide or show the caption by clicking or tapping on it. |
| captionToggleLabel | string | ["Hide caption", "Show caption"] | Labels for the caption display toggle button. |
| 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. |
| dialogTitle | string | "Lightbox" | 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 | false | 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). |
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
- 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.