Image Gallery Post Template - Bottom-Aligned Rows with Configurable Heights

Juniper Chen

This is a template post for image-heavy content. You can place text before and after each gallery block, and the text style matches the body size used in blog prose.

API 调用说明(先代码 / 后效果)

完整 API 参数说明(逐行注释)

// ===== 完整 API 调用参考(每行注释版)=====<ImageGalleryTemplaterowHeight="medium" // 全局基准高度: "low" | "medium" | "high"(默认 medium)portraitSpanRows // 开启后,竖图会按规则放大高度(默认 false)portraitRatioThreshold={1} // 低于该比例判定为竖图(默认 1)portraitSpanCount={2} // 竖图放大倍数(默认 2)className="my-6" // 外层容器自定义类名(可选)items={[  {    src: "http://.../DSC05661.jpg", // 图片地址(可选;不传会显示占位块)    alt: "Street photo", // 图片替代文本(必填)    size: "high", // 单项高度,优先级高于 rowHeight(可选)    caption: "override to high", // 图注(可选)    ratio: "3:4", // 宽高比(可选;推荐 "3:4" 这种写法,缺省回退 4:3)    id: "hero-photo", // 稳定 key(可选,建议列表动态场景使用)  },  {    kind: "placeholder", // 进阶项:占位块    fillAxis: "height", // "width" 横向补位 | "height" 纵向补位    fillRemaining: true, // 是否吃掉剩余空间(默认 true)    ratio: "1:1", // 占位比例(可选)    minRatio: "1:1", // 最小比例下限(可选)    spanRows: 1, // 纵向占位行数(可选)    heightOffset: -240, // 高度微调(可选,支持负数)    reserveCaptionSpace: true, // 预留 caption 空间,便于和图片对齐(可选)    size: "medium", // 占位块高度档位(可选,也支持 legacy: height)    caption: "placeholder", // 占位块图注(可选)    id: "ph-1", // 稳定 key(可选)  },]}advancedItems={[  {    kind: "text", // 进阶项:文字块    text: <>Custom text tile.</>, // 文字内容(ReactNode)    ratio: "4:3", // 文本块比例(可选)    minRatio: "4:3", // 文本块最小比例(可选)    fillRemaining: true, // 是否填充剩余宽度(可选,默认 true)    reserveCaptionSpace: true, // 无 caption 时也预留图注高度(可选)    size: "low", // 文本块高度档位(可选,也支持 legacy: height)    caption: "text tile", // 文本块图注(可选)    id: "txt-1", // 稳定 key(可选)  },]}/>// ===== 语法糖(简化批量图片输入)=====const items = withSize(fromImages([  "http://.../DSC05661.jpg", // 仅传字符串:自动生成 alt  { src: "http://.../DSC05663.jpg", alt: "Manual alt", caption: "Optional caption" }, // 也可对象写法]),"medium", // 批量设置 size: "low" | "medium" | "high");

1) 最简调用:批量图片 + 统一尺寸

<ImageGalleryTemplaterowHeight="medium"items={withSize(  fromImages([    "http://.../DSC05663.jpg",  ]),  "medium",)}/>
DSC05663

2) 单项覆盖尺寸:全局 rowHeight + item size

<ImageGalleryTemplaterowHeight="medium"items={[  { alt: "Default medium", ratio: "3:4", caption: "inherits rowHeight" },  { alt: "Force high", ratio: "16:9", size: "high", caption: "item size: high" },  { alt: "Force low", ratio: "1:1", size: "low", caption: "item size: low" },]}/>
Default medium
inherits rowHeight
Force high
item size: high
Force low
item size: low

3) 进阶调用:items + advancedItems

<ImageGalleryTemplaterowHeight="medium"portraitSpanRowsitems={[  { alt: "Photo A", ratio: "3:4", caption: "image item" },  {    kind: "placeholder",    ratio: "1:1",    fillAxis: "width",    spanRows: 1,    heightOffset: -240,    reserveCaptionSpace: true,  },  { alt: "Photo B", ratio: "16:9", caption: "image item" },]}advancedItems={[  {    kind: "text",    ratio: "4:3",    height: "low",    caption: "text tile",    text: <>Advanced text block.</>,  },]}/>
Photo A
image item
Photo B
image item
Advanced text block.
text tile

