Text

The Text component displays textual information in a number of optional styles and variants.

You can learn more about this component in the Working with Text article.

Also note that variants of the Text component are also mapped to HtmlTag components. See the variant section to check which variant maps to which HtmlTag.

Custom Variants

In addition to the predefined variants, the Text component supports custom variant names that can be styled using theme variables. This allows you to create application-specific text styles without modifying the component itself.

When you use a custom variant name (one not in the predefined list), the component automatically applies theme variables following the naming pattern: {cssProperty}-Text-{variantName}.

<App>
  <Theme 
    textColor-Text-brandTitle="rgb(41, 128, 185)"
    fontSize-Text-brandTitle="28px"
    fontWeight-Text-brandTitle="bold"
    letterSpacing-Text-brandTitle="2px"
  >
    <Text variant="brandTitle">
      Welcome to Our Application
    </Text>
  </Theme>
</App>

<App>
  <Theme 
    textColor-Text-brandTitle="rgb(41, 128, 185)"
    fontSize-Text-brandTitle="28px"
    fontWeight-Text-brandTitle="bold"
    letterSpacing-Text-brandTitle="2px"
  >
    <Text variant="brandTitle">
      Welcome to Our Application
    </Text>
  </Theme>
</App>

In this example, the custom variant brandTitle is styled using theme variables. Any CSS text property can be configured, including textColor, fontSize, fontWeight, fontFamily, textDecoration*, lineHeight, backgroundColor, textTransform, letterSpacing, wordSpacing, textShadow, and more.

Behaviors

This component supports the following behaviors:

Properties

breakMode

default: "normal"

This property controls how text breaks into multiple lines. normal uses standard word boundaries, word breaks long words to prevent overflow, anywhere breaks at any character, keep prevents word breaking, and hyphenate uses automatic hyphenation. When not specified, uses the default browser behavior or theme variables.

Available values:

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">breakMode="normal" (default)</Text>
      <Text
        width="150px"
        backgroundColor="lightblue"
        padding="8px"
        breakMode="normal">
        This text uses standardwordbreaking at natural boundaries 
        like spaces and hyphens.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="word"</Text>
      <Text
        width="150px"
        backgroundColor="lightgreen"
        padding="8px"
        breakMode="word">
        This text will breakverylongwordswhenneeded to prevent 
        overflow while preserving readability.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="anywhere"</Text>
      <Text
        width="150px"
        backgroundColor="lightyellow"
        padding="8px"
        breakMode="anywhere">
        Thistext willbreakanywhereif neededtofit thecontainer 
        eveninthe middleofwords.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="keep"</Text>
      <Text
        width="150px"
        backgroundColor="lightcoral"
        padding="8px"
        breakMode="keep">
        This text will keep verylongwords intact and prevent 
        breaking within words entirely.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="hyphenate"</Text>
      <Text
        width="150px"
        backgroundColor="lavender"
        padding="8px"
        breakMode="hyphenate"
        lang="en">
        This text uses automatic hyphenation for 
        supercalifragilisticexpialidocious words.
      </Text>
    </VStack>
  </VStack>
</App>

<App>
  <VStack gap="16px">
    <VStack gap="8px">
      <Text variant="strong">breakMode="normal" (default)</Text>
      <Text
        width="150px"
        backgroundColor="lightblue"
        padding="8px"
        breakMode="normal">
        This text uses standardwordbreaking at natural boundaries 
        like spaces and hyphens.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="word"</Text>
      <Text
        width="150px"
        backgroundColor="lightgreen"
        padding="8px"
        breakMode="word">
        This text will breakverylongwordswhenneeded to prevent 
        overflow while preserving readability.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="anywhere"</Text>
      <Text
        width="150px"
        backgroundColor="lightyellow"
        padding="8px"
        breakMode="anywhere">
        Thistext willbreakanywhereif neededtofit thecontainer 
        eveninthe middleofwords.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="keep"</Text>
      <Text
        width="150px"
        backgroundColor="lightcoral"
        padding="8px"
        breakMode="keep">
        This text will keep verylongwords intact and prevent 
        breaking within words entirely.
      </Text>
    </VStack>
    
    <VStack gap="8px">
      <Text variant="strong">breakMode="hyphenate"</Text>
      <Text
        width="150px"
        backgroundColor="lavender"
        padding="8px"
        breakMode="hyphenate"
        lang="en">
        This text uses automatic hyphenation for 
        supercalifragilisticexpialidocious words.
      </Text>
    </VStack>
  </VStack>
