{"id":15019909,"url":"https://github.com/marekdedic/imagelightbox","last_synced_at":"2026-04-02T05:38:34.451Z","repository":{"id":16213663,"uuid":"18960713","full_name":"marekdedic/imagelightbox","owner":"marekdedic","description":"Image Lightbox, Responsive and Touch‑friendly","archived":false,"fork":false,"pushed_at":"2025-05-05T12:20:40.000Z","size":120969,"stargazers_count":127,"open_issues_count":2,"forks_count":38,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-11T06:56:57.867Z","etag":null,"topics":["image-lightbox","javascript","jquery"],"latest_commit_sha":null,"homepage":"https://marekdedic.github.io/imagelightbox/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marekdedic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-04-20T08:32:32.000Z","updated_at":"2025-05-05T12:20:09.000Z","dependencies_parsed_at":"2024-01-15T10:44:21.846Z","dependency_job_id":"bb568af1-4717-4263-8b01-390afabceb78","html_url":"https://github.com/marekdedic/imagelightbox","commit_stats":{"total_commits":1716,"total_committers":27,"mean_commits":63.55555555555556,"dds":0.587995337995338,"last_synced_commit":"f55e5518059ec73594e8c8408ab22b976d41ea56"},"previous_names":["rejas/imagelightbox"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marekdedic%2Fimagelightbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marekdedic%2Fimagelightbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marekdedic%2Fimagelightbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marekdedic%2Fimagelightbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marekdedic","download_url":"https://codeload.github.com/marekdedic/imagelightbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478193,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-lightbox","javascript","jquery"],"created_at":"2024-09-24T19:54:18.466Z","updated_at":"2026-04-02T05:38:34.417Z","avatar_url":"https://github.com/marekdedic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imagelightbox\n\n[![NPM Version](https://img.shields.io/npm/v/imagelightbox?logo=npm)](https://www.npmjs.com/package/imagelightbox)\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/marekdedic/imagelightbox/CI.yml?branch=master\u0026logo=github)](https://github.com/marekdedic/imagelightbox/actions)\n[![Coveralls](https://img.shields.io/coverallsCoverage/github/marekdedic/imagelightbox?branch=master\u0026logo=coveralls)](https://coveralls.io/github/marekdedic/imagelightbox)\n[![NPM Downloads](https://img.shields.io/npm/dm/imagelightbox?logo=npm)](https://www.npmjs.com/package/imagelightbox)\n[![NPM License](https://img.shields.io/npm/l/imagelightbox)](https://github.com/marekdedic/imagelightbox/blob/master/LICENSE)\n[![RelativeCI native bundle](https://badges.relative-ci.com/badges/mqvYqDg4xPM2gcxviDAG?branch=master\u0026style=flat)](https://app.relative-ci.com/projects/mqvYqDg4xPM2gcxviDAG)\n[![RelativeCI jquery bundle](https://badges.relative-ci.com/badges/99MW2QOdJusoWoLHsKkr?branch=master\u0026style=flat)](https://app.relative-ci.com/projects/99MW2QOdJusoWoLHsKkr)\n\nImage Lightbox, Responsive and Touch‑friendly.\n\nThis is a fork of the lightbox plugin created by [Osvaldas Valutis](http://osvaldas.info/image-lightbox-responsive-touch-friendly/).\n\nSee most of the available options at the [Demo Page](http://marekdedic.github.io/imagelightbox/)\n\n## Requirements and Browser support\n\n* All major desktop browsers and versions as well as mobile browsers on Android and iOS.\n\n## How to install\n\n```sh\n$ npm install --save imagelightbox\n```\n\nAfter that include the `dist/imagelightbox.css` and `dist/imagelightbox.umd.cjs` files. Alternatively, you can use the `dist/imagelightbox.js` file if you are using ES6 modules.\n\nIf you prefer to use jQuery, there are also jQuery versions available in `dist/imagelightbox.jquery.umd.cjs` or `dist/imagelightbox.jquery.js`. These mostly adapt the interface of the library to work with jQuery types and emit jQuery events. These are here mostly for legacy reasons and their use is discouraged.\n\n## How to use\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003clink rel=\"stylesheet\" href=\"node_modules/imagelightbox/dist/imagelightbox.css\"\u003e\n        \u003cscript src=\"node_modules/imagelightbox/dist/imagelightbox.umd.cjs\"\u003e\u003c/script\u003e\n        \u003cscript\u003e\n            new Imagelightbox(\n                document.querySelectorAll('a[data-imagelightbox=\"xyz\"]'),\n            )\n        \u003c/script\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003ca data-imagelightbox=\"xyz\" href=\"image_1.jpg\"\u003e\n            \u003cimg src=\"thumbnail_1.jpg\" alt=\"Caption 1\"/\u003e\n        \u003c/a\u003e\n        \u003ca data-imagelightbox=\"xyz\" href=\"image_2.jpg\"\u003e\n            \u003cimg src=\"thumbnail_2.jpg\" alt=\"Caption 2\"/\u003e\n        \u003c/a\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Options\n\nYou can pass an object with options to the `ImageLightbox` constructor as a second argument. The available options are:\n\n| Option           | Type      | Default value | Description |\n| ---------------- | --------- | ------------- | --- |\n| `activity`       | `boolean` | `true`        | Whether to show an activity indicator when loading or changing the images |\n| `allowedTypes`   | `string`  | `\"\"`          | A list of allowed file types. Use an empty string to allow any type. |\n| `animationSpeed` | `number`  | `250`         | The duration (in milliseconds) of all animations |\n| `arrows`         | `boolean` | `true`        | Whether to show navigation arrows |\n| `button`         | `boolean` | `true`        | Whether to show a close button |\n| `caption`        | `boolean` | `false`       | Whether to show image captions, if they are available |\n| `enableKeyboard` | `boolean` | `true`        | Whether to enable keyboard navigation (previous/next with arrows, Escape to exit) |\n| `history`        | `boolean` | `false`       | Whether to save the current lightbox state to the browser history and add perma-linkable URLs |\n| `fullscreen`     | `boolean` | `true`        | Whether to enable the availability to show the lightbox in fullscreen mode |\n| `gutter`         | `number`  | `10`          | The minimum amount of free space (in % relative to the window size) to always keep around the image |\n| `navigation`     | `boolean` | `false`       | Whether to show a navigation (panel with clickable dots for each image) |\n| `overlay`        | `boolean` | `true`        | Whether to show a dark page overlay under the image |\n| `preloadNext`    | `boolean` | `true`        | Whether to start preloading the next image upon navigation |\n| `quitOnEnd`      | `boolean` | `true`        | Whether to close the lightbox when navigation past the last image. Alternatively, the lightbox just loops to the first image. |\n| `quitOnImgClick` | `boolean` | `false`       | Whether to close the lightbox when the image is clicked. Alternatively, the previous/next image is shown based on the position of the click. Never quits on touch devices. |\n| `quitOnDocClick` | `boolean` | `true`        | Whether to close the lightbox when clicking outside of the image. |\n\n## Opening the lightbox with a JavaScript call\n\nThe lightbox can be opened with the `open()` method call.\n\n### Example:\n\n```js\nimport { ImageLightbox } from \"imagelightbox\";\n\nconst gallery = new ImageLightbox(\n    document.querySelectorAll('a[data-imagelightbox=\"xyz\"]'),\n);\ngallery.open();\n```\n### Example: Open specific image\n\n```js\nimport { ImageLightbox } from \"imagelightbox\";\n\nconst gallery = new ImageLightbox(\n    document.querySelectorAll('a[data-imagelightbox=\"xyz\"]'),\n);\ngallery.open(\n    document.querySelectorAll('a[href=\"image_1.jpg\"]').item(0),\n);\n```\n\n## Adding captions to lightbox\n\nTo use captions, add an \"ilb2-caption\" data-attribute to the element, or as a fallback value, the `alt` attribute of the thumbnail image is used.\n\n```html\n\u003ca data-imagelightbox=\"xyz\" data-ilb2-caption=\"caption text\" href=\"image.jpg\"\u003e\n    \u003cimg src=\"thumbnail.jpg\" alt=\"Fallback caption\" /\u003e\n\u003c/a\u003e\n```\n\n## Fullscreen\n\nTo enable fullscreen, set the `fullscreen` option to true. The user can then launch the fullscreen view by pressing the Enter key.\n\n## Video\n\nVideos can be displayed in lightbox by including a `data-ilb2-video` attribute in the link. This attribute should contain a JSON-encoded list of parameters as they would be in an HTML5 video tag. For multiple video sources, the `sources` field can be added, containing a list of similarily encoded HTML5 source tags.\n\n```html\n\u003ca data-imagelightbox=\"xyz\" data-ilb2-video='{\"controls\": \"controls\", \"autoplay\": \"autoplay\", \"sources\": [{\"src\": \"images/video.m4v\", \"type\": \"video/mp4\"}], \"width\": 1920, \"height\": 1080}'\u003e\n    \u003cimg src=\"images/video-thumb.jpg\"\u003e\n\u003c/a\u003e\n```\n\n## Custom events\n\nThe lightbox dispatches custom events upon opening, closing, image loading, and when either the next or previous image is requested (beware that these are not dispatched when the image is changed in other ways, such as the navigation panel).\nThese events are, respectively, `ilb:start`, `ilb:quit`, `ilb:loaded`, `ilb:next`, and `ilb:previous`.\n\nUsage example:\n\n```js\ndocument.addEventListener(\"ilb:start\", (e) =\u003e {\n    console.log(\"The lightbox was started with element: \");\n    console.log(e.target);\n});\ndocument.addEventListener(\"ilb:quit\", () =\u003e {\n    console.log(\"The lightbox was closed.\");\n});\ndocument.addEventListener(\"ilb:loaded\", () =\u003e {\n    console.log(\"A new image was loaded\");\n});\ndocument.addEventListener(\"ilb:previous\", (e) =\u003e {\n    console.log(\"Previous image: \");\n    console.log(e.target);\n});\ndocument.addEventListener(\"ilb:next\", (e) =\u003e {\n    console.log(\"Next image: \");\n    console.log(e.target);\n});\ndocument.addEventListener(\"ilb:error\", (e) =\u003e {\n    console.log(\"Error loading image\");\n    console.log(e.detail.target);\n});\n```\n## Using multiple lighboxes\n\nImagelightbox supports multiple independent image sets on the same page, each initialized indepently.\n\nFor example:\n\n```html\n\u003ca data-imagelightbox=\"a\" href=\"image_1.jpg\"\u003e\n    \u003cimg src=\"thumbnail_1.jpg\" alt=\"caption\"/\u003e\n\u003c/a\u003e\n\u003ca data-imagelightbox=\"a\" href=\"image_2.jpg\"\u003e\n    \u003cimg src=\"thumbnail_2.jpg\" alt=\"caption\"/\u003e\n\u003c/a\u003e\n\n\u003ca data-imagelightbox=\"b\" href=\"image_3.jpg\"\u003e\n    \u003cimg src=\"thumbnail_3.jpg\" alt=\"caption\"/\u003e\n\u003c/a\u003e\n\u003ca data-imagelightbox=\"b\" href=\"image_4.jpg\"\u003e\n    \u003cimg src=\"thumbnail_4.jpg\" alt=\"caption\"/\u003e\n\u003c/a\u003e\n```\nWhen the user clicks any of the thumbnails with a data-imagelightbox value of \"a\", only those images will appear in the \nlightbox. The same is true when clicking an image with data-imagelightbox value of \"b\" and any other.\n\n## Adding images dynamically to lightbox\n\nMore images can be added to the lightbox after it has been initialized.\n\n### Example:\n\n```js\nimport { ImageLightbox } from \"imagelightbox\";\n\nconst lightbox = new ImageLightbox(\n    document.querySelectorAll('a[data-imagelightbox=\"xyz\"]'),\n)\nconst newAnchor = document.createElement(\"a\");\nnewAnchor.dataset.imagelightbox = \"xyz\";\nnewAnchor.href = \"images/demo4.jpg\";\n\nconst newImg = document.createElement(\"img\");\nnewImg.src = \"images/thumb4.jpg\";\nnewAnchor.appendChild(newImg);\n\nlightbox.addImages([newAnchor]);\n```\n\n## Permalinks \u0026 History\n\nWhen history is enabled, upon clicking on an image, the query field `imageLightboxIndex=X` is added to the URL, where `X` is the index of the currently opened image. This means that such an URL can be copied and used as a permanent link to that particular image. When somebody opens the URL, the lightbox will be open on the image in question. This also works with multiple sets, where an aditional query field `imageLightboxSet=Y` is used to distinguish between the sets in one page.\n\nIn some cases, this could lead to a different image being opened, for example if new images have been added to the set, or if the order of the images has changed. To solve this issue, whenever the HTML attribute `data-ilb2-id=X` is present in the image tag, this value is used instead of the image index (this means this id has to be different for each image and mustn't change over time to keep links working).\n\n### Example:\n\n```html\n\u003ca href=\"image1.jpg\" data-imagelightbox=\"images\" data-ilb2-id=\"img1\"\u003e\n    \u003cimg src=\"thumb1.jpg\"\u003e\n\u003c/a\u003e\n\u003ca href=\"image2.jpg\" data-imagelightbox=\"images\" data-ilb2-id=\"img2\"\u003e\n    \u003cimg src=\"thumb2.jpg\"\u003e\n\u003c/a\u003e\n\u003ca href=\"image3.jpg\" data-imagelightbox=\"images\" data-ilb2-id=\"img3\"\u003e\n    \u003cimg src=\"thumb3.jpg\"\u003e\n\u003c/a\u003e\n\n\u003cscript\u003e\n    new Imagelightbox(\n        document.querySelectorAll('a[data-imagelightbox=\"images\"]'),\n        {\n            history: true,\n        },\n    )\n\u003c/script\u003e\n```\n\nIf you want a dynamically add images after the page has loaded and still support direct links to them, you have to call `lightbox.openHistory()` manually on the lightbox object yourself after adding the image.\n\n## Changelog\n\nYou can find all notable changes to this project in the [GitHub releases](https://github.com/marekdedic/imagelightbox/releases).\n\n## See also\n\nUsed by https://wordpress.org/plugins/skaut-google-drive-gallery/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarekdedic%2Fimagelightbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarekdedic%2Fimagelightbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarekdedic%2Fimagelightbox/lists"}