Object

ConditionalComponentTextStyle

The object for defining conditional properties for a component text style, and when the conditional properties are in effect.

Properties

conditions
*
(Required)

An instance or array of conditions that, when met, cause the conditional component text style properties to take effect.

backgroundColor
*

The background color for text lines. This value defaults to transparent.

To remove a previously set condition, use none.

dropCapStyle
*

The style of drop cap to apply to the first paragraph of the component.

To remove a previously set condition, use none.

firstLineIndent
integer

The indent, in points, of the first line of each paragraph.

fontFamily
*

The font family to use for text rendering; for example, Gill Sans. Using a combination of fontFamily, fontWeight, and fontStyle, you can define the appearance of the text. Apple News automatically selects the appropriate font variant from the available variants in that family. See About Apple News Format Fonts.

In iOS 13 and macOS 10.15, you can use the value system to show text in the default font used by the operating system.

fontName
string

The font name to use to refer to an explicit font variant's PostScript name, such as GillSans-Bold. Alternatively, you can use a combination of fontFamily, fontWeight, and fontStyle to have Apple News automatically select the appropriate variant depending on the text formatting used.

See About Apple News Format Fonts.

fontScaling
boolean

A Boolean value that indicates whether scaling of font sizes for various screen sizes is enabled. By default, all font sizes in Apple News Format are scaled down on smaller screen sizes.

fontSize
integer

The size of the font, in points. By default, the font size is inherited from a parent component or a default style. As a best practice, try not to go below 16 points for body text. The fontSize may be automatically resized for different device sizes or for iOS devices with Larger Accessibility Sizes enabled.

fontStyle
string

The font style to apply for the selected font.

Valid values:

  • normal. Selects from the font family a font that is defined as normal.

  • italic. Selects from the font family a font that is defined as italic. If the family does not contain an italic font variant, but contains an oblique variant, oblique is selected instead.

  • oblique. Selects from the font family a font that is defined as oblique. If the family does not contain an oblique font variant, but contains an italic variant, italic is selected.

fontWeight
*

The font weight to apply for the selected font. In addition to explicit weights (named or numerical), lighter and bolder are available, to set text in a lighter or bolder font as compared to the surrounding text.

If a font variant with the given specifications cannot be found in the provided font family, the closest match is selected. If no bold or bolder font is found, Apple News does not create a faux-bold alternative, but falls back to the closest match. Similarly, if no italic or oblique font variant can be found, text is not slanted to make it appear italicized.

Valid values:

  • thin or 100. Thin or hairline weight.

  • extra-light, ultra-light or 200. Extra-light or ultra-light weight.

  • light or 300. Light weight.

  • regular, normal, book, roman, or 400. Regular weight. This is the default if no weight is defined or inherited.

  • medium or 500. Medium weight.

  • semi-bold, demi-bold, or 600. Semi-bold or demi-bold weight.

  • bold or 700. Bold weight. This is the default when using <strong> or <b> tags in HTML with default fontWeight.

  • extra-bold, ultra-bold, or 800. Extra-bold or ultra-bold weight.

  • black, heavy, or 900. Black or heavy weight.

  • lighter. A weight lighter than its surrounding text. When surrounding text is made bold, a value of lighter makes it medium.

  • bolder. A weight heavier than its surrounding text. When surrounding text is made light, a value of bolder makes it regular.

fontWidth
string

The font width for the selected font (known in CSS as font-stretch). This value defines the width characteristics of a font variant between normal, condensed, and expanded. Some font families are categorized by width (for example, Avenir Next and Avenir Next Condensed), so make sure that the font family you select supports the specified font width.

Valid values:

  • ultra-condensed. The most condensed variant.

  • extra-condensed. A very condensed variant.

  • condensed. A condensed variant.

  • semi-condensed. A semi-condensed variant.

  • normal (default). The font variant classified as normal.

  • semi-expanded. A semi-expanded variant.

  • expanded. An expanded variant.

  • extra-expanded. A very expanded variant.

  • ultra-expanded. The most expanded variant.

hangingPunctuation
boolean

A Boolean that defines whether punctuation should be positioned outside the margins of the body text.

hyphenation
boolean

A Boolean that indicates whether text should be hyphenated when necessary. By default, only components with the role body or intro have hyphenation enabled. All other components default to false.

