Contents

ArticleThumbnail

The component for displaying a thumbnail image with an article link.

Declaration

object ArticleThumbnail

Properties

NameTypeDescription
role Requiredstring

Always article_thumbnail for this component.

accessibilityCaptionstring

A caption that describes the image. VoiceOver uses this text. For more information about VoiceOver, see the Vision page in Accessibility. If you don’t provide accessibilityCaption, VoiceOver uses the caption value.

additions[ComponentLink]

Ignored for all subcomponents of ArticleLink.

anchorAnchor

An object that defines vertical alignment with another component.

animation(ComponentAnimation | string("none"))

An object that defines an animation you apply to the component.

Use the none value for conditional design elements. Adding it here has no effect.

articleIdentifierstring

The identifier of the article that this component displays the thumbnail of. By default the articleIdentifier value is inherited from the ArticleLink component.

aspectRatiofloat

The aspect ratio of the component in which the article thumbnail is displayed.

behavior(Behavior | string("none"))

An object that defines behavior for a component, like Parallax or Springy.

Use the none value for conditional design elements. Adding it here has no effect.

caption(CaptionDescriptor | string)

A caption that describes the image. The article displays this text when the image is full screen, and VoiceOver uses this text if you don’t provide accessibilityCaption text. For more information about VoiceOver, see the Vision page in Accessibility. The caption text doesn’t appear in the main article view. To display a caption in the main article view, use the Caption component.

conditional(ConditionalComponent | [ConditionalComponent])

An instance or array of component properties that you can apply conditionally, and the conditions that cause Apple News Format to apply them.

explicitContentboolean

A Boolean that indicates that the image may contain explicit content.

fillModestring

A string that indicates how to display the image fill.

Valid values:

  • cover (default). Scales the image by aspect ratio to completely fill the component.

  • fit. Scales the image by aspect ratio to fit the component.

hiddenboolean

A Boolean that indicates whether the component is hidden.

horizontalAlignmentstring

A string that sets the horizontal alignment of the image fill within its component.

Valid values:

  • left. Aligns the left edge of the fill with the left edge of the component.

  • center (default). Aligns the horizontal center of the fill with the center of the component.

  • right. Aligns the right edge of the fill with the right edge of the component.

You can use fillMode with horizontalAlignment to achieve the effect you want. For example, set fillMode to fit and horizontalAlignment to left to fit the image based on its aspect ratio and align the left edge of the fill with the left edge of the component. Or set fillMode to cover and horizontalAlignment to right to scale the image horizontally and align the right edge of the fill with the right edge of the component.

identifierstring

A unique identifier for this component. If you use identifier, it must be unique across the entire document. Apple News requires an identifier if you want to anchor other components to this component. See Anchor.

layout(ComponentLayout | string)

An inline ComponentLayout object that contains layout information, or a string reference to a ComponentLayout object that’s defined at the top level of the document.

If you don’t define layout, Apple News bases size and position on various factors, such as the device type, the length of the content, and the role of this component.

style(ComponentStyle | string | string("none"))

An inline ComponentStyle object that defines the appearance of this component, or a string reference to a ComponentStyle object that’s defined at the top level of the document.

Use the none value for conditional design elements. Adding it here has no effect.

URLuri

The URL of an image file.

If omitted, the thumbnail of the article referenced in the ArticleLink component is used. Images should be high-resolution so they can be smoothly scaled down.

Image URLs can begin with http://, https://, or bundle://. If the image URL begins with bundle://, the image file must be in the same directory as the document.

Image filenames should be properly encoded as URLs.

See Preparing Image, Video, Audio, Music, and ARKit Assets.

verticalAlignmentstring

A string that defines the vertical alignment of the article thumbnail within the component.

Mentioned in

Discussion

Use the ArticleThumbnail object to display the thumbnail of an article. Use this component inside an ArticleLink component. The value of the URL property is automatically populated to reference the thumbnail image associated with the article (using the articleIdentifier property of the ArticleLink component). To provide a custom thumbnail, use another component, such as Image.

Example

{
  "components": [
    {
      "role": "article_link",
      "articleIdentifier": "https://apple.news/AT6kNQslCQy6EE4bF8hpOoQ",
      "components": [
        {
          "role": "article_thumbnail",
          "aspectRatio": 1,
          "fillMode": "cover",
          "verticalAlignment": "top"
        },
        {
          "role": "article_title"
        }
      ]
    }
  ]
}

See Also

Article Structure