</App>

ellipses

default: true

This property indicates whether ellipses should be displayed when the text is cropped (true) or not (false).

<App>
  <VStack width="120px">
    <Text
      backgroundColor="cyan"
      color="black"
      maxLines="1"
      ellipses="false">
      Though this long text does is about to crop!
    </Text>
    <Text
      backgroundColor="cyan"
      color="black"
      maxLines="1">
      Though this long text does is about to crop!
    </Text>
  </VStack>
</App>

<App>
  <VStack width="120px">
    <Text
      backgroundColor="cyan"
      color="black"
      maxLines="1"
      ellipses="false">
      Though this long text does is about to crop!
    </Text>
    <Text
      backgroundColor="cyan"
      color="black"
      maxLines="1">
      Though this long text does is about to crop!
    </Text>
  </VStack>
</App>

highlightActiveIndex

Which occurrence (0-based) of highlightText is the active match: it is emphasized and scrolled into view. Occurrences are counted across all terms in document order, matching Markdown, so a find-in-page stepping through a mixed list walks every match as one sequence regardless of which component rendered it. -1 or unset means none. With segments, counts over the hit segments instead.

Selects which occurrence of highlightText is the active match: it gets data-active="true", is styled with backgroundColor-markActive-Text, and is scrolled into view.

Occurrences are counted across all terms in document order, matching Markdown. That shared numbering is the point: a find-in-page stepping through a list of mixed Text and Markdown rows walks every match as one sequence, regardless of which component rendered it.

<App var.step="{0}">
  <HStack>
    <Button label="Previous" onClick="step = Math.max(0, step - 1)" />
    <Button label="Next" onClick="step = Math.min(2, step + 1)" />
    <Text value="Match {step + 1} of 3" />
  </HStack>
  <Text highlightText="pty" highlightActiveIndex="{step}">
    The pty ticker, the pty layer, and the pty menu.
  </Text>
</App>

<App var.step="{0}">
  <HStack>
    <Button label="Previous" onClick="step = Math.max(0, step - 1)" />
    <Button label="Next" onClick="step = Math.min(2, step + 1)" />
    <Text value="Match {step + 1} of 3" />
  </HStack>
  <Text highlightText="pty" highlightActiveIndex="{step}">
    The pty ticker, the pty layer, and the pty menu.
  </Text>
</App>

highlightText

When set, wraps every case-insensitive occurrence in the displayed text in a <mark> element (highlighted). Accepts a string (a single phrase) or a string array (each term highlighted independently). A term shorter than 2 characters, an empty string, or an empty array is a no-op. Matching is identical to Markdown's property of the same name, so a list mixing Text and Markdown rows highlights consistently.

Wraps matching text in <mark> elements, without the caller having to split the string into segments. Matching is identical to Markdown's property of the same name — case-insensitive, a string treated as one phrase, an array as independent terms, terms under 2 characters ignored — so a list mixing Text and Markdown rows highlights consistently.

<App>
  <Text highlightText="ticker">The pty ticker fires once per second.</Text>
  <Text highlightText="{['pty', 'ticker']}">The pty layer and the ticker.</Text>
</App>

<App>
  <Text highlightText="ticker">The pty ticker fires once per second.</Text>
  <Text highlightText="{['pty', 'ticker']}">The pty layer and the ticker.</Text>
</App>

Because the marks are rendered inside the Text element itself, a match falling in the middle of a word does not break the word, and styling set on the Text applies once rather than needing to be repeated per segment.

inline

default: false

When true, the component renders display: inline so a sequence of adjacent Text runs joins one line-breaking context and wraps as continuous text, breaking only at whitespace rather than between runs. Use it to compose per-run-styled segments (syntax colors, highlights) into a single flowing line. Inline mode is mutually exclusive with maxLines, ellipses, and overflowMode, which require a block formatting context and are ignored when inline is set.

By default a Text is display: inline-block, so a line built from several styled Text runs treats each run as an atomic box and may break between runs — splitting a word across a style boundary. Set inline="true" to render display: inline instead, so adjacent runs share one line-breaking context and wrap as continuous text, breaking only at whitespace.

