Object

ComponentTextStyle

The object for defining the style for a text component, including spacing, alignment, and drop caps.

Properties

backgroundColor
*

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

The none value is used for conditional design elements. Adding it here has no effect.

conditional
*

An instance or array of component text style properties that can be applied conditionally, and the conditions that cause them to be applied.

dropCapStyle
*

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

The none value is used for conditional design elements. Adding it here has no effect.

firstLineIndent
integer

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

fontFamily
*

The font family to use for text rendering; for example, Gill Sans. Using a combination of fontFamily, fontWidth, 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 fontName to refer to an explicit font variant’s Postscript name, such as GillSans-Bold. Alternatively, you can use a combination of fontFamily, fontWeight, fontWidth and/or fontStyle to have 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, text in Apple News Format articles is scaled down when viewed on devices with screens that are narrower than the width specified in the document layout. This scaling effect occurs at a faster rate for heading roles (Title, Heading, and so on) than for body roles (Body, Byline, Caption, and so on).

To disable this effect, set fontScaling to false. When doing so, be mindful of how larger text appears on smaller devices and make use of conditions as appropriate. See ConditionalComponentTextStyle.

fontSize
integer

The size of the font, in points. By default, the font size will be 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.

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, then 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, then italic is selected.

fontWeight
*

The font weight to apply for font selection. 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 its surrounding text.

If a font variant with the given specifications cannot be found in the provided font family, an alternative is selected that has the closest match. If no bold/bolder font is found, News will not create a faux-bold alternative, but will fall back to the closest match. Similarly, if no italic or oblique font variant is found, text will not be slanted to make text appear italicized.

Valid values:

  • thin or 100. Thin/hairline weight.

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

  • light or 300. Light weight.

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

  • medium or 500. Medium weight.

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

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

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

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

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

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

fontWidth
string

The font width to apply for font selection (known in CSS as font-stretch) defines the width characteristics of a font variant between normal, condensed and expanded. Some font families have separate families assigned for different widths (for example, Avenir Next and Avenir Next Condensed), so make sure that the fontFamily you select supports the specified fontWidth.

Valid values:

  • ultra-condensed. Specifies the most condensed variant.

  • extra-condensed. Specifies a very condensed variant.

  • condensed. Specifies a condensed variant.

  • semi-condensed. Specifies a semi-condensed variant.

  • normal (default). Specifies the font variant classified as normal.

  • semi-expanded. Specifies a semi-expanded variant.

  • expanded. Specifies an expanded variant.

  • extra-expanded. Specifies a very expanded variant.

  • ultra-expanded. Specifies the most expanded variant.

hangingPunctuation
boolean

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

hyphenation
boolean

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

lineHeight
integer

A number that provides the default line height, in points. The lineHeight is recalculated as necessary, relative to the fontSize. For example, when the font is automatically resized to fit a smaller screen, the line height will also be adjusted accordingly.

linkStyle
*

An object that provides text styling for all links within a text component.

The none value is used for conditional design elements. Adding it here has no effect.

orderedListItems
*

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

The none value is used for conditional design elements. Adding it here has no effect.

paragraphSpacingAfter
integer

A number that defines the spacing after each paragraph in points relative to the lineHeight.

paragraphSpacingBefore
integer

A number that defines the spacing before each paragraph in points relative to the lineHeight.

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.

stroke
*

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

The none value is used for conditional design elements. Adding it here has no effect.

textAlignment
string

The justification for all text within the component.

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

textColor

The text color.

textShadow
*

The text shadow for this style.

The none value is used for conditional design elements. Adding it here has no effect.

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 fontSize. 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. This style can be used for links. Set underline to true to use the text color as the underline color, or provide a text decoration with a different color.

unorderedListItems
*

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

The none value is used for conditional design elements. Adding it here has no effect.

verticalAlignment
string

The vertical alignment of the text. You can use this property for superscripts and subscripts.

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 a ComponentTextStyle object to define the text style for an entire text component (such as body or heading). A ComponentTextStyle object can have the same properties as a TextStyle object, as well as some additional properties such as a drop cap and text alignment.

To use a ComponentTextStyle once:

  • Include a ComponentTextStyle object as the value of the individual component’s style property.

To define a style that can be used by multiple components:

  1. Include a property, with a name that you define and a ComponentTextStyle object value, in the ArticleDocument.componentTextStyles object.

  2. Use the name you created as the value of the individual component’s textStyle property.

To create a default text style for the article:

To create a default component text style for a role:

  • Define a component text style in ArticleDocument.componentTextStyles and use the key default-<role>. For example, if you define a component text style with the key default-title, all components with a role of title will use that style, unless you override it.

For more information about properties, objects, keys, and values, see JSON Concepts and Article Structure. For more about components and roles, see Components.

This object can be used in Text and ArticleDocument.componentTextStyles.

Example

{ "componentTextStyles": { "exampleStyle": { "fontName": "HelveticaNeue", "fontSize": 20, "dropCapStyle": { "numberOfLines": 3, "numberOfRaisedLines": 2, "numberOfCharacters": 1, "fontName": "HelveticaNeue", "textColor": "#FFF", "backgroundColor": "#000", "padding": 5 } } }, "components": [ { "role": "body", "text": "This is body text", "textStyle": "exampleStyle" } ]}

Relationships

Inherits From

See Also

Text Styles

Defining and Applying Text Styles

Define and apply custom, default, and inline text styles, or use HTML tags or Markdown syntax to style your text.

About Apple News Format Fonts

See the iOS font families supported in Apple News Format.

object TextStyle

The object for defining the text style (font family, size, color, and so on) that you can apply to ranges of text.

object DropCapStyle

The object for defining the drop cap text style for use in the first paragraph in a text component.

object ListItemStyle

The object for defining the style for bulleted or numbered lists in an article.

object InlineTextStyle

The object for applying text styling when not using HTML or Markdown formatting.