lineHeight
integer

The default line height, in points. The line height is recalculated as necessary, relative to the font size. For example, when the font is automatically resized to fit a smaller screen, the line height is also adjusted accordingly.

linkStyle
*

Text styling for all links within a text component.

To remove a previously set condition, use none.

orderedListItems
*

An object for use with text components with HTML markup. You can create text styles containing an orderedListItems definition to configure how to display list items inside <ol> tags.

To remove a previously set condition, use none.

paragraphSpacingAfter
integer

An object that defines the spacing, in points, after each paragraph, relative to the line height.

paragraphSpacingBefore
integer

An object that defines the spacing, in points, before each paragraph, relative to the line height.

strikethrough
*

The text strikethrough. Set strikethrough to true to use the text color inherited from the textColor property as the strikethrough color, or provide a text decoration definition with a different color. By default, strikethrough is omitted (false).

stroke
*

The stroke style for the text outline. By default, stroke is omitted.

To remove a previously set condition, use none.

textAlignment
string

The justification for all text within the component.

If textAlignment is omitted or set to none, the justification is determined by the text direction (left-to-right text is aligned to the left, and right-to-left text is aligned to the right).

textColor

The text color to apply to the selected text.

textShadow
*

The text shadow for this style.

To remove a previously set condition, use none.

textTransform
string

The transform to apply to the text.

Valid values:

  • uppercase

  • lowercase

  • capitalize. Capitalizes the first letter of all words in the string.

  • none (default)

tracking
number

The amount of tracking (spacing between characters) in text, as a percentage of the font size. The actual spacing between letters is determined by combining information from the font and font size.

Example: Set tracking to 0.5 to make the distance between characters increase by 50% of the fontSize. With a font size of 10, the additional space between characters is 5 points.

underline
*

The text underlining. You can use this style for links. Set underline to true to use the text color as the underline color, or provide a text decoration with a different color. By default, underline is omitted (false).

unorderedListItems
*

An object for use with text components with HTML markup. You can create text styles containing an unorderedListItems definition to configure how to display list items inside <ul> tags.

To remove a previously set condition, use none.

verticalAlignment
string

The vertical alignment of the text. You can use this property for superscript and subscript.

To override values specified in parent text styles, use baseline.

Defaults to baseline when unspecified, and inherits the value specified in a TextStyle applied to the same range.

The values superscript and subscript also adjust the font size to 2/3 of the size defined for that character range.

Discussion

Use the ConditionalComponentTextStyle object to define an array of conditional component text style properties and the conditions under which to apply them. When a condition is met, the value of a property in ConditionalComponentTextStyle overrides the value of the same property if defined in the parent ComponentTextStyle object. See ComponentTextStyle.

Example

{ "components": [ { "role": "title", "text": "Lorem Ipsum Dolor Sit Amet", "textStyle": "exampleTextStyle" } ], "componentTextStyles": { "exampleTextStyle": { "fontSize": 24, "conditional": [ { "fontSize": 24, "conditions": [ { "minViewportWidth": 0 } ] }, { "fontSize": 48, "conditions": [ { "minViewportWidth": 415 } ] }, { "fontSize": 64, "conditions": [ { "minViewportWidth": 769 } ] } ] } }}

Relationships

Inherits From

See Also

Conditional Design Elements

object Condition

The object for defining a condition that, when met, causes conditional properties to go into effect.

object ConditionalComponent

The object for defining conditional properties for a component, and when the conditional properties are in effect.

object ConditionalComponentLayout

The object for defining conditional properties for a component layout, and when the conditional properties are in effect.

object ConditionalAutoPlacement

The object for defining conditional properties for an automatically placed component, and when the conditional properties are in effect.

object ConditionalSection

The object for defining conditional properties for a section component, and when the conditional properties are in effect.

object ConditionalText

The object for defining conditional properties for a text component, and when the conditional properties are in effect.

object ConditionalTextStyle

The object for defining conditional properties for a text style, and when the conditional properties are in effect.

object ConditionalComponentStyle

The object for defining conditional properties for a component style, and when the conditional properties are in effect.

object ConditionalContainer

The object for defining conditional properties for a container component, and when the conditional properties are in effect.

object ConditionalDivider

The object for defining conditional properties for a divider component, and when the conditional properties are in effect.