Tất cả thư viện
v1.2.0

@hwagfu/images

Thư viện ảnh dạng lưới kèm lightbox — dùng cho React, Next.js hoặc HTML thuần.

Component React hiển thị danh sách ảnh dạng lưới tự sắp xếp theo số lượng, kèm lightbox tích hợp. Hỗ trợ tối ưu ảnh Next.js qua renderImage và có sẵn bản Web Component <multiple-image> cho HTML thuần.

Playground

Chỉnh các thông số bên phải để xem component thay đổi trực tiếp.

blurBackground

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

Cài đặt

bash
npm install @hwagfu/images
tsx
import { MultipleImage } from "@hwagfu/images";

Tính năng

  • Lưới ảnh tự sắp xếp theo số lượng (2–5 ảnh).
  • Lightbox tích hợp, có tùy chọn làm mờ nền.
  • Tùy chỉnh bo góc và tỉ lệ khung ảnh.
  • Hỗ trợ Next.js Image qua prop renderImage.
  • Có bản Web Component <multiple-image> cho HTML thuần.

Cách dùng

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>

Thuộc tính (Props)

TênKiểuMặc địnhMô tả
imgList{ src: string; alt?: string }[]—Danh sách ảnh cần hiển thị (bắt buộc).
blurBackgroundbooleanfalseLàm mờ nền trang phía sau lightbox.
radius"none" | "md" | "lg" | "xl""none"Độ bo góc của ảnh.
ratio"square" | "landscape" | "portrait""landscape"Tỉ lệ khung ảnh.
renderImage(props: RenderImageProps) => ReactNode—Hàm render ảnh tùy chỉnh (dùng cho next/image).
classNamestring—Class Tailwind cho lớp bọc lưới.

Lưu ý

  • Component có "use client" vì lightbox cần tương tác phía client; vẫn pre-render được trên Next.js App Router.
  • Với Web Component, luôn dùng thẻ đóng tường minh: <image-item ...></image-item>.