Article

Specifying Measurements for Components

Specify the units of measure to use for margins, minimum heights, and other dimensions.

Overview

In Apple News Format, you can use variable sizing for component margins, minimum component height, and other measurements. Sizes can be a percentage of the width or height of the viewport, the document margins and gutters, or the component’s height (the part of the document visible to the user).

This example sets the margin to 10 points, as a string value.

"margin": {
  "top": "10pt"
}

This example also sets the margin to 10 points, because an integer is specified and the default unit is points.

"margin": {
  "top": 10
}

Set Component Measurements Based on the Viewport

You can set the size of a margin or the minimum height for a component based on a percentage of the width or height of the viewport. The viewport includes the portion of the screen that is sometimes covered by the toolbar.

Set Measurements Based on Viewport Height

This example results in a component height of at least 50% of the viewport height (vh).

"minimumHeight": "50vh"

Set Measurements Based on Viewport Width

In this example, the component’s margin is set to 20% of the viewport width (vw).

"margin": {
  "bottom": "20vw"
}

Set Measurements Based on the Viewport’s Shortest Side

If you base a component’s minimum height on the shortest side of the viewport, remember that the minimum height varies depending on your device orientation. If your article is being viewed in portrait orientation, the calculation is based on the width of the viewport; in landscape, the calculation is based on the height of the viewport.

For example, if the viewport is narrow and tall (portrait), a value of 150vmin is calculated as 150% of the width. This example sets the component’s minimum height to 25% of the shortest side of the viewport.

"minimumHeight": "25vmin"

Set Measurements Based on the Viewport’s Longest Side

If you base a component’s minimum height on the longest side of the viewport, remember that the minimum height varies depending on your device orientation. If your article is being viewed in portrait orientation, the calculation is based on the height of the viewport; in landscape, the calculation is based on the width of the viewport.

For example, if the viewport is narrow and tall (portrait), a value of 150vmax is calculated as 150% of the height. The following example sets the component’s minimum height to 25% of the longest side of the viewport.

"minimumHeight": "25vmax"

Set Component Height Based on Component Width

Use the component width (cw) unit to set a component’s height as a percentage of the component’s width, which guarantees a specific aspect ratio. This example calculates the value.

height ÷ width * 100 

For example, for a landscape image with a 9:16 aspect ratio, you calculate 9 ÷ 16 * 100, for a value of 56.25cw. This example sets the component’s height to 50% of its width.

"minimumHeight": "50cw"

Set Component Width Based on Parent Component Width

Use the parent width (pw) unit to set minimumWidth or maximumWidth in relation to the width of the parent component. If you use the pw unit on a top-level component inside a document that does not have a parent, the viewport width (vw) is used.

"minimumWidth": "30pw", "maximumWidth": "50pw"

Set Component Margins Based on Gutter Size

Use the gut unit to base a component’s margin on the column gutter size. This example sets the component’s margin to the full width of the gutter.

"margin": {
  "bottom": "100gut"
}

Use the dg unit to base a component’s margin on the column gutter size. This example sets the component’s margin to the full width of the gutter.

"margin": {
  "bottom": "100dg"
}

This example sets the component’s margin to half the width of the gutter.

"margin": {
  "bottom": "50dg"
}

Set Vertical Margins for a Component

The margin property in the layout object provides the spacing for the outer left and right sides of the document and can change depending on the device size. To apply that same spacing vertically, use the dm unit in the margin property in the component layout object.

This example creates a vertical margin between components that is 100% of the left margin of the document.

"margin": "100dm"

This example creates a vertical margin that’s 50% of the left margin of the document.

"margin": "50dm"

See Also

Component Measurements and Media Guidelines

type SupportedUnits

The units of measurement supported by Apple News Format.