\n\t\n\t\t| field | \n\t\trequired | \n\t\tdescription | \n\t
\n\t\n\t\t| src | \n\t\tyes | \n\t\tfull-size image URL (equivalent to href in HTML mode) | \n\t
\n\t\n\t\t| thumb | \n\t\tno | \n\t\tthumbnail URL used in the nav strip. Falls back to src | \n\t
\n\t\n\t\t| caption | \n\t\tno | \n\t\tcaption text (equivalent to data-caption) | \n\t
\n\t\n\t\t| alt | \n\t\tno | \n\t\timage alt text. Falls back to caption, then src | \n\t
\n\t\n\t\t| id | \n\t\tno | \n\t\tidentifier used by show(id) and the URL hash. Falls back to the index | \n\t
\n\t\n\t\t| group | \n\t\tno | \n\t\tgroup name (equivalent to data-group). Falls back to \"nogroup\" | \n\t
\n\t\n\t\t| width / height | \n\t\tno | \n\t\tnatural image size in px. When given, SmartPhoto skips the preload used to measure the image | \n\t
\n
\n\n`show(indexOrId, options)` also accepts `options.group` (which group to open) and `options.trigger` (the element to animate from / return focus to). Both HTML mode and data source mode share the exact same public API, options, and events.\n\n### Option\n\n\n\t\n\t\t| variable | \n\t\tdescription | \n\t\tdefault | \n\t
\n\t\n\t\t| arrows | \n\t\tprev/next arrows | \n\t\ttrue | \n\t
\n\t\n\t\t| nav | \n\t\tnavigation images at the bottom | \n\t\ttrue | \n\t
\n\t\n\t\t| showAnimation | \n\t\tanimate the open/close transition | \n\t\ttrue | \n\t
\n\t\n\t\t| verticalGravity | \n\t\tapply device-tilt gravity to the vertical axis too (in addition to horizontal) | \n\t\tfalse | \n\t
\n\t\n\t\t| useOrientationApi | \n\t\tuse the accelerometer (deviceorientation) to move a zoomed image | \n\t\tfalse | \n\t
\n\t\n\t\t| useHistoryApi | \n\t\tupdate the URL hash (#group=…&photo=…) via the History API | \n\t\ttrue | \n\t
\n\t\n\t\t| useViewTransitionApi | \n\t\tuse the View Transition API for the open animation when the browser supports it (falls back to the clone-based animation when disabled or unsupported) | \n\t\ttrue | \n\t
\n\t\n\t\t| swipeTopToClose | \n\t\tclose the viewer on an upward swipe | \n\t\tfalse | \n\t
\n\t\n\t\t| swipeBottomToClose | \n\t\tclose the viewer on a downward swipe | \n\t\ttrue | \n\t
\n\t\n\t\t| pinchToClose | \n\t\tclose the viewer when the photo is pinched in clearly below its base scale (fit/fill) | \n\t\ttrue | \n\t
\n\t\n\t\t| swipeOffset | \n\t\tminimum swipe distance (px) to trigger navigation/close | \n\t\t100 | \n\t
\n\t\n\t\t| swipeVelocity | \n\t\tminimum swipe speed (px/ms) that triggers navigation even below swipeOffset (fast flicks) | \n\t\t0.5 | \n\t
\n\t\n\t\t| headerHeight | \n\t\theight (px) reserved for the header when fitting images | \n\t\t60 | \n\t
\n\t\n\t\t| footerHeight | \n\t\theight (px) reserved for the footer when fitting images | \n\t\t60 | \n\t
\n\t\n\t\t| resizeStyle | \n\t\tresize images to fill/fit on the screen | \n\t\t'fit' | \n\t
\n\t\n\t\t| animationSpeed | \n\t\tanimation speed (ms) when switching/opening/closing images | \n\t\t300 | \n\t
\n\t\n\t\t| forceInterval | \n\t\tfrequency (ms) to apply force to images | \n\t\t10 | \n\t
\n\t\n\t\t| registance | \n\t\tfriction applied to the inertia scroll of a zoomed image | \n\t\t0.5 | \n\t
\n\t\n\t\t| loadOffset | \n\t\tnumber of neighboring slides to preload around the current one | \n\t\t2 | \n\t
\n\t\n\t\t| lazyAttribute | \n\t\tattribute read for a lazy-loaded thumbnail (HTML mode only) | \n\t\t'data-src' | \n\t
\n\t\n\t\t| classNames | \n\t\toverride any of the generated CSS class names | \n\t\tsee source | \n\t
\n\t\n\t\t| message | \n\t\toverride screen-reader text (gotoNextImage / gotoPrevImage / closeDialog / carouselLabel) | \n\t\tsee source | \n\t
\n
\n\n#### Hide parts\n```js\ndocument.addEventListener('DOMContentLoaded',function(){\n new SmartPhoto(\".js-smartphoto\",{\n arrows: false,\n nav: false\n });\n});\n```\n\n#### Fit/Fill Option\n\nYou can choose if you want to scale images to fit/fill\n\n```js\ndocument.addEventListener('DOMContentLoaded',function(){\n new SmartPhoto(\".js-smartphoto\",{\n resizeStyle: 'fit'\n });\n});\n```\n\n### Event\n\n```js\n// when the modal opened\nphoto.on('open',function(){\n console.log('open');\n});\n// when the modal closed\nphoto.on('close',function(){\n console.log('close');\n});\n// when all images are loaded\nphoto.on('loadall',function(){\n console.log('loadall');\n});\n// when photo is changed\nphoto.on('change',function(){\n console.log('change');\n});\n// when swipe started\nphoto.on('swipestart',function(){\n console.log('swipestart');\n});\n// when swipe ended\nphoto.on('swipeend',function(){\n console.log('swipeend');\n});\n// when zoomed in\nphoto.on('zoomin',function(){\n console.log('zoomin');\n});\n// when zoomed out\nphoto.on('zoomout',function(){\n console.log('zoomout');\n});\n```\n\n### Methods\n\n\n\t\n\t\t| method | \n\t\tdescription | \n\t
\n\t\n\t\ton(event, listener) | \n\t\tsubscribe to one of the events listed above | \n\t
\n\t\n\t\tdestroy() | \n\t\tremove the viewer and all of its event listeners | \n\t
\n\t\n\t\t[Symbol.dispose]() | \n\t\tsame as destroy(). Lets a using declaration destroy the instance automatically when it goes out of scope: { using photo = new SmartPhoto(...); } | \n\t
\n\t\n\t\tgotoSlide(index) | \n\t\tgo to the slide at index within the current group | \n\t
\n\t\n\t\thidePhoto(dir?) | \n\t\tclose the viewer. dir is 'bottom' (default) or 'top' and controls the close animation direction | \n\t
\n\t\n\t\tzoomPhoto() / zoomOutPhoto() | \n\t\tzoom the current image in/out programmatically | \n\t
\n\t\n\t\taddNewItem(element) | \n\t\tregister a new <a> thumbnail element (HTML mode). Only needed when constructed with a NodeList/Element[] or otherwise not using a selector string — with a selector string, elements added later are auto-detected on click (see above) | \n\t
\n\t\n\t\tshow(indexOrId?, options?) | \n\t\topen the viewer, by index or id. Works in both HTML mode and data source mode. options.group picks the group; options.trigger sets the element to animate from and to return focus to | \n\t
\n\t\n\t\thide() | \n\t\talias of hidePhoto() | \n\t
\n\t\n\t\tnext() / prev() | \n\t\tgo to the next/previous slide. No-op at the start/end of the group | \n\t
\n\t\n\t\taddItem(slideOrElement) | \n\t\tadd a new item. Accepts a slide object (data source mode, where explicit registration is always required) or an Element (HTML mode, same caveat as addNewItem) | \n\t
\n\t\n\t\tcurrentIndex | \n\t\t(getter) the index currently displayed within its group | \n\t
\n
\n\n### CSS Custom Properties\n\n\n\t\n\t\t| property | \n\t\tdescription | \n\t\tdefault | \n\t
\n \n | --smartphoto-animation-speed | \n animation speed when switching/opening/closing images. Overridden per-instance by the animationSpeed JS option | \n 300ms | \n
\n \n | --smartphoto-animation-function | \n easing function used for animations | \n ease-out | \n
\n \n | --smartphoto-backdrop-color | \n backdrop color when viewing images | \n rgba(0, 0, 0, 1) | \n
\n \n | --smartphoto-header-color | \n header color | \n rgba(0, 0, 0, .2) | \n
\n \n | --smartphoto-arrow-top | \n vertical position of the prev/next arrows, e.g. move them off the image on narrow screens with a media query | \n 50% | \n
\n
\n\nSet these on `.smartphoto` (or `:root`) to override the defaults, no rebuild required:\n\n```css\n.smartphoto {\n --smartphoto-animation-speed: 450ms;\n --smartphoto-animation-function: ease-in-out;\n --smartphoto-backdrop-color: rgba(0, 0, 0, 0.9);\n --smartphoto-header-color: rgba(0, 0, 0, 0.4);\n}\n\n@media (max-width: 480px) {\n .smartphoto {\n --smartphoto-arrow-top: 85%;\n }\n}\n```\n\nThe bottom thumbnail nav (`.smartphoto-nav`) also reserves `env(safe-area-inset-bottom)` automatically so it isn't hidden behind the iOS home indicator/toolbar.\n\n\n## Download\n[Download ZIP](https://github.com/appleple/SmartPhoto/archive/master.zip)\n\n## Github\n[https://github.com/appleple/SmartPhoto](https://github.com/appleple/SmartPhoto)\n\n## License\nCode and documentation copyright 2017 by appleple, Inc. Code released under the [MIT License](https://github.com/appleple/SmartPhoto/blob/master/LICENSE).\n","readmeFilename":"README.md","users":{"appleple":true}}![](\"./assets/large-bear.jpg\")
\n![](\"./assets/large-camel.jpg\")
\n\n\n ![](\"./assets/large-rhinoceros.jpg\")
\n\n\n\n\n```\n\nWhen SmartPhoto is constructed with a CSS selector string (as above), clicks are handled via a single delegated listener, so elements added to the page **after** construction (e.g. by Ajax/infinite scroll) are picked up automatically just by clicking them — no need to call `addItem()`/`addNewItem()` manually. Right before a photo is opened, SmartPhoto also reconciles that photo's group against the current DOM: newly appended matching elements are added, and elements that have since been removed from the DOM are dropped from the group (remaining indices are recalculated). This auto-detection only applies to the selector-string form; when a `NodeList`/`Element[]` is passed (or in data source mode below), add/remove items explicitly via `addItem()`/`addNewItem()`.\n\nA few things to keep in mind:\n- Reconciliation only happens **right before a photo is opened** (via a click, `show()`, or hash restoration) — not continuously. If an element disappears from the DOM while the viewer is already open and you `next()`/`prev()` through the same session, that removal isn't reflected until the viewer is opened again.\n- It does not support replacing an entire container's `innerHTML` (which recreates existing elements too, as brand-new DOM nodes) — that produces duplicate items, since the old and new elements aren't recognized as the same one. Only *appending*/*removing* individual elements is supported; if you regenerate the whole container, call `destroy()` and construct a new instance instead.\n- Changing `data-group` on an element that has already been opened/registered has no effect (the group is fixed at first registration). Changing it before the element is first interacted with is picked up correctly.\n- If multiple instances are built with overlapping selectors, avoid relying on distinguishing exactly which instance handles a click for elements that could match either.\n\n### Programmatic usage (data source mode)\n\nInstead of scanning `` elements in the page, you can pass an array of slide objects directly (inspired by [yet-another-react-lightbox](https://yet-another-react-lightbox.com/)). This is useful when your images come from an API or a JS-rendered list.\n\n```js\nconst photo = new SmartPhoto([\n { src: \"/img/bear-large.jpg\", thumb: \"/img/bear.jpg\", caption: \"bear\", id: \"bear\" },\n { src: \"/img/camel-large.jpg\", thumb: \"/img/camel.jpg\", caption: \"camel\", id: \"camel\", width: 1200, height: 800 },\n]);\n\nphoto.show(0); // open by index\nphoto.show(\"camel\"); // or by id\nphoto.next();\nphoto.prev();\nphoto.hide();\nphoto.on(\"change\", () => { /* ... */ }); // same event contract as HTML mode\n```\n\nSlide fields:\n\n