Creative Gallery React 🎨

Creative Gallery React là một thư viện UI chuyên biệt, cung cấp các giao diện hiển thị hình ảnh và video độc đáo, sáng tạo nhất. Bộ thư viện được xây dựng sẵn các hiệu ứng chuyển động mượt mà và tính năng phóng to ảnh (Lightbox) ưu việt, giúp tiết kiệm hàng chục giờ phát triển các trang trưng bày sản phẩm, dự án bất động sản, hay portfolio cá nhân.

1. Hướng dẫn cài đặt

Để bắt đầu, bạn cần cài đặt thư viện chính cùng các package phụ thuộc (Swiper cho logic xoay ảnh và Lucide React cho bộ icon).

Chạy lệnh sau trong terminal của dự án:

Với npm:

npm install creative-gallery-react swiper lucide-react

Với yarn:

yarn add creative-gallery-react swiper lucide-react

⚠️ Cấu hình Tailwind CSS (Rất quan trọng)

Thư viện này sử dụng Tailwind CSS V4. Vì không đi kèm file .css build sẵn tĩnh, bạn phải yêu cầu Tailwind quét các component của thư viện để sinh ra style.

Trong file CSS chính của ứng dụng (thường là app.css hoặc index.css), thêm dòng @source trỏ vào thư viện:

@import "tailwindcss";
@source "../node_modules/creative-gallery-react";

/* Các style custom của bạn bên dưới... */

⚠️ Import CSS của Swiper (Rất quan trọng)

Thư viện sử dụng Swiper cho Lightbox. Bạn bắt buộc phải import file css của thư viện vào file gốc dự án (thường là main.jsx hoặc App.jsx):

import 'creative-gallery-react/style.css';

2. API Reference (Danh sách tham số)

Mọi component layout trong thư viện đều được thiết kế để nhận chung một cấu trúc dữ liệu. Điểm giao tiếp chính là prop images.

| Prop | Kiểu dữ liệu | Bắt buộc | Mô tả | | :--- | :--- | :--- | :--- | | images | Array<Object> | Có | Mảng chứa danh sách các đối tượng dữ liệu hình ảnh. Đây là nguồn dữ liệu duy nhất mà component cần để vẽ giao diện. |

Cấu trúc dữ liệu của từng tấm ảnh

Mỗi phần tử bên trong mảng images cần tuân thủ cấu trúc object sau:

| Thuộc tính | Kiểu dữ liệu | Bắt buộc | Mô tả chi tiết | | :--- | :--- | :--- | :--- | | id | Number | String | Có | Định danh duy nhất cho tấm ảnh (được dùng làm key khi render). | | url | String | Có | Đường dẫn ảnh gốc chất lượng cao (hiển thị khi mở Lightbox). | | thumbnailUrl | String | Không | Đường dẫn ảnh thu nhỏ giúp tối ưu tốc độ load. Nếu bỏ trống, component sẽ dùng url. | | title | String | Không | Dòng tiêu đề ngắn (Xuất hiện khi di chuột lên ảnh hoặc bên trong Lightbox). | | description | String | Không | Đoạn văn bản mô tả chi tiết cho ảnh. |

3. Danh sách Components & Layouts

Thư viện export ra các component sau để bạn thoải mái import và sử dụng. Tất cả các layout dưới đây đều đã tự động tích hợp sẵn tính năng "Click vào ảnh để phóng to (Lightbox)".

import { 
  MasonryLayout, 
  SpotlightLayout, 
  MagazineLayout, 
  Carousel3DLayout, 
  FocusImage, 
  AccordionGallery, 
  Cylinder3DGallery,
  PopUpMedia 
} from 'creative-gallery-react';

• MasonryLayout: Giao diện lưới bất đối xứng (chuẩn Pinterest). Tự động sắp xếp khoảng trống, cực kỳ mượt mà.
• SpotlightLayout: Phân bổ mảng khối to/nhỏ đan xen, giúp điều hướng mắt người xem vào ảnh trọng tâm.
• MagazineLayout: Bố cục tĩnh chặt chẽ như trang bìa tạp chí (Cần 13+ tấm ảnh).
• Carousel3DLayout: Vòng xoay 3D nằm ngang. Ảnh rìa làm mờ, ảnh trung tâm phóng to nổi bật.
• FocusImage: Thiết kế phân cấp với 1 khung ảnh khổng lồ ở trên và dải ảnh nhỏ xếp dưới.
• AccordionGallery: Lấy cảm hứng từ đàn Accordion. Hover vào ảnh nào, ảnh đó tự dãn rộng ra cực kỳ uyển chuyển.
• Cylinder3DGallery: Khối trụ tròn 3D bao quanh không gian. Kéo thả chuột để xoay lướt xem ảnh.

4. Component Cốt lõi: PopUpMedia (Lightbox)

Bạn hoàn toàn có thể tự xây dựng layout của riêng bạn và gọi PopUpMedia lên để tái sử dụng logic Lightbox vuốt trượt siêu xịn của thư viện. PopUpMedia sử dụng React Portal để tránh lỗi CSS overflow.

| Prop | Kiểu dữ liệu | Bắt buộc | Mô tả chi tiết | | :--- | :--- | :--- | :--- | | images | Array<Object> | Có | Cùng cấu trúc dữ liệu như ở Phần 2. | | setShow | Function | Có | Hàm setter (Ví dụ: setShow(false)) dùng để đóng Lightbox khi bấm X. | | initialIndex | Number | Không | Vị trí index ảnh muốn mở đầu tiên. Mặc định là 0. |

5. Ví dụ tích hợp thực tế

Cách nhanh nhất để dựng một trang gallery. Bạn chỉ cần định nghĩa mảng dữ liệu và truyền vào component layout.

import React from 'react';
// Import layout từ thư viện NPM
import { MasonryLayout } from 'creative-gallery-react';

const myGalleryData = [
  {
    id: 1,
    url: '/assets/high-res-1.jpg',
    thumbnailUrl: '/assets/thumb-1.jpg',
    title: 'Phòng khách phong cách Bắc Âu',
    description: 'Sử dụng tone màu ấm và tận dụng ánh sáng tự nhiên.'
  },
  {
    id: 2,
    url: '/assets/high-res-2.jpg',
    title: 'Góc làm việc tối giản',
    description: 'Bàn gỗ sồi kết hợp ghế Ergonomic hiện đại.'
  }
];

const App = () => {
  return (
    <div className="container mx-auto py-10 px-4">
      <h2 className="text-3xl font-semibold mb-8 text-gray-800">Không Gian Sống</h2>
      
      {/* Khởi tạo component */}
      <MasonryLayout images={myGalleryData} />
    </div>
  );
};

export default App;

Tác giả: GokuWebDev