The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Text

Figma GitHub

A component that applies predefined typographic styles to a block of content.

The Text component is a code-only component used to apply specific predefined HDS typographic styles to a block of text or content.

The equivalent in Figma is not a component, but a set of typographic Figma styles.

How to use this component

The Text component is available in three different variants with a one-to-one association between the namespace (eg. ::Display) and the corresponding style in Figma.

Text as "Display" variant Text as "Body" variant Text as "Code" variant 
<Hds::Text::Display>Text as "Display" variant</Hds::Text::Display>
<Hds::Text::Body>Text as "Body" variant</Hds::Text::Body>
<Hds::Text::Code>Text as "Code" variant</Hds::Text::Code>

When no @tag argument is provided, the text element is rendered as a <span> by default.

HTML tag

To specify which HTML tag to use to render the element, use the @tag argument:

Page title

Paragraph text

Code sample
<Hds::Text::Display @tag="h1">Page title</Hds::Text::Display>
<Hds::Text::Body @tag="p">Paragraph text</Hds::Text::Body>
<Hds::Text::Code @tag="pre">Code sample</Hds::Text::Code>

While by default the component renders a <span>, we invite consumers to:

  • consider which semantic HTML tag is the correct one for the context in which the text is used
  • always set a @tag value accordingly, to make the semantic choice explicit

Size

To specify which size to apply to the text, use the @size argument:

Page title with "Display-500" variant

Paragraph text with "Body-300" variant-

Code sample with "Code-100" variant
<Hds::Text::Display @tag="h1" @size="500">Page title with "Display-500" variant </Hds::Text::Display>
<Hds::Text::Body @tag="p" @size="300">Paragraph text with "Body-300" variant-</Hds::Text::Body>
<Hds::Text::Code @tag="pre" @size="100">Code sample with "Code-100" variant</Hds::Text::Code>

Different style variants support different sizes: refer to the Component API section for details.

Weight

To apply a specific font weight to the text, use the @weight argument:

Level 4 heading with "medium" font weight

Paragraph text with "semibold" font weight 

Code sample with "bold" font weight
<Hds::Text::Display @tag="h4" @size="300" @weight="medium">Level 4 heading with "medium" font weight</Hds::Text::Display>
<Hds::Text::Body @tag="p" @weight="semibold">Paragraph text with "semibold" font weight </Hds::Text::Body>
<Hds::Text::Code @tag="pre" @weight="bold">Code sample with "bold" font weight</Hds::Text::Code>

Important

Different typographic styles support only a limited set of font weights. Refer to the Component API section to see what the allowed combinations are for the different styles.

Alignment

To specify a text alignment, use the @align argument:

Page title, right-aligned

Paragraph, center-aligned

Code sample, left-aligned
<Hds::Text::Display @tag="h1" @align="right">Page title, right-aligned</Hds::Text::Display>
<Hds::Text::Body @tag="p" @align="center">Paragraph, center-aligned</Hds::Text::Body>
<Hds::Text::Code @tag="pre" @align="left">Code sample, left-aligned</Hds::Text::Code>

Color

It is possible to apply a specific foreground color to the text (from a predefined list) using the @color argument:

Paragraph with "strong" color applied

Paragraph with "action-active" color applied

Paragraph with "highlight-high-contrast" color applied

<Hds::Text::Body @tag="p" @color="strong">Paragraph with "strong" color applied</Hds::Text::Body>
<Hds::Text::Body @tag="p" @color="action-active">Paragraph with "action-active" color applied</Hds::Text::Body>
<Hds::Text::Body @tag="p" @color="highlight-high-contrast">Paragraph with "highlight-high-contrast" color applied</Hds::Text::Body>

For the list of possible foreground colors supported, refer to the Component API section for details.

It’s also possible to provide a CSS color as string (in this case the color will be applied as inline style). The string can be a CSS var() that uses one of the predefined color tokens:

This text has a "blue-400" color applied

<Hds::Text::Body @tag="p" @color="var(--token-color-palette-blue-400)">This text has a "blue-400" color applied</Hds::Text::Body>

Or it can be one of the standard CSS color formats (hex, rgb, rgba, hsl, etc.):

This text has a "#FF0000" (red) color applied

<Hds::Text::Body @tag="p" @color="#FF0000">This text has a "#FF0000" (red) color applied</Hds::Text::Body>

We don’t validate the CSS color string to ensure that the value used is correct.

Structured content

Since the component is not prescriptive on the tags that can be used to render the text, it can be used to apply a typographic style not only to plain text but also to structured content:

This text contains some strong and em tags, a link.

<Hds::Text::Body @tag="p" @size="300">This text contains some <strong>strong</strong> and <em>em</em> tags, a <Hds::Link::Inline @href="#">link</Hds::Link::Inline>.</Hds::Text::Body>

We can imagine even more complex examples where we may want to apply a typographic style to an entire block of content:

This is some generic text in a paragraph.

  • this list item contains some strong and em tags
  • this list item contains a link

This is also some generic text in a paragraph.

