---
source: https://carbone.io/examples/gallery-simple/
title: "Gallery of images | Carbone Sample"
description: "Learn how to generate professional image gallery documents using Carbone. This template shows how to merge JSON data with DOCX templates to create beautiful image layouts."
generated_at: "2026-07-10"
---

# Gallery of images

Generate a beautiful gallery of images with Carbone

[![gallery-simple thumbnail](/examples/gallery-simple/thumb-result.webp)](/examples/gallery-simple/result.pdf)

[Download Template](/examples/gallery-simple/template.docx)

[Download data sample](/examples/gallery-simple/data.json)

-   Template type document docx expert
-   Carbone min. v5.0.0+
-   Features loop bidirectional set count imageFit header
-   Target gallery array

## Overview

Learn how to create a professional image gallery with these key features:

-   Display multiple images from an array
-   Create a fixed-column layout
-   Ensure perfect image fitting within cells

## Step-by-Step Guide

This example demonstrates how to display images from a JSON array in a fixed-column layout. We'll restructure the JSON data using Carbone tags to achieve the desired layout.

### 1\. Restructure the JSON Data

Use these formatters to organize the data:

-   [:cumCount()](/documentation/design/computation/aggregation.md#cumcount-partitionby) to track total entries
-   [:div()](/documentation/design/formatters/number.md#div-value) to calculate rows based on desired columns (example: 3)
-   [:ceil](/documentation/design/formatters/number.md#ceil) to round up to whole numbers
-   [:set()](/documentation/design/computation/store-and-transform.md#store-values-set-absolutepath) to store the result

Example: `{d.image[]:cumCount():div(3):ceil:set(.rowNb)}`

### 2\. Transform the JSON Structure

Group objects that share the same `rowNb` value into a new array using the [:set()](/documentation/design/computation/store-and-transform.md#transform-json-set-absolutepath) formatter.

Example: `{d.image[]:set(d.group[id=.rowNb].pictures[])}`

**Original JSON Structure:**

```json
{
  "image": [
    { "pic": "a" },
    { "pic": "b" },
    { "pic": "c" },
    { "pic": "d" }
  ]
}
```

**Transformed JSON Structure:**

```json
{
  "image": [
    { "pic": "a", "rowNb": 1 },
    { "pic": "b", "rowNb": 1 },
    { "pic": "c", "rowNb": 1 },
    { "pic": "d", "rowNb": 1 }
  ],
  "group": [
    { "id": 1, "pictures": [
        { "pic": "a", "rowNb": 1 },
        { "pic": "b", "rowNb": 1 }
      ]
    },
    { "id": 2, "pictures": [
        { "pic": "c", "rowNb": 2 },
        { "pic": "d", "rowNb": 2 }
      ]
    }
  ]
}
```

### 3\. Create the Image Layout

-   Create a 2x2 table (whatever the number of columns you want)
-   Insert a [temporary image](https://carbone.io/documentation/design/advanced-features/pictures.md#simple-image-docx) in the first cell
-   Add the Carbone tag in the image's Alt Text:
    -   Use `{d.group[i].pictures[i].pic}` to display the image
    -   Add [:imageFit](/documentation/design/advanced-features/pictures.md#how-to-insert-picture-image-aspect-ratio-imagefit) formatter to control sizing: `{d.group[i].pictures[i].pic:imageFit(contain)}`

### 4\. Set Up Horizontal Repetition

In the second cell of the first row, use `[i+1]` for horizontal iteration: `{d.group[i].pictures[i+1]}`

### 5\. Set Up Vertical Repetition

In the first cell of the second row, use `[i+1]` for vertical iteration: `{d.group[i+1]}`

## Alternative Layout Option

To maintain a fixed number of columns on the last row when the number of images is not sufficient in the data :

1.  Instead of creating a 2x2 table (step 3.a), create a table with your desired number of columns (example: 3 columns) and always 2 rows
2.  In the first row, define the content manually. Example: insert a placeholder in each cell and define in the **Alt text** respectively: `{d.group[i].pictures[0].pic}`, `{d.group[i].pictures[1].pic}` and `{d.group[i].pictures[2].pic}`
3.  In the second and the third cell of the first row, add a condition to handle empty cells using [:drop(img)](/documentation/design/conditions/smart-conditions.md#drop-keep-element): `{d.group[i].pictures[2].pic:ifEM:drop(img)}`

## Page Layout Enhancement

To add a background image that appears on every page:

1.  Insert your chosen image in the document header
2.  Lock the image anchor position
3.  The image will automatically repeat on all pages

## Related Examples

[![bank-statement-simple thumbnail example](/examples/bank-statement-simple/thumb-result.webp)](/examples/bank-statement-simple/index.md)

## Trusted by 800+ paid customers in 40+ countries

## Related topics

- [Transport ticket](/examples/ticket/index.md)
- [Summary](/examples/summary/index.md)
- [Stock inventory spreadsheet](/examples/stock-inventory-spreadsheet/index.md)
- [Store Inventory](/examples/shoes/index.md)
- [Sensor readings](/examples/sensor-readings/index.md)
- [Real estate property document](/examples/real-estate-property-description/index.md)