Mixed Example (2x Medium + Right Landscape)

Left portrait 9:16
Left bottom: 9:16 portrait, medium span-2 (540x960)
Right landscape 16:9 top
Right top: 16:9 landscape, medium (853x480)
Right landscape 16:9 bottom
Right bottom: 16:9 landscape, medium (853x480)

Image + Text Box (Equal Height)

Photo 3:4 medium
3:4 image (315x420)
Photo 16:9 medium
16:9 image (747x420)
Photo 16:9 high
16:9 + high (924x520)
This is a text tile with equal height to the image tile.
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
Text box (>= 4:3, 560x420)
This is a text tile with equal height to the image tile.
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
Text box (>= 4:3, 560x420)
This is a text tile with equal height to the image tile.
The text container is bottom-aligned, and the tile ratio is clamped to at least 4:3.
Text box (1:1, 320x320)

Mixed Height In One Row

Mixed 3:4 low
3:4 + low (240x320)
Mixed 16:9 high
16:9 + high (924x520)
Mixed 1:1 medium
1:1 + medium (420x420)
Mixed 9:16 low
9:16 + low (200x320)

Each item can override height independently via height: "low" | "medium" | "high", so mixed heights can appear in the same wrapped row.

Portrait Span Two Rows (Experimental)

Low (320 -> 640)

Portrait 3:4 low
3:4 portrait, low span-2 (480x640)
Tall 9:16 low
9:16 portrait, low span-2 (360x640)
Landscape 16:9 low
16:9 landscape, low normal (569x320)

Medium (480 -> 960)

Portrait 3:4 medium
3:4 portrait, medium span-2 (720x960)
Tall 9:16 medium
9:16 portrait, medium span-2 (540x960)
Landscape 16:9 medium
16:9 landscape, medium normal (853x480)

High (540 -> 1080)

Portrait 3:4 high
3:4 portrait, high span-2 (810x1080)
Tall 9:16 high
9:16 portrait, high span-2 (608x1080)
Landscape 16:9 high
16:9 landscape, high normal (960x540)

With portraitSpanRows, portrait images (ratio < 1) are scaled proportionally to 2x row height while landscape images remain at the base row height.


Low Row Height

Low 1:1
Square 1:1 (320x320)
Low 4:3
Classic landscape 4:3 (427x320)
Low 3:4
Portrait 3:4 (240x320)
Low 3:2
Photo landscape 3:2 (480x320)
Low 2:3
Photo portrait 2:3 (213x320)
Low 16:9
Widescreen 16:9 (569x320)
Low 9:16
Tall mobile 9:16 (200x320)
Low 21:9
Ultra wide 21:9 (747x320)

Low row height is good for overview sections with many images. It increases density while keeping captions readable.

Medium Row Height

Medium 1:1
Square 1:1 (480x480)
Medium 4:3
Classic landscape 4:3 (640x480)
Medium 3:4
Portrait 3:4 (360x480)
Medium 3:2
Photo landscape 3:2 (720x480)
Medium 2:3
Photo portrait 2:3 (320x480)
Medium 16:9
Widescreen 16:9 (853x480)
Medium 9:16
Tall mobile 9:16 (270x480)
Medium 21:9
Ultra wide 21:9 (1120x480)

Medium is a balanced default. If you do not have a strong reason, this is usually the best starting point.

High Row Height

High 1:1
Square 1:1 (540x540)
High 4:3
Classic landscape 4:3 (720x540)
High 3:4
Portrait 3:4 (405x540)
High 3:2
Photo landscape 3:2 (810x540)
High 2:3
Photo portrait 2:3 (360x540)
High 16:9
Widescreen 16:9 (960x540)
High 9:16
Tall mobile 9:16 (304x540)
High 21:9
Ultra wide 21:9 (1260x540)

High row height works for storytelling blocks where each image needs stronger visual impact.

Copyright © 2025 Tailwind Labs Inc.·Trademark Policy