<Hds::Text::Body @tag="div" @size="200" @color="strong">
  <p>This is some generic text in a paragraph.</p>
  <ul>
    <li>this list item contains some <strong>strong</strong> and <em>em</em> tags</li>
    <li>this list item contains a <Hds::Link::Inline @href="#">link</Hds::Link::Inline></li>
  </ul>
  <p>This is also some generic text in a paragraph.</p>
</Hds::Text::Body>

Notice

While this is technically possible, it’s not necessarily desirable (or correct in every possible context). Please be mindful of how the markup is structured, in terms of HTML semantics (for accessibility) as well as code readability (for the developers writing/reviewing/maintaining that code, now and in the future).

Component API

The Text component is used through these specialized variants: Hds::Text::Display, Hds::Text::Body, and Hds::Text::Code.

Text::Display

size string
  • 500
  • 400
  • 300
  • 200 (default)
  • 100
The size of the Display text style.
tag string
  • span (default)
HTML tag to be used to render the text element.
weight string
  • medium
  • semibold
  • bold
The font weight of the text. If no @weight argument is provided, the component will inherit its weight from the parent container/context.

Notice: not all the font weights can be used for all the font sizes (refer to the Typography section for details.). Below are the allowed combinations:
Display-500 → bold
Display-400 → medium, semibold, bold
Display-300 → medium, semibold, bold
Display-200 → semibold
Display-100 → medium
align string
  • left
  • center
  • right
The alignment of the text. If no @align argument is provided, the component will inherit its alignment from the parent container/context.
color string | CSS color
  • primary
  • strong
  • faint
  • disabled
  • high-contrast
  • action
  • action-hover
  • action-active
  • highlight
  • highlight-on-surface
  • highlight-high-contrast
  • success
  • success-on-surface
  • success-high-contrast
  • warning
  • warning-on-surface
  • warning-high-contrast
  • critical
  • critical-on-surface
  • critical-high-contrast
The color of the text expressed as one of the possible foreground color names. As a fallback solution to handle special cases, a valid CSS color string (hex, rgb, rgba, etc.) is also accepted (in this case the color will be applied via an inline style). If no @color argument is provided, the component will inherit its color from the parent container/context.
yield
Elements passed as children are yielded to the content of the <@tag> HTML element.
…attributes
This component supports use of ...attributes.

Text::Body

size string
  • 300
  • 200 (default)
  • 100
The size of the Body text style.
tag string
  • span (default)
HTML tag to be used to render the text element.
weight string
  • regular (default)
  • medium
  • semibold
The font weight of the text. If no @weight argument is provided, the component will inherit its weight from the parent container/context.
align string
  • left
  • center
  • right
The alignment of the text. If no @align argument is provided, the component will inherit its alignment from the parent container/context.
color string | CSS color
  • primary
  • strong
  • faint
  • disabled
  • high-contrast
  • action
  • action-hover
  • action-active
  • highlight
  • highlight-on-surface
  • highlight-high-contrast
  • success
  • success-on-surface
  • success-high-contrast
  • warning
  • warning-on-surface
  • warning-high-contrast
  • critical
  • critical-on-surface
  • critical-high-contrast
The color of the text expressed as one of the possible foreground color names. As a fallback solution to handle special cases, a valid CSS color string (hex, rgb, rgba, etc.) is also accepted (in this case the color will be applied via an inline style). If no @color argument is provided, the component will inherit its color from the parent container/context.
yield
Elements passed as children are yielded to the content of the <@tag> HTML element.
…attributes
This component supports use of ...attributes.

Text::Code

size string
  • 300
  • 200 (default)
  • 100
The size of the Code text style.
tag string
  • span (default)
HTML tag to be used to render the text element.
weight string
  • regular (default)
  • bold
The font weight of the text. If no @weight argument is provided, the component will inherit its weight from the parent container/context.
align string
  • left
  • center
  • right
The alignment of the text. If no @align argument is provided, the component will inherit its alignment from the parent container/context.
color string | CSS color
  • primary
  • strong
  • faint
  • disabled
  • high-contrast
  • action
  • action-hover
  • action-active
  • highlight
  • highlight-on-surface
  • highlight-high-contrast
  • success
  • success-on-surface
  • success-high-contrast
  • warning
  • warning-on-surface
  • warning-high-contrast
  • critical
  • critical-on-surface
  • critical-high-contrast
The color of the text expressed as one of the possible foreground color names. As a fallback solution to handle special cases, a valid CSS color string (hex, rgb, rgba, etc.) is also accepted (in this case the color will be applied via an inline style). If no @color argument is provided, the component will inherit its color from the parent container/context.
yield
Elements passed as children are yielded to the content of the <@tag> HTML element.
…attributes
This component supports use of ...attributes.

Conformance rating

Conditionally Conformant

Since this component is nothing more than a wrapper around generic HTML tags with custom typographic styles applied, any conformance issues that may arise will depend on how this component is used in the consumer’s code, in the same way as normal HTML tags and text would.

The importance of heading levels

Headings are used to describe the structure and organize the text content of a webpage. They should be brief, clear, and meaningful. Heading levels should be used in hierchical order without skipping levels. The h1 tag should come first in the order and be unique.

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

Related

On this page: