# react-ikusi

> React photo displaying component library

Latest version **4.0.0** (published 2025-02-06) · ISC license · 0 weekly downloads

## Install

```sh
npm install react-ikusi
pnpm add react-ikusi
yarn add react-ikusi
bun add react-ikusi
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-02-06 |
| First published | 2019-12-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 328.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Ane Diaz de Tuesta |
| Maintainers | anediaz |
| Keywords | react, typescript, masonry, css, flexbox, responsive, gallery, pictures |

## Links

- npm: https://www.npmjs.com/package/react-ikusi
- Repository: https://github.com/anediaz/react-ikusi
- Homepage: https://anediaz.github.io/react-ikusi
- Issues: https://github.com/anediaz/react-ikusi/issues
- npm.io page: https://npm.io/package/react-ikusi

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2025-02-06
- 3.1.7 — 2025-02-03
- 3.1.6 — 2024-07-04
- 3.1.5 — 2024-06-15
- 3.1.4 — 2024-06-15
- 3.1.3 — 2023-12-17
- 3.1.2 — 2023-12-05
- 3.1.1 — 2023-12-05
- 3.1.0 — 2023-11-21
- 3.0.2 — 2023-11-11
- 2.4.0 — 2023-04-23
- 2.3.0 — 2021-05-02
- 2.1.3 — 2021-04-26
- 2.1.2 — 2021-04-26
- 2.1.0 — 2021-04-26
- … 11 more at https://npm.io/package/react-ikusi/versions

## README

#

<img src="https://live.staticflickr.com//65535//49596034956_0cd35c0db4_o.png" />

<a href="https://www.npmjs.com/package/react-ikusi">See on NPM</a> &nbsp;&nbsp;[![See on NPM][npm-image]][storybook-url]

<a href="https://anediaz.github.io/react-ikusi/?path=/docs/react-ikusi--docs">See on Storybook</a> &nbsp;&nbsp;[![See on Storybook][storybook-image]][storybook-url]

#

[npm-url]: https://www.npmjs.com/package/react-ikusi
[npm-image]: https://github.com/anediaz/react-ikusi/assets/17216937/1f2391bf-fae5-4a59-af03-74b9918df37b
[storybook-url]: https://anediaz.github.io/react-ikusi/?path=/docs/react-ikusi--docs
[storybook-image]: https://github.com/anediaz/react-ikusi/assets/17216937/48dfea53-4d6c-4d30-b2bf-6670ad9755af

A lightweight React responsive masonry component to display images.
Built with CSS Flexbox:
-   Supports row direction layout
-   Configurable for different screen sizes
-   Responsive
-   Combined with a lightbox to display each image

:bulb: The word **_ikusi_** from the package name react-ikusi means **_see_** in Basque language.
Click [here](https://en.wikipedia.org/wiki/Basque_language) for more information.

## Getting started
You can download `react-ikusi` from the NPM registry via `npm` or
`yarn`

```shell
yarn add react-ikusi
npm install react-ikusi --save
```
## Demo
See <a href="https://anediaz.github.io/react-ikusi/?path=/docs/react-ikusi--docs">react-ikusi Storybook</a>

## Example

Customizable configurations for different screen sizes
| | |
| ---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------: |
| <img src="https://live.staticflickr.com//65535//49596351782_fbf41d588f_n.jpg" alt="example"/> | <img src="https://live.staticflickr.com//65535//49595603383_d76c9a0d9a_n.png" alt="example"/> |

## Usage
Here's the minimal setup example:

```jsx
import Gallery from 'react-ikusi';

const photos = [
    {
        id: 'id-11111',
        title: 'Example image 1',
        src: 'http://example.com/example/img1.jpg',
        width: 4,
        height: 3,
    },
    {
        id: 'id-0033',
        title: 'Example image 2',
        src: 'http://example.com/example/img2.jpg',
        width: 1,
        height: 1,
    },
];


<Gallery photos={photos} />;
```

With additional props

```jsx
const configurations = [
    { maxWidth: 340, cols: 2, margin: 1 },
    { maxWidth: 1024, cols: 3, margin: 1 },
    { minWidth: 1025, cols: 5, margin: 2 },
  ];

const handleClick: (photo) => {
    // do something...
}

const lightboxProps = {
    isEnabled: true,
    onClose?: () => {
        // do something...
    },
    onNext?: (photo) => {
        // do something...
    },     
    onPrev?: (photo) => {
        // do something...
    }
};

<Gallery photos={photos} configurations={configurations} onClickPhoto={handleClick} lightboxProps={lightboxProps} />;
```

## Props

###

<ins>**Gallery**</ins>

| Name           | Description                                                                | Type                 | Required |
| -------------- | -------------------------------------------------------------------------- | -------------------- | -------- |
| photos         | An array of photos to render                                               | PhotoProps[]         | true     |
| configurations | Configurations to use for different screen sizes                           | ConfigurationProps[] | true     |
| onClickPhoto   | Click photo handler                                                        | function             | false    |
| lightboxProps  | Props for lightbox rendering                                               | LightboxProps        | false    |
| withLightbox   | Used to enable Lightbox rendering. @deprecated: Use lightboxProps instead  | boolean              | false    |

\
<ins>**PhotoProps**</ins>

| Name   | Description                                                   | Type   | Required |
| ------ | ------------------------------------------------------------- | ------ | -------- |
| id     | Unique identifier of the photo                                | string | true     |
| src    | Url source of the photo                                       | string | true     |
| title  | Title of the photo                                            | string | false    |
| width  | Original width of the photo in pixels                         | number | true     |
| height | Original height of the photo in pixels                        | number | true     |
| bigSrc | Url source of the photo in big size (for Lightbox displaying) | string | false    |

\
<ins>**ConfigurationProps**</ins>

It contains data for photo rendering in different screen sizes.

It determines the number of elements to be displayed per row and their margin.

| Name     | Description                                      | Type   | Required |
| -------- | ------------------------------------------------ | ------ | -------- |
| cols     | Number of elements per row                       | number | true     |
| margin   | Space around each element of the Gallery (px)    | number | true     |
| minWidth | Minimum width for the current configuration (px) | number | false    |
| maxWidth | Maximum width for the current configuration (px) | number | false    |

\
<ins>**LightboxProps**</ins>

Additional props for lightbox rendering.

| Name      | Description                             | Type     | Required |
| --------- | --------------------------------------- | -------- | -------- |
| isEnabled | Whether lightbox is present in Gallery  | boolean  | true     |
| onClose   | Close lightbox handler                  | function | false    |
| onPrev    | Click on previous button handler        | function | false    |
| onNext    | Click on previous button handler        | function | false    |

\
\
An example of Gallery layout :

<img src="https://live.staticflickr.com//65535//49595136583_f326bc8ef5_n.jpg" width="45%" alt="layout"/> <img src="https://live.staticflickr.com//65535//49595636006_ce5a2e029a_n.jpg" width="45%" alt="layout"/>

<img src="https://live.staticflickr.com//65535//49595635976_7d941dac9e_n.jpg" width="45%" alt="layout"/> <img src="https://live.staticflickr.com/65535/49595136513_235b10c43e_n.jpg" width="45%" alt="layout"/>

---
_Source: https://npm.io/package/react-ikusi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._