圖磚網格主視覺｜免費 React 元件

標題在左、右側圖磚網格自中心向外依序進場，hover 單塊放大、其他圖磚微暗。

編輯感的兩欄主視覺：左側是小標、標題、說明與 CTA，右側是一面正方形圖磚網格（2×2、3×3 或 4×3），其中可讓 1–2 塊佔 2×2 形成不規則版面。進場時圖磚以網格中心為起點、依曼哈頓距離向外擴散——縮放、淡入、去模糊同時發生；滑過或聚焦任一圖磚，它會以彈簧放大並浮起陰影、底部說明淡入，其他圖磚微暗降飽和。沒給圖片時每塊都會畫內建的漸層加幾何佔位，不需要任何外部圖片。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add image-tile-grid-hero

還沒有專案，或安裝遇到問題？看快速開始 →

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

網格grid

hover 放大倍率hoverZoom

1.04

進場間隔（ms）stagger

進場時長（ms）duration

500

小標eyebrow

標題title

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<ImageTileGridHero/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

安裝

npx webberui@latest add https://webberui.com/r/image-tile-grid-hero.json

或在 components.json 設定 registries 後，改用 @webberui/image-tile-grid-hero 安裝。

使用

import { ImageTileGridHero } from "@/components/ui/image-tile-grid-hero";

<ImageTileGridHero
  eyebrow="青嶼器物 · 秋季選品"
  title="把日常器物，排成一面安靜的牆"
  subtitle="二十件手作陶器與織品，從工作室直送。"
  primaryAction={{ label: "逛本季選品", href: "/shop" }}
  secondaryAction={{ label: "預約門市", href: "/visit" }}
  grid="3x3"
  tiles={[
    { alt: "霧面陶土花器", caption: "霧面陶花器", href: "/p/vase" },
    { src: "/images/arch.jpg", alt: "拱門形掛毯", caption: "本季主打", span: 2 },
    { alt: "砂岩色球形桌燈", caption: "砂岩球燈" },
  ]}
/>

Props

Prop	型別	預設值	說明
`title`	`ReactNode`	—	主標題（必填）
`eyebrow`	`ReactNode`	—	標題上方的小標，使用強調色
`subtitle`	`ReactNode`	—	標題下方的說明文字
`primaryAction`	`ImageTileGridHeroAction`	—	主要行動按鈕，背景使用強調色
`secondaryAction`	`ImageTileGridHeroAction`	—	次要行動按鈕（外框樣式）
`as`	`"h1" \| "h2"`	`"h1"`	標題層級
`minHeight`	`number`	`560`	區塊最小高度（px）
`tiles`	`ImageGridTile[]`	9 張內建佔位圖	圖磚清單；超出網格容量的圖磚不顯示
`grid`	`"2x2" \| "3x3" \| "4x3"`	`"3x3"`	網格規格（欄 × 列）
`hoverZoom`	`number`	`1.04`	hover／focus 時單塊圖磚的放大倍率
`stagger`	`number`	—	每一步曼哈頓距離的進場延遲（ms）；省略時讀 `--wb-image-tile-grid-hero-stagger`（60ms）
`duration`	`number`	—	進場時長（ms）；省略時讀 `--wb-image-tile-grid-hero-duration`（圖磚 500ms、文字 600ms）
`activeIndex`	`number \| null`	—	受控的作用中圖磚索引；未提供時由元件內部管理
`defaultActiveIndex`	`number \| null`	`null`	非受控模式的初始作用中圖磚索引
`onActiveIndexChange`	`(index: number \| null) => void`	—	作用中圖磚改變時回呼（hover、focus 或離開）
`galleryLabel`	`string`	`"作品圖磚"`	圖磚網格的無障礙名稱
`className`	`string`	—	併入根 `section` 的 class

ImageGridTile

欄位	型別	預設值	說明
`alt`	`string`	—	替代文字（必填），也作為佔位圖的無障礙名稱
`src`	`string`	—	圖片網址；省略則畫漸層加幾何佔位
`caption`	`string`	—	圖磚底部的小字說明，hover／focus 時淡入
`span`	`1 \| 2`	`1`	設 `2` 佔 2×2；網格欄數不足 3 時退回單格
`href`	`string`	—	提供時圖磚渲染為可聚焦的連結

ImageTileGridHeroAction

欄位	型別	預設值	說明
`label`	`string`	—	按鈕文字
`href`	`string`	—	提供時渲染為連結，否則為 `type="button"` 的按鈕
`onClick`	`() => void`	—	點擊回呼

細節

排版：圖磚依序放進第一個放得下的空位（列優先），span: 2 的圖磚放不下時自動退回單格，再放不下就略過。座標由元件自己計算，因為進場延遲需要每塊的實際位置。
進場節奏：每塊延遲 = 與網格中心的曼哈頓距離 × --wb-image-tile-grid-hero-stagger，同時從 scale(0.9)、透明、blur(6px) 回到原狀；文字區依序上浮，間隔 80ms，曲線 cubic-bezier(0.22,1,0.36,1)。
強調色：--wb-image-tile-grid-hero-accent（淺色預設 #0d9488，深色預設 #2dd4bf）同時用於小標、主按鈕背景與焦點框。
進場動畫寫在 CSS keyframes，首次繪製就生效，不必等 hydration；hover 放大則由 motion 的彈簧（stiffness 300、damping 22）驅動。

可及性

根元素為 section，以 aria-labelledby 指向標題；標題層級可用 as 切換為 h2
圖磚網格為 role="group" 並帶 galleryLabel；有 href 的圖磚是 a 連結，可用 Tab 聚焦、聚焦時放大並顯示 focus-visible 焦點框，其餘為 figure 搭配 figcaption
alt 為必填：使用者圖片直接用作 img 的 alt，佔位圖則以 role="img" 與 aria-label 提供名稱
說明文字只是視覺上淡入，始終留在 DOM 中，螢幕閱讀器不必 hover 也讀得到
使用者系統開啟「減少動態效果」時，所有進場改為 150ms 淡入（無位移、縮放與模糊），hover 不再放大，僅保留其他圖磚微暗

圖磚網格主視覺

把這個效果裝進你的專案

本頁目錄