Both blocks render the same sentence at the same width, differing only in inline. The highlighted Authentication sits mid-identifier (getUser + Authentication + Token). With inline="true" the whole identifier flows as one word and the line breaks only at the surrounding spaces; with the default inline-block each segment is an atomic box, so the line breaks inside the identifier — dropping part of it onto its own line.

<App>
  <VStack gap="$space-4" width="200px">
    <VStack gap="$space-1">
      <Text variant="strong" fontSize="$fontSize-sm">inline="true" — one flowing word</Text>
      <Text>Call <Text inline="true">getUser</Text><Text inline="true" backgroundColor="yellow" color="black" borderRadius="0">Authentication</Text><Text inline="true">Token</Text> before the request.</Text>
    </VStack>
    <VStack gap="$space-1">
      <Text variant="strong" fontSize="$fontSize-sm">default — inline-block splits the word</Text>
      <Text>Call <Text>getUser</Text><Text backgroundColor="yellow" color="black" borderRadius="0">Authentication</Text><Text>Token</Text> before the request.</Text>
    </VStack>
  </VStack>
</App>

<App>
  <VStack gap="$space-4" width="200px">
    <VStack gap="$space-1">
      <Text variant="strong" fontSize="$fontSize-sm">inline="true" — one flowing word</Text>
      <Text>Call <Text inline="true">getUser</Text><Text inline="true" backgroundColor="yellow" color="black" borderRadius="0">Authentication</Text><Text inline="true">Token</Text> before the request.</Text>
    </VStack>
    <VStack gap="$space-1">
      <Text variant="strong" fontSize="$fontSize-sm">default — inline-block splits the word</Text>
      <Text>Call <Text>getUser</Text><Text backgroundColor="yellow" color="black" borderRadius="0">Authentication</Text><Text>Token</Text> before the request.</Text>
    </VStack>
  </VStack>
</App>

Inline mode is for composing flowing rich text, so it is mutually exclusive with maxLines, ellipses, and overflowMode — those need a block formatting context and are ignored when inline is set.

maxLines

This property determines the maximum number of lines the component can wrap to. If there is no space to display all the contents, the component displays up to as many lines as specified in this property. When the value is not defined, there is no limit on the displayed lines.

<App>
  <Text
    maxWidth="120px"
    backgroundColor="cyan"
    color="black"
    value="A long text that will likely overflow"
    maxLines="2" />
</App>

<App>
  <Text
    maxWidth="120px"
    backgroundColor="cyan"
    color="black"
    value="A long text that will likely overflow"
    maxLines="2" />
</App>

overflowMode

default: "not specified"

This property controls how text overflow is handled. none prevents wrapping and shows no overflow indicator, ellipsis shows ellipses when text is truncated, scroll forces single line with horizontal scrolling, and flow allows multi-line wrapping with vertical scrolling when needed (ignores maxLines). When not specified, uses the default text behavior.

Available values:

Here are a few examples.

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    maxLines="2">
    This is a very long text that will be clipped with an 
    ellipsis indicator when it exceeds the specified lines.
  </Text>
</App>

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    maxLines="2">
    This is a very long text that will be clipped with an 
    ellipsis indicator when it exceeds the specified lines.
  </Text>
</App>

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="none"
    maxLines="2">
    This is a very long text that will be clipped cleanly without 
    any overflow indicator when it exceeds the specified lines.
  </Text>
</App>

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="none"
    maxLines="2">
    This is a very long text that will be clipped cleanly without 
    any overflow indicator when it exceeds the specified lines.
  </Text>
</App>

<App>
  <Text variant="strong">overflowMode="ellipsis" (default, maxlines='1')</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="ellipsis"
    maxLines="1">
    This is a very long text that will show ellipsis when it 
    overflows the container width.
  </Text>

  <Text variant="strong">overflowMode="ellipsis" (default, maxlines='2')</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="ellipsis"
    maxLines="2">
    This is a very long text that will show ellipsis when it 
    overflows the container width.
  </Text>
</App>

<App>
  <Text variant="strong">overflowMode="ellipsis" (default, maxlines='1')</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="ellipsis"
    maxLines="1">
    This is a very long text that will show ellipsis when it 
    overflows the container width.
  </Text>

  <Text variant="strong">overflowMode="ellipsis" (default, maxlines='2')</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="ellipsis"
    maxLines="2">
    This is a very long text that will show ellipsis when it 
    overflows the container width.
  </Text>
