--- title: ComponentTextStyle framework: applenewsformat role: symbol role_heading: Object path: applenewsformat/componenttextstyle --- # ComponentTextStyle The object for defining the style for a text component, including spacing, alignment, and drop caps. ## Declaration ```data object ComponentTextStyle ``` ## Properties backgroundColor: The background color for text lines. The value defaults to transparent. Use the none value 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. Use the none value for conditional design elements. Adding it here has no effect. firstLineIndent: 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 Applying Apple News Format Fonts. You can use the value system to show text in the default font the operating system uses. fontName: 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 you use. See Applying Apple News Format Fonts. fontScaling: 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: The size of the font, in points. By default, Apple News applies the font size from a containing 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 and iPadOS devices with Larger Accessibility Sizes enabled. fontStyle: The font style to apply. Valid values: normal. Selects a font defined as normal from the font family. italic. Selects a font defined as italic from the font family. If the family doesn’t contain an italic font variant, but contains an oblique variant, then Apple News selects oblique instead. oblique. Selects a font defined as oblique from the font family. If the family doesn’t contain an oblique font variant, but contains an italic variant, then Apple News selects italic . fontWeight: The font weight to apply for font selection. In addition to specific 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 Apple News can’t find a font variant with the given specifications in the provided font family, it selects an alternative with the closest match. If Apple News doesn’t find a bold/bolder font, it doesn’t create a faux-bold alternative, and instead uses the closest match. Similarly, if Apple News can’t find an italic or oblique font variant, it won’t slant text or make it 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 you don’t define a weight or a weight isn’t 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 or 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 bold, using a value of lighter makes text medium weight. bolder. A weight heavier than its surrounding text. When surrounding text is light, using a value of bolder makes text regular weight. fontWidth: 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: A Boolean value that defines whether Apple News positions punctuation outside the margins of the text. hyphenation: A Boolean value that indicates whether Apple News hyphenates text when necessary. By default, only components with a role of body or intro have hyphenation enabled. All other components default to false. hyphenationMinimumCharactersAfter: note: Available in iOS 17, iPadOS 17, and macOS 14 beta release. The minimum number of characters required after the hyphen to enable hyphenation. hyphenationMinimumCharactersBefore: note: Available in iOS 17, iPadOS 17, and macOS 14 beta release. The minimum number of characters required before the hyphen to enable hyphenation. hyphenationMinimumWordLength: note: Available in iOS 17, iPadOS 17, and macOS 14 beta release. The minimum number of characters required for a word to be hyphenated. hyphenationZone: note: Available in iOS 17, iPadOS 17, and macOS 14 beta release. The area in points from the right edge of the text component before which a word needs to start to enable hyphenation. By default, the value is set to 18 points. A larger value reduces the allowable hyphenation area of a word, which can result in a more ragged appearance of the text along the right margin. lineBalancing: note: Available in iOS 17, iPadOS 17, and macOS 14 beta release. A Boolean value that defines whether the system enables line balancing for the text component. lineHeight: A number that provides the default line height, in points. Apple News recalculates lineHeight as necessary, relative to the fontSize. For example, when Apple News automatically resizes the font to fit a smaller screen, it also readjusts the line height accordingly. linkStyle: An object that provides text styling for all links within a text component. Use the none value 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 Apple News displays the list items inside
    tags. Use the none value for conditional design elements. Adding it here has no effect. paragraphSpacingAfter: A number that defines the spacing after each paragraph in points relative to the lineHeight. paragraphSpacingBefore: 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, Apple News omits the stroke. Use the none value for conditional design elements. Adding it here has no effect. textAlignment: The justification for all text within the component. If you omit textAlignment or set it to none, Apple News determines the justification 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. textShadow: The text shadow for this style. Use the none value for conditional design elements. Adding it here has no effect. textTransform: The transform to apply to the text. Valid values: uppercase lowercase capitalize. Capitalizes the first letter of all words in the string. smallcaps. Capitalizes the lowercase letters as small capital letters. none (default) tracking: The amount of tracking (spacing between characters) in text, as a percentage of the fontSize. Apple News determines the actual spacing between letters by combining information from the font and font size. Example: Set tracking to 0.5 to make the distance between characters increase by 50 percent 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. unorderedListItems: The object for use with text components with HTML markup. You can create text styles containing an unorderedListItems definition to configure how Apple News displays the list items inside
      tags. Use the none value for conditional design elements. Adding it here has no effect. verticalAlignment: 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. ## Mentioned in Enhancing Your Articles with Styles Defining and Applying Text Styles Positioning the Content in Your Article Supporting Dark Mode for Your Article ## Discussion 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 multiple components can use: Include a property, with a name that you define and a ComponentTextStyle object value, in the ArticleDocument.componentTextStyles object. Use the name you created as the value of the individual component’s textStyle property. To create a default text style for the article, define a component text style in ArticleDocument.componentTextStyles object and use the key default. To create a default component text style for a role, define a component text style in ArticleDocument.componentTextStyles and use the key default-. For example, if you define a component text style with the key default-title, all components with a role of title 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. You can use this object 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 - [TextStyle](applenewsformat/textstyle.md) ## See Also ### Related Documentation - [Creating Your First Article](applenews/creating-your-first-article.md) ### Text Styles - [Defining and Applying Text Styles](applenews/defining-and-applying-text-styles.md) - [Applying Apple News Format Fonts](applenews/applying-apple-news-format-fonts.md) - [TextStyle](applenewsformat/textstyle.md) - [DropCapStyle](applenewsformat/dropcapstyle.md) - [ListItemStyle](applenewsformat/listitemstyle.md) - [InlineTextStyle](applenewsformat/inlinetextstyle.md)