Guides and Sample Code

Developer

Apple News Format: Design Tutorial

On This Page

Gallery Components

You can use a gallery component to display a sequence of images as a horizontal strip that the user can swipe through. A gallery gives the reader access to multiple images, without using up too much vertical space; it also gives readers the immersive experience of swiping through the images. You may want to use a gallery component when the order of the images is important to the story and a mosaic compnonent when the order is not important.

image: ../Art/gallery-closeup_2x.png
image: ../Art/gallery_2x.png

In your article, you’ll place a gallery component in the article’s components array. For any gallery component, the value of the items property is an array of objects called gallery items. The order of objects in the items array determines the order of the gallery images. For each gallery item, the value of the URL property works as it does for photo components.

For information on customizing gallery components, see Gallery and Gallery Item in the Apple News Format Reference.

Image Guidelines

For image guidelines, see Image Guidelines and Gallery in the Apple News Format Reference.

JSON Example: Gallery Component

Create a gallery component that contains three images.

Example Code

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

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "gallery",
  7. "items": [
  8. {
  9. "URL": "bundle://gallery-01.jpg"
  10. },
  11. {
  12. "URL": "bundle://gallery-02.jpg"
  13. },
  14. {
  15. "URL": "bundle://gallery-03.jpg"
  16. }
  17. ]
  18. },
  19. ...
  20. ],
  21. ...
  22. }

JSON Example: Gallery Captions

Add a caption component. Then, within each gallery item, add an image-specific caption property. For more information about captions, see Captions in this tutorial.

Example Code

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

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "gallery",
  7. "items": [
  8. {
  9. "URL": "bundle://gallery-01.jpg",
  10. "caption": "A caption for the first image in the gallery."
  11. },
  12. {
  13. "URL": "bundle://gallery-02.jpg",
  14. "caption": "A caption for the second image in the gallery."
  15. },
  16. {
  17. "URL": "bundle://gallery-03.jpg",
  18. "caption": "A caption for the third image in the gallery."
  19. }
  20. ]
  21. },
  22. {
  23. "role": "caption",
  24. "text": "ABOVE: A caption for the entire gallery. Individual photos in the gallery also have their own captions. (Shared attribution)"
  25. },
  26. ...
  27. ],
  28. ...
  29. }

JSON Example: References to Component Layout Objects

Add references to component layout objects in the gallery and caption components. Also, add a divider to set the gallery apart visually.

The noMarginLayout, halfMarginBothLayout, and fullMarginBelowLayout component layout objects were defined earlier in the tutorial. For the purposes of this tutorial, a “full margin” was considered to be a space of 24 points above or below a component, and a “half margin” to be a space of 12 points.

Example Code

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

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "gallery",
  7. "layout": "noMarginLayout",
  8. "items": [
  9. {
  10. "URL": "bundle://gallery-01.jpg",
  11. "caption": "A caption for the first image in the gallery."
  12. },
  13. {
  14. "URL": "bundle://gallery-02.jpg",
  15. "caption": "A caption for the second image in the gallery."
  16. },
  17. {
  18. "URL": "bundle://gallery-03.jpg",
  19. "caption": "A caption for the third image in the gallery."
  20. }
  21. ]
  22. },
  23. {
  24. "role": "caption",
  25. "layout": "halfMarginBothLayout",
  26. "text": "ABOVE: A caption for the entire gallery. Individual photos in the gallery also have their own captions. (Shared attribution)"
  27. },
  28. {
  29. "role": "divider",
  30. "layout": "fullMarginBelowLayout",
  31. "stroke": {
  32. "width": 1,
  33. "color": "#D5B327"
  34. }
  35. },
  36. ...
  37. ],
  38. ...
  39. }

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 impact the look of your article.

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

  1. In your code, find the items array inside the gallery component.

  2. Within the items array, cut the entire first object, including both curly brackets and the comma, to your clipboard.

  3. Paste the object between the two remaining objects in the gallery. See also: Tutorial Tip: Adding Objects to Arrays in article.json.

  4. Preview your article.json file in News Preview; see Updating Your Article Preview.

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