Contents

ComponentLayout

The object for defining the positioning for a specific component within the article’s column system.

Declaration

object ComponentLayout

Properties

NameTypeDescription
columnSpaninteger

A number that indicates how many columns the component spans, based on the number of columns in the document.

By default, the component spans the entire width of the document or the width of its container component.

columnStartinteger

A number that indicates which column the component’s start position is in, based on the number of columns in the document or parent container.

By default, the component starts in the first column (note that the first column is 0, not 1).

conditional(ConditionalComponentLayout | [ConditionalComponentLayout])

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

horizontalContentAlignmentstring

A string value that sets the alignment of the content within the component. This property applies only when the width of the content is less than the width of the component.

Apple News supports this property for LinkButton, Image, Logo, Divider, and MediumRectangleAdvertisement. All other components ignore this property.

ignoreDocumentGutter(boolean | string("none" | "left" | "right" | "both"))

A value that indicates whether Apple News ignores the gutters (if any) to the left and right of the component. The gutter size is defined in the Layout object at the root level of the document.

Use this option if you want to position two components right next to each other without a gutter between them. This property applies only when a gutter actually exists to the left or right of the component. The first column doesn’t have a left gutter, and the last column doesn’t have a right gutter.

Valid values:

  • none (default). The component doesn’t ignore any gutters.

  • left. The component ignores the gutter on the left.

  • right. The component ignores the gutter on the right.

  • both. The component ignores gutters, if any, on both sides.

You can also set this property to true to indicate that the component ignores both gutters, or set it to false to ignore none of the gutters. By default, none of the gutters are ignored.

ignoreDocumentMargin(boolean | string("none" | "left" | "right" | "both"))

A value that indicates whether the component applies or ignores the document’s margins. Ignoring document margins positions the component based on the document’s width and margin.

Valid values:

  • none (default). The component doesn’t ignore the margins.

  • left. The component ignores the left margin.

  • right. The component ignores the right margin.

  • both. The component ignores margins, if any, on both sides.

Instead of specifying margins, you can set this property to true so the component ignores both margins, or set it to false so the component ignores neither margin. By default, neither margin is ignored.

The layout of a parent component always constrains any child components. As such, setting ignoreDocumentMargin to true for a component has no effect if it’s inside of a container with ignoreDocumentMargin set to false.

Specifying a value other than none for ignoreViewportPadding takes precedence over any value defined for ignoreDocumentMargin.

On device with a screen size wider than the document width and margin combined, a component with ignoreDocumentMargin property set to true extends the width of the document plus the margin, but doesn’t extend into the viewport padding.

ignoreViewportPadding(boolean | string("none" | "left" | "right" | "both"))

A value that indicates whether the component applies or ignores the viewport padding. Ignoring viewport padding positions the component at the edge of the display screen. This property affects the layout only if the component is in the first or last column.

Valid values:

  • none (default). The component doesn’t ignore the padding.

  • left. The component ignores left padding.

  • right. The component ignores right padding.

  • both. The component ignores padding, if any, on both sides.

Instead of specifying the padding, you can also set this property to true so the component ignores paddings on both sides, or set it to false so the component ignores neither padding. By default, neither padding is ignored.

The layout of a parent component always constrains any child components. Setting ignoreViewportPadding to true for a component has no effect if it’s inside of a container with ignoreViewportPadding set to false.

If ignoreViewportPadding is set to true, left, right, or both, it overrides the layout’s ignoreDocumentMargin value and spans the entire screen.

If ignoreViewportPadding is set to none, Apple News Format accepts the value of ignoreDocumentMargin.

By default, components don’t ignore the viewport padding, even if you previously specified ignoreDocumentMargin to span the entire width of the screen. To achieve the same functionality, you must update your article to use ignoreViewportPadding.

margin(Margin | integer)

A value that sets the margins for the top and bottom of the component as a single integer that Apple News applies to the top and bottom margins, or as an object containing separate properties for top and bottom.

maximumContentWidth(SupportedUnits | number)

A value that sets the maximum width of the content within the component. Specify this value as a number in points or using one of the available units of measure for components. See Specifying Measurements for Components.

Apple News supports this property for LinkButton, Image, Logo, Divider, and MediumRectangleAdvertisement. All other components ignore this property.

minimumHeight(SupportedUnits | number)

A value that sets the minimum height of the component. A component is taller than its defined minimumHeight when the contents require the component to be taller. You can define the minimum height as a number in points or using one of the available units of measure for components. See Specifying Measurements for Components.

minimumWidth(SupportedUnits | number)

A value that defines the minimum width of the layout when you use it within a Container with HorizontalStackDisplay as the specified contentDisplay type. You can define the minimum width as a number in points or using one of the available units of measure for components. See Specifying Measurements for Components.

maximumWidth(SupportedUnits | number)

A value that defines the maximum width of the layout when you use it within a Container with HorizontalStackDisplay as the specified contentDisplay type. You can define the maximum width as a number in points or using one of the available units of measure for components. See Specifying Measurements for Components.

padding(SupportedUnits | Padding | number)

A value that defines the padding between the content of the component and the edges of the component. You can define padding as a number in points or using one of the available units of measure for components. See Specifying Measurements for Components.

Mentioned in

Discussion

Use the ComponentLayout object to define a position for a specific component within the column system defined using the Layout object.

For information on setting the units for the width and height, see Specifying Measurements for Components. For information on aligning components, see Anchor.

You can use this object in ArticleDocument.

Example

{
  "components": [
    {
      "role": "heading1",
      "layout": "heading1Layout",
      "text": "Heading Text"
    },
    {
      "role": "body",
      "text": "Apple News Format allows publishers to craft beautiful editorial layouts. Galleries, audio, video, and fun interactions like animation make stories spring to life."
    }
  ],
  "componentLayouts": {
    "heading1Layout": {
      "columnStart": 0,
      "columnSpan": 7,
      "margin": {
        "top": 24,
        "bottom": 10
      }
    }
  }
}

See Also

Article Layout