</App>

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="scroll">
    This is a very long text that will enable horizontal scrolling 
    when it overflows the container width.
  </Text>
</App>

<App>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="scroll">
    This is a very long text that will enable horizontal scrolling 
    when it overflows the container width.
  </Text>
</App>

<App>
  <Text variant="strong">overflowMode="flow"</Text>
  <Text
    width="200px"
    height="100px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="flow">
    This is a very long text that will wrap to multiple lines and show 
    a vertical scrollbar when the content exceeds the container height. 
    This mode ignores maxLines and allows unlimited text wrapping with 
    vertical scrolling when needed.
  </Text>
  
  <Text variant="strong">overflowMode="flow" (no height constraint)</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="flow">
    This is a very long text that demonstrates flow mode without a 
    height constraint. The text will wrap to multiple lines naturally 
    and the container will grow to accommodate all the content. No 
    scrollbar will appear since there's no height limitation - the text 
    flows freely across as many lines as needed.
  </Text>
</App>

<App>
  <Text variant="strong">overflowMode="flow"</Text>
  <Text
    width="200px"
    height="100px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="flow">
    This is a very long text that will wrap to multiple lines and show 
    a vertical scrollbar when the content exceeds the container height. 
    This mode ignores maxLines and allows unlimited text wrapping with 
    vertical scrolling when needed.
  </Text>
  
  <Text variant="strong">overflowMode="flow" (no height constraint)</Text>
  <Text
    width="200px"
    backgroundColor="lightblue"
    padding="8px"
    overflowMode="flow">
    This is a very long text that demonstrates flow mode without a 
    height constraint. The text will wrap to multiple lines naturally 
    and the container will grow to accommodate all the content. No 
    scrollbar will appear since there's no height limitation - the text 
    flows freely across as many lines as needed.
  </Text>
</App>

preserveLinebreaks

default: false

This property indicates if linebreaks should be preserved when displaying text.

<App>
  <HStack>
    <Text
      width="250px"
      backgroundColor="cyan"
      color="black"
      preserveLinebreaks="true"
      value="(preserve) This long text

      with several line breaks

              does not fit into a viewport with a 200-pixel width." />
    <Text
      width="250px"
      backgroundColor="cyan"
      color="black"
      preserveLinebreaks="false"
      value="(don't preserve) This long text

      with several line breaks

              does not fit into a viewport with a 200-pixel width." />
  </HStack>
</App>

<App>
  <HStack>
    <Text
      width="250px"
      backgroundColor="cyan"
      color="black"
      preserveLinebreaks="true"
      value="(preserve) This long text

      with several line breaks

              does not fit into a viewport with a 200-pixel width." />
    <Text
      width="250px"
      backgroundColor="cyan"
      color="black"
      preserveLinebreaks="false"
      value="(don't preserve) This long text

      with several line breaks

              does not fit into a viewport with a 200-pixel width." />
  </HStack>
</App>

Note: Remember to use the value property of the Text. Linebreaks are converted to spaces when nesting the text inside the Text component.

segments

Pre-computed highlight spans, as an array of { text, hit, active } objects. Use this instead of highlightText when the highlights are decided upstream rather than by matching a search term here — a full-text search snippet, for example, whose marks fall on token boundaries that cannot be reproduced by substring matching. Segments with hit are rendered as highlighted; active marks the current occurrence. A segment may instead carry variant, naming a non-search span kind (such as a changed word in a diff) styled through backgroundColor-mark-<variant>-Text. Precedence is active > hit > variant, so a segment that is a hit renders as a hit and its variant is ignored, and only hit segments are counted by highlightActiveIndex. When set, segments supplies the Text's content and highlightText is ignored.

Renders pre-computed highlight spans. Use this instead of highlightText when the highlights are decided upstream rather than by matching a term here.

The distinction matters more than it first appears. A full-text search snippet marks whole tokens after its own tokenization, and the excerpt that reaches the client has usually lost the context needed to re-derive those spans. Substring matching over the same text is not an approximation of that result — it disagrees in both directions, marking part of a token where the server marked all of it, and marking inside words where the server did not.

<App>
  <Text segments="{[
    { text: 'the ', hit: false },
    { text: 'ticker', hit: true },
    { text: ' fires once per ', hit: false },
    { text: 'second', hit: true, active: true }
  ]}" />
