Guides and Sample Code


Apple News Format: Design Tutorial

On This Page


You can add a caption to your article using a component with the role of caption. One advantage of having photos and captions in separate components is that you can easily use different component layout objects for each, for example aligning a caption with article text and using a dramatic full-bleed layout for an image.

image: ../Art/photo-caption_2x.png

You’ll place a caption component in the article’s components array. For any caption component, the value of the role property is "caption", and the value of the text property is the caption text.

Additionally, you’ll add a caption property to the photo component. A caption property is different from a caption component. Text in the caption property is associated with the image, appears in zoomed-in or full-screen image views, and is used by VoiceOver for iOS. Text in the caption component is displayed in the article layout.

For information on customizing captions, see Caption in the Apple News Format Reference.

JSON Example: Photo Captions

Add a caption component, and add a caption property to the photo component. Note the slight variation in the text between the caption property and the caption component.

Example Code

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

  1. {
  2. ...
  3. "components": [
  4. ...
  5. {
  6. "role": "photo",
  7. "caption": "A caption for the photo.",
  8. "URL": "bundle://header.jpg"
  9. },
  10. {
  11. "role": "caption",
  12. "text": "ABOVE: A caption for the photo. (Attribution)"
  13. },
  14. ...
  15. ],
  16. ...
  17. }

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 changing the caption text of your article’s photo captions:

  1. In your code, find the photo component in the components array.

  2. In the photo component, find the caption property.

  3. Replace the value of the caption property, "A caption for the photo.", with the caption text of your choice.

    Be sure to include quotation marks. See also: A JSON Object Has Properties.

  4. Preview your article.json file in News Preview. See also: Updating Your Article Preview.

  5. In News Preview, click the photo to view the caption that you changed.

    The caption text has changed.

  6. Repeat steps 3–5 with the text property of the caption component.