@hanakla/react-lightbox


A flexible headless lightbox component for React.

Inspired by react-image-viewer-hook, reimagined as a headless component library for maximum flexibility and customization.

$3

Try it out on CodeSandbox:


Features

- Headless design - Fully customizable UI with complete control over styling
- Pinch-to-zoom support - Built-in support for touch gestures on mobile devices
- TypeScript support - Fully typed API for better developer experience
- Flexible architecture - Compose your own lightbox with provided building blocks
- Accessible - Keyboard navigation and proper ARIA attributes

Installation

``bash
npm install @hanakla/react-lightbox
`

Anatomy

Import the component and assemble its parts:

`tsx
import {
useLightbox,
Lightbox,
useLightboxState,
} from "@hanakla/react-lightbox";

function App() {
const lb = useLightbox({
LightboxComponent: MyLightbox,
});

return (
<>
Open


);
}

function MyLightbox() {
const lbContext = useLightboxState();

return (




$renderItem={(item, index) => (

{/ Your content /}

)}
/>

);
}
`

Usage

The lightbox is built with a headless architecture, giving you complete control over the UI while handling the complex interaction logic.

$3

1. Initialize the hook - Call useLightbox with your custom lightbox component
2. Trigger the lightbox - Use lb.getOnClick(item) to open the lightbox with specific content
3. Render the viewer - Place in your component tree
4. Build your UI - Compose your lightbox interface using the provided building blocks

The library separates concerns:

- useLightbox manages state and provides methods to control the lightbox
- useLightboxState provides access to the current state within your lightbox component
- Lightbox.* components are the building blocks for your custom UI

$3

`tsx
import {
useLightbox,
Lightbox,
useLightboxState,
} from "@hanakla/react-lightbox";

type ImageItem = {
kind: "image";
url: string;
};

function App() {
const lb = useLightbox({
onLoadNext: () => {
console.log("Request to load next");
},
LightboxComponent: ImageLightbox,
});

const images = [
{ kind: "image", url: "/image1.jpg" },
{ kind: "image", url: "/image2.jpg" },
{ kind: "image", url: "/image3.jpg" },
];

return (




);
}
`

API Reference

$3

`tsx
const lb = useLightbox(options);
`

Main hook to create a lightbox.

Type Parameters

| Parameter | Description |
| --------- | -------------------------------------------- |
| T | The type of items to display in the lightbox |

Parameters

| Prop | Type | Default | Description |
| ------------------- | ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| LightboxComponent | React.ComponentType> | — | Custom lightbox component to render when the lightbox is opened |
| onLoadNext | () => void | undefined | Callback invoked when the user navigates to the last item. Useful for implementing infinite scroll or lazy loading |

Returns

| Property | Type | Description |
| -------------- | -------------------------------------------- | --------------------------------------------------------------------------------------- |
| getOnClick | (item: T) => (e: React.MouseEvent) => void | Returns a click handler function that opens the lightbox with the specified item |
| LightboxView | React.ComponentType | Component that renders the lightbox modal. Should be placed once in your component tree |

---

$3

`tsx
const lbContext = useLightboxState();
`

Hook to access the current lightbox state from within lightbox components.

Type Parameters

| Parameter | Description |
| --------- | --------------------------------- |
| T | The type of items in the lightbox |

Returns

| Property | Type | Description |
| ----------------- | ------------------------- | ------------------------------------------------------------------- |
| items | T[] | Array of all items currently in the lightbox |
| currentIndex | number | Index of the currently displayed item |
| currentItem | T \| undefined | The currently displayed item, or undefined if no item is selected |
| setCurrentIndex | (index: number) => void | Function to programmatically change the current item by index |
| close | () => void | Function to close the lightbox |

---

$3

`tsx

`

Root container for the lightbox.

---

$3

`tsx

`

Container for header content like close button and actions.

---

$3

`tsx

×

`

Button to close the lightbox.

---

$3

`tsx
...} />
`

Main viewport area that displays the lightbox items.

Props

| Prop | Type | Default | Description |
| ------------- | --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| $renderItem | (item: T, index: number) => React.ReactNode | — | Render function called for each item in the lightbox. Must return a Lightbox.Item component |

---

$3

`tsx

`

Wrapper component for individual lightbox items.

Props

| Prop | Type | Default | Description |
| -------- | -------- | ------- | --------------------------------------------------------------------------------- |
| $index | number | — | Index of the item being rendered. Used to track which item is currently displayed |

---

$3

`tsx



`

Helper component that adds pinch-to-zoom and pan gestures to its children.

Props

| Prop | Type | Default | Description |
| ---------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------- |
| onRequestClose | () => void | undefined | Callback invoked when the user performs a close gesture. Typically connected to lbContext.close()` |

Features

- Pinch-to-zoom gesture support on touch devices
- Pan gesture when zoomed in
- Double-tap to zoom
- Smooth animations and transitions

---

Credits

This library is based on react-image-viewer-hook by rkusa, reimagined as a headless component library for maximum flexibility and customization.

Original work Copyright (c) Markus Ast (rkusa)

License

MIT

Copyright (c) [Your Name/Organization]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.