v1.2.0

@hwagfu/images

A grid image gallery with a built-in lightbox — for React, Next.js or plain HTML.

A React component that displays a list of images in a self-arranging grid with a built-in lightbox. Supports Next.js image optimization via renderImage and ships a <multiple-image> Web Component for plain HTML.

Playground

Tweak the controls on the right to see the component update live.

images3radius

blurBackground

Bấm vào một ảnh để mở lightbox · Click an image to open the lightbox.

Installation

bash

npm install @hwagfu/images

tsx

import { MultipleImage } from "@hwagfu/images";

Features

A self-arranging grid layout for 2–5 images.
Built-in lightbox with an optional background blur.
Customizable corner radius and aspect ratio.
Next.js Image support via the renderImage prop.
Ships a <multiple-image> Web Component for plain HTML.

Usage

React

tsx

import { MultipleImage } from "@hwagfu/images";

const images = [
  { src: "/images/1.jpg", alt: "Image 1" },
  { src: "/images/2.jpg", alt: "Image 2" },
  { src: "/images/3.jpg", alt: "Image 3" },
];

export function Example() {
  return (
    <MultipleImage
      imgList={images}
      blurBackground
      radius="xl"
      ratio="landscape"
    />
  );
}

Next.js (next/image)

tsx

"use client";

import Image from "next/image";
import { MultipleImage, type RenderImageProps } from "@hwagfu/images";

function renderNextImage({ image, index, className, style, sizes, priority }: RenderImageProps) {
  return (
    <Image
      src={image.src}
      alt={image.alt ?? `image-${index + 1}`}
      fill
      sizes={sizes}
      priority={priority}
      className={className}
      style={style}
    />
  );
}

<MultipleImage imgList={images} radius="xl" ratio="landscape" renderImage={renderNextImage} />

HTML (Web Component)

html

<script type="module" src="https://cdn.jsdelivr.net/npm/@hwagfu/images/dist/web-component.js"></script>

<multiple-image radius="xl" ratio="landscape" blur-background>
  <image-item src="/photo-1.jpg" alt="Mountain"></image-item>
  <image-item src="/photo-2.jpg" alt="Forest"></image-item>
  <image-item src="/photo-3.jpg" alt="City"></image-item>
</multiple-image>

Props

Name	Type	Default	Description
imgList	{ src: string; alt?: string }[]	—	The array of images to display (required).
blurBackground	boolean	false	Blur the page behind the lightbox.
radius	"none" \| "md" \| "lg" \| "xl"	"none"	Corner radius of the images.
ratio	"square" \| "landscape" \| "portrait"	"landscape"	Aspect ratio of the tiles.
renderImage	(props: RenderImageProps) => ReactNode	—	Custom image renderer (e.g. for next/image).
className	string	—	Tailwind classes for the grid wrapper.

Notes

The component is marked "use client" because the lightbox needs client interaction; it still pre-renders on the Next.js App Router.
For the Web Component, always use an explicit closing tag: <image-item ...></image-item>.