<!--
{
  "documentType" : "article",
  "framework" : "AppleNews",
  "identifier" : "/documentation/AppleNews/adding-a-gallery-of-images",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Adding a Gallery of Images"
}
-->

# Adding a Gallery of Images

Display three images as a sequential gallery.

## Discussion

**On this page, you’ll learn how to use a gallery to display a sequence of images as a horizontal strip that the user can swipe through.**

![Screenshot of an Apple News article with a gallery on iPad.](images/com.apple.applenews/media-3624436@2x.png)

### Add a Gallery in Your Article

In <doc://com.apple.applenews/documentation/AppleNews/setting-up-the-introductory-tutorial#Download-the-Article-Bundle-Examples>, you downloaded a bundle called `News_Design_Tutorial_5_Galleries` that contains gallery images and mosaic images. Now, you’ll move some of those images into your working folder and create a `gallery` component to display the images.

1. Move the `gallery-01.jpg`, `gallery-02.jpg`, and `gallery-03.jpg` files from the `Desktop/News_Design/Tutorial/News_Design_Tutorial_5_Galleries` folder that you downloaded in <doc://com.apple.applenews/documentation/AppleNews/setting-up-the-introductory-tutorial#Download-the-Article-Bundle-Examples> to the folder that contains your working `article.json` file.
2. Copy the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Gallery-Copy-This-Code>.
3. Paste the code inside the `components` array of your article, after the closing brace (`}`) of the third `heading2` component.

Your code should look like the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Gallery-Result>.

After you make this change in your code, you can preview your working `article.json` file in News Preview to see a gallery in your article.

#### Gallery: Copy This Code

```json
    {
      "role": "gallery",
      "items": [
        {
          "URL": "bundle://gallery-01.jpg"
        },
        {
          "URL": "bundle://gallery-02.jpg"
        },
        {
          "URL": "bundle://gallery-03.jpg"
        }
      ]
    },
```

#### Gallery: Result

Ellipses (`...`) indicate lines of code that have been omitted from this example.

```json
{
  ...
  "components": [
    ...
    {
      "role": "gallery",
      "items": [
        {
          "URL": "bundle://gallery-01.jpg"
        },
        {
          "URL": "bundle://gallery-02.jpg"
        },
        {
          "URL": "bundle://gallery-03.jpg"
        }
      ]
    },
    ...
  ],
  ...
}
```

### Add Captions for Gallery Images

In <doc://com.apple.applenews/documentation/AppleNews/adding-an-image-and-captions>, you created a `caption` component in your article layout and a `caption` property for when users view your photo in full screen. Here, you’ll do something similar, adding a `caption` component for the gallery and `caption` properties for each gallery item.

1. Copy the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Caption-Copy-This-Code>.
2. Paste the code inside the `components` array of your article, after the closing brace and comma (`},`) that end the `gallery` component.
3. In each of the three gallery items in your `gallery` component, add a comma after `"bundle://gallery-<XX>.jpg"`
4. Copy the `"caption"` properties in the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Caption-Result>, and paste them after the commas that you added in the previous step.

After you make these changes in your code, you can preview your working `article.json` file in News Preview to see captions for each gallery item and for the whole gallery.

#### Caption: Copy This Code

```json
    {
      "role": "caption",
      "text": "ABOVE: A caption for the entire gallery. Individual photos in the gallery also have their own captions. (Shared attribution)"
    },
```

#### Caption: Result

Ellipses (`...`) indicate lines of code that have been omitted from this example.

```json
{
  ...
  "components": [
    ...
    {
      "role": "gallery",
      "items": [
        {
          "URL": "bundle://gallery-01.jpg",
          "caption": "A caption for the first image in the gallery."
        },
        {
          "URL": "bundle://gallery-02.jpg",
          "caption": "A caption for the second image in the gallery."
        },
        {
          "URL": "bundle://gallery-03.jpg",
          "caption": "A caption for the third image in the gallery."
        }
      ]
    },
    {
      "role": "caption",
      "text": "ABOVE: A caption for the entire gallery. Individual photos in the gallery also have their own captions. (Shared attribution)"
    },
    ...
  ],
  ...
}
```

### Modify Gallery and Caption Positioning and Add a Divider

In <doc://com.apple.applenews/documentation/AppleNews/positioning-text-components> and <doc://com.apple.applenews/documentation/AppleNews/adding-an-image-and-captions>, you created some `ComponentLayout` objects. You’ll refer to those `ComponentLayout` objects in this code. You’ll also add a `divider` component to set the gallery apart visually.

1. Copy the line `"layout": "noMarginLayout",`
2. Paste the line inside your `gallery` component, after the line `"role": "gallery",`
3. Copy the line `"layout": "halfMarginBothLayout",`
4. Paste the line inside your `caption` component, after the line `"role": "caption",`
5. Copy the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Divider-Copy-This-Code>, and paste it after the closing brace and comma (`},`) that end the `caption` component for the gallery.

Your code should look like the example code <doc://com.apple.applenews/documentation/AppleNews/adding-a-gallery-of-images#Divider-Result>.

After you make these changes in your code, you can preview your working `article.json` file in News Preview to see the new divider and some changes in the positioning of your components.

#### Divider: Copy This Code

```json
    {
      "role": "divider",
      "layout": "fullMarginBelowLayout",
      "stroke": {
        "width": 1,
        "color": "#D5B327"
      }
    },
```

#### Divider: Result

Ellipses (`...`) indicate lines of code that have been omitted from this example.

```json
{
  ...
  "components": [
    ...
    {
      "role": "gallery",
      "layout": "noMarginLayout",
      "items": [
        {
          "URL": "bundle://gallery-01.jpg",
          "caption": "A caption for the first image in the gallery."
        },
        {
          "URL": "bundle://gallery-02.jpg",
          "caption": "A caption for the second image in the gallery."
        },
        {
          "URL": "bundle://gallery-03.jpg",
          "caption": "A caption for the third image in the gallery."
        }
      ]
    },
    {
      "role": "caption",
      "layout": "halfMarginBothLayout",
      "text": "ABOVE: A caption for the entire gallery. Individual photos in the gallery also have their own captions. (Shared attribution)"
    },
    {
      "role": "divider",
      "layout": "fullMarginBelowLayout",
      "stroke": {
        "width": 1,
        "color": "#D5B327"
      }
    },
    ...
  ],
  ...
}
```

### Further Exploration

At any time, you can try changing property values in your `article.json` file and then use News Preview to see how these changes affect the look of your article.

For example, try switching the order of the first two images in your `gallery` component:

1. In your `article.json` file, find the `items` array inside the `gallery` component.
2. Within the `items` array, cut the entire first object, including both braces (`{}`) and the comma, to your clipboard.
3. Paste the object between the two remaining objects in the gallery.
4. Preview your `article.json` file in News Preview.

The order of your first and second gallery items has been switched.

### Previous

<doc://com.apple.applenews/documentation/AppleNews/adding-a-pull-quote>

### Next

<doc://com.apple.applenews/documentation/AppleNews/adding-a-mosaic-of-images>

## See Also

[`object Gallery`](/documentation/AppleNewsFormat/Gallery)

The component for displaying a sequence of images in a specific order as a horizontal strip.

[`object GalleryItem`](/documentation/AppleNewsFormat/GalleryItem)

An object used in a gallery or mosaic component for displaying an individual image.

[`object Caption`](/documentation/AppleNewsFormat/Caption)

The component for adding caption text.

[`object CaptionDescriptor`](/documentation/AppleNewsFormat/CaptionDescriptor)

The object you use in image components for displaying captions when the image is full-screen.



---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)