</App>

<App>
  <Text segments="{[
    { text: 'the ', hit: false },
    { text: 'ticker', hit: true },
    { text: ' fires once per ', hit: false },
    { text: 'second', hit: true, active: true }
  ]}" />
</App>

Each entry needs a text string. hit renders that span highlighted; active marks it as the current occurrence, styled with backgroundColor-markActive-Text and scrolled into view.

When segments is set it supplies the component's content — value and any children are not rendered, and highlightText is ignored (in a development build, setting both logs a warning). If segments is absent or undefined, the component renders its normal content, so a data-bound segments that is briefly undefined during a refetch degrades quietly rather than blanking the row.

If no segment carries active, highlightActiveIndex selects which hit is active, counting in document order — the same numbering highlightText uses, so a find-in-page can step through a list mixing both kinds of row as one sequence.

Precedence is active > hit > variant: a segment that is a search hit renders as one, and its variant is ignored. Only hit segments are counted by highlightActiveIndex, so variant spans never enter the sequence a find-in-page steps through.

A second span kind: variant

Some content carries spans that have nothing to do with searching — a word that changed on one side of a diff, say — and a row may hold those alongside search hits. Give such a segment a variant naming its kind:

<Text segments="{[
  { text: 'the ', hit: false },
  { text: 'quick', variant: 'emphasis' },
  { text: ' brown ', hit: false },
  { text: 'fox', hit: true, active: true }
]}" />

Colours come from your theme, keyed by the variant name:

backgroundColor-mark-emphasis-Text
textColor-mark-emphasis-Text

Declare those for every variant you use. An undeclared variant renders as plain text — the span is still there, just unstyled — and a development build warns once per name so a typo in a data-driven field does not pass silently.

This is deliberately not a general styling channel: exactly those two properties resolve, keyed by a name you declare in the theme, rather than arbitrary CSS travelling in your data.

Two namespaces here point in opposite directions, deliberately. In the DOM, a hit is a <mark> and a variant is a <span data-variant="…"> — they are different kinds of thing, and code that counts or queries marks to find search hits should not also collect diff spans. In the theme, both live under mark- (backgroundColor-mark-Text, backgroundColor-markActive-Text, backgroundColor-mark-emphasis-Text) — from a theme author's side they are one family of span styling to keep visually coherent.

value

The text to be displayed. This value can also be set via nesting the text into the Text component.

<App>
  <Text value="An example text" />
  <Text>An example text</Text>
</App>

<App>
  <Text value="An example text" />
  <Text>An example text</Text>
</App>

variant

An optional string value that provides named presets for text variants with a unique combination of font style, weight, size, color, and other parameters. If not defined, the text uses the current style of its context.

Available values:

HtmlTag Mappings

The table below indicates which Text variant maps to which HtmlTag component.

Events

contextMenu

This event is triggered when the Text is right-clicked (context menu).

Signature: contextMenu(event: MouseEvent): void

• event: The mouse event object.

Exposed Methods

hasOverflow

Returns true when the displayed text overflows its container boundaries.

Signature: hasOverflow(): boolean

Styling

Custom Variant Theme Variables

When using custom variants, you can style them using theme variables with the naming pattern {propertyName}-Text-{variantName}. The following CSS properties are supported:

<App>
  <Theme 
    textColor-Text-highlight="rgb(255, 193, 7)"
    fontWeight-Text-highlight="bold"
    backgroundColor-Text-highlight="rgba(0, 0, 0, 0.8)"
    padding-Text-highlight="4px 8px"
    textShadow-Text-highlight="0 2px 4px rgba(0,0,0,0.5)"
  >
    <Text variant="highlight">Important Notice</Text>
    <Text variant="highlight">This is Important Too</Text>
  </Theme>
</App>

<App>
  <Theme 
    textColor-Text-highlight="rgb(255, 193, 7)"
    fontWeight-Text-highlight="bold"
    backgroundColor-Text-highlight="rgba(0, 0, 0, 0.8)"
    padding-Text-highlight="4px 8px"
    textShadow-Text-highlight="0 2px 4px rgba(0,0,0,0.5)"
  >
    <Text variant="highlight">Important Notice</Text>
    <Text variant="highlight">This is Important Too</Text>
  </Theme>
</App>

Theme Variables