\n\nLightweight React lightbox component. This is a trimmed-down version of the\n[yet-another-react-lightbox](https://github.com/igordanchenko/yet-another-react-lightbox)\nthat provides essential lightbox features and slick UX with a really modest\nbundle size.\n\n## Overview\n\n- **Lightweight:** around 5 kB minified + compressed, with no runtime\n dependencies\n- **Universal input:** keyboard, mouse, touchpad, and touchscreen navigation\n- **Zoom:** pinch, wheel, double-tap, and keyboard, with a configurable zoom\n limit\n- **Transitions:** built-in `fade`/`slide`/`none`, with custom effects via CSS\n- **Preloading:** configurable preload window keeps memory and bandwidth in\n check\n- **Responsive images:** built-in `srcSet` support for automatic resolution\n switching\n- **Fully customizable:** override any element via `slots`, `render` props, and\n exported hooks, or add custom slide types\n- **TypeScript-first:** extend `slides` and `labels` via declaration merging,\n with full autocomplete support\n\n\n\n## Documentation\n\n[https://github.com/igordanchenko/yet-another-react-lightbox-lite](https://github.com/igordanchenko/yet-another-react-lightbox-lite)\n\n## Examples\n\n- Live demo -\n [https://stackblitz.com/edit/yet-another-react-lightbox-lite](https://stackblitz.com/edit/yet-another-react-lightbox-lite?file=src%2FApp.tsx)\n- Examples -\n [https://stackblitz.com/edit/yet-another-react-lightbox-lite-examples](https://stackblitz.com/edit/yet-another-react-lightbox-lite-examples?file=src%2FApp.tsx)\n\n## Changelog\n\n[https://github.com/igordanchenko/yet-another-react-lightbox-lite/releases](https://github.com/igordanchenko/yet-another-react-lightbox-lite/releases)\n\n## Requirements\n\n- React 18+\n- Node 22+\n- modern ESM-compatible bundler\n\n## Installation\n\n```shell\nnpm install yet-another-react-lightbox-lite\n```\n\n## Minimal Setup Example\n\n```tsx\nimport { useState } from \"react\";\nimport Lightbox from \"yet-another-react-lightbox-lite\";\nimport \"yet-another-react-lightbox-lite/styles.css\";\n\nexport default function App() {\n const [index, setIndex] = useState();\n\n return (\n <>\n \n\n \n \n );\n}\n```\n\n## Responsive Images\n\nTo utilize responsive images with automatic resolution switching, provide\n`srcset` images in the slide `srcSet` array.\n\n```tsx\n\n```\n\n## Next.js Image\n\nIf your project is based on [Next.js](https://nextjs.org/), you may want to take\nadvantage of the\n[next/image](https://nextjs.org/docs/pages/api-reference/components/image)\ncomponent. The `next/image` component provides a more efficient way to handle\nimages in your Next.js project. You can replace the standard `` element\nwith `next/image` using the following `render.slide` render function.\n\n```tsx\ndeclare module \"yet-another-react-lightbox-lite\" {\n interface SlideImage {\n blurDataURL?: string;\n }\n}\n```\n\n```tsx\n {\n const width =\n slide.width && slide.height\n ? Math.round(\n Math.min(rect.width, (rect.height / slide.height) * slide.width),\n )\n : rect.width;\n\n const height =\n slide.width && slide.height\n ? Math.round(\n Math.min(rect.height, (rect.width / slide.width) * slide.height),\n )\n : rect.height;\n\n return (\n \n );\n },\n }}\n // ...\n/>\n```\n\n## API\n\nYet Another React Lightbox Lite comes with a CSS stylesheet that needs to be\nimported in your app.\n\n```tsx\nimport \"yet-another-react-lightbox-lite/styles.css\";\n```\n\nThe lightbox component accepts the following props.\n\n### slides\n\nType: `Slide[]`\n\nAn array of slides to display in the lightbox. This prop is required. By\ndefault, the lightbox supports only image slides. You can add support for custom\nslides through a custom render function (see example below).\n\nImage slide props:\n\n- `src` — image source (required)\n- `alt` — image `alt` attribute\n- `width` — image width in pixels\n- `height` — image height in pixels\n- `srcSet` — alternative images for responsive resolution switching (see\n [Responsive Images](#responsive-images))\n\n### index\n\nType: `number | undefined`\n\nCurrent slide index. This prop is required.\n\n### setIndex\n\nType: `(index: number | undefined) => void`\n\nA callback to update current slide index state. This prop is required.\n\nSetting `index` to `undefined` unmounts the lightbox immediately, skipping the\nexit transition. To close with the transition (same as the Escape key or the\ntoolbar Close button), call `close()` from the\n[imperative handle](#imperative-handle) or [`useController`](#usecontroller)\ninstead.\n\n### labels\n\nType: `object`\n\nCustom UI labels / translations.\n\n```tsx\n\n```\n\nThe `labels` prop accepts the built-in keys (`Previous`, `Next`, `Close`,\n`Lightbox`, `Carousel`, `Slide`, `Photo gallery`, `{index} of {total}`) and any\ncustom string keys — useful for translating\n[custom `IconButton` labels](#iconbutton). To get autocomplete for your custom\nkeys in both [`IconButton.label`](#iconbutton) and the `labels` prop,\ndeclaration-merge them into the exported `LabelRegistry` interface:\n\n```ts\ndeclare module \"yet-another-react-lightbox-lite\" {\n interface LabelRegistry {\n Download?: string;\n }\n}\n```\n\n### toolbar\n\nType: `object`\n\nToolbar settings.\n\n- `buttons` — custom toolbar buttons (type: `ReactNode[]`). Each button should\n have a unique `key` attribute. Use the exported [`IconButton`](#iconbutton)\n component for buttons that match the built-in styling.\n- `fixed` — if `true`, the toolbar is positioned statically above the carousel\n\nUsage example:\n\n```tsx\n {\n // ...\n }}\n />,\n ],\n }}\n // ...\n/>\n```\n\n### carousel\n\nType: `object`\n\nCarousel settings.\n\n- `preload` — the lightbox preloads `(2 * preload + 1)` slides (default: `2`)\n- `transition` — slide transition effect, `\"fade\"` (default), `\"slide\"`, or\n `\"none\"` (see [Slide Transitions](#slide-transitions))\n- `infinite` — if `true`, the carousel wraps around from the last slide to the\n first and vice versa (default: `false`). In this mode, the controlled `index`\n value drifts beyond `[0, slides.length)` to encode navigation direction; treat\n it as opaque navigation state. If you need to persist which slide is showing\n (e.g., to URL params), persist a stable slide identifier and resolve it back\n to an in-range index on load — don't round-trip the drifted index through\n normalization, as that would break wrap animations and the preload window\n during a live session.\n\nUsage example:\n\n```tsx\n\n```\n\nEnable infinite (wrapping) navigation:\n\n```tsx\n\n```\n\nTo customize image slide attributes (e.g., `crossOrigin`, `loading`, `lang`),\nuse the [`slots.image`](#slots) prop.\n\n### controller\n\nType: `object`\n\nController settings.\n\n- `closeOnPullUp` — if `true`, close the lightbox on pull-up gesture (default:\n `true`)\n- `closeOnPullDown` — if `true`, close the lightbox on pull-down gesture\n (default: `true`)\n- `closeOnBackdropClick` — if `true`, close the lightbox when the backdrop is\n clicked (default: `true`)\n- `closeOnEscape` — if `true`, close the lightbox on Escape key press (default:\n `true`)\n\nUsage example:\n\n```tsx\n\n```\n\n### render\n\nType: `object`\n\nAn object providing custom render functions.\n\n```tsx\n (\n \n ),\n slideHeader: ({ slide, rect, zoom, current, slideIndex }) => (\n \n ),\n slideFooter: ({ slide, rect, zoom, current, slideIndex }) => (\n \n ),\n controls: () => ,\n iconPrev: () => ,\n iconNext: () => ,\n iconClose: () => ,\n }}\n // ...\n/>\n```\n\n#### slide: ({ slide, rect, zoom, current, slideIndex }) => ReactNode\n\nRender custom slide type, or override the default image slide implementation.\n\nParameters:\n\n- `slide` — slide object (type: `Slide`)\n- `rect` — slide rect size (type: `Rect`)\n- `zoom` — current zoom level (type: `number`)\n- `current` — if `true`, the slide is the current slide in the viewport (type:\n `boolean`)\n- `slideIndex` — index of this slide within the `slides` array, always in\n `[0, slides.length)` (type: `number`). Not the same as the controlled `index`\n prop — for preloaded neighbors it points to a neighbor, and in `infinite` mode\n the controlled `index` may drift outside `[0, slides.length)` while\n `slideIndex` stays wrapped.\n\n#### slideHeader: ({ slide, rect, zoom, current, slideIndex }) => ReactNode\n\nRender custom elements above each slide.\n\n#### slideFooter: ({ slide, rect, zoom, current, slideIndex }) => ReactNode\n\nRender custom elements below or over each slide. By default, the content is\nrendered right under the slide. Alternatively, you can use\n`position: \"absolute\"` to position the extra elements relative to the slide.\n\nFor example, you can use the `slideFooter` render function to add slides\ndescriptions (see [Custom Slide Attributes](#custom-slide-attributes)).\n\n```tsx\n (\n
{slide.description}
\n ),\n }}\n // ...\n/>\n```\n\n#### controls: () => ReactNode\n\nRender custom controls or additional elements in the lightbox (use absolute\npositioning).\n\nFor example, you can use the `render.controls` render function to implement a\nslides counter.\n\n```tsx\nconst slides = [\n { src: \"/image1.jpg\" },\n { src: \"/image2.jpg\" },\n { src: \"/image3.jpg\" },\n];\n\nconst [index, setIndex] = useState();\n\n// Fold the controlled index back into [0, slides.length) — needed because\n// `infinite` mode lets `index` drift outside that range.\nconst normalizeIndex = (i: number) =>\n ((i % slides.length) + slides.length) % slides.length;\n```\n\n```tsx\n\n index !== undefined && (\n
\n {`${normalizeIndex(index) + 1} of ${slides.length}`}\n
\n ),\n }}\n/>\n```\n\n#### iconPrev: () => ReactNode\n\nRender custom `Previous` icon.\n\n#### iconNext: () => ReactNode\n\nRender custom `Next` icon.\n\n#### iconClose: () => ReactNode\n\nRender custom `Close` icon.\n\n### slots\n\nType: `object`\n\nCustomization slots let you override HTML attributes on the lightbox elements —\n`className`, `style` (including `--yarll__*` CSS variables), `data-*`, `aria-*`,\n`crossOrigin`, etc.\n\nSupported slots:\n\n- `portal` — lightbox portal (root) `
![\"\"](\".github/assets/logo.webp\"){kind=logo}
\n