ts
| Guidance | Practices |
|---|---|
| Do | Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight — the theme handles the details. |
| Do | Set accessibilityLevel on XDSHeading when the visual level differs from the document outline so screen readers announce the correct hierarchy. |
| Do | Use maxLines with a number to truncate long content — a tooltip appears automatically on hover so no text is lost. |
| Do | Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows. |
| Don't | Override size and weight when a semantic type already matches — extra overrides fight the theme and break when themes change. |
| Don't | Skip heading levels in the document outline — go h1 then h2 then h3, never h1 then h3. |
| Don't | Use raw HTML tags like <p>, <h1>–<h6>, or <span> for text — XDSText and XDSHeading apply the correct theme tokens automatically. |
| Prop | Type | Description |
|---|---|---|
levelrequired | 1 | 2 | 3 | 4 | 5 | 6 | Visual heading level. Determines both the HTML element (h1–h6) and the styling from the theme. |
childrenrequired | ReactNode | Heading content. |
accessibilityLevel | 1 | 2 | 3 | 4 | 5 | 6 | Accessibility level override. When set and different from `level`, applies `aria-level` so the document outline differs from the visual style. |
color | 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit' (default: 'primary') | Text color. |
display | 'inline' | 'block' (default: 'block') | Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true. |
maxLines | number (default: 0) | Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated. |
hasTruncateTooltip | boolean | LayerPlacement (default: true) | Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position. |
wordBreak | 'break-word' | 'break-all' | Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise. |
textWrap | 'wrap' | 'nowrap' | 'balance' | 'pretty' | Text wrapping behavior. |
hasCapsize | boolean (default: false) | Enable optical alignment using text-box-trim. Forces block display. |
hasStrikethrough | boolean (default: false) | Apply strikethrough text decoration. |
id | string | HTML id attribute. |
| Prop | Type | Description |
|---|---|---|
childrenrequired | ReactNode | Text content. |
type | 'body' | 'large' | 'label' | 'supporting' | 'code' (default: 'body') | Semantic text type. Determines size, weight, and line-height from the theme. |
size | '4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone. |
color | 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit' | Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. |
weight | 'normal' | 'medium' | 'semibold' | 'bold' | Font weight override. |
display | 'inline' | 'block' (default: 'inline') | Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true. |
as | 'span' | 'p' | 'div' | 'label' (default: 'span') | HTML element to render. |
maxLines | number (default: 0) | Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated. |
hasTruncateTooltip | boolean | LayerPlacement (default: true) | Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position. |
wordBreak | 'break-word' | 'break-all' | Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise. |
textWrap | 'wrap' | 'nowrap' | 'balance' | 'pretty' | Text wrapping behavior. |
hasCapsize | boolean (default: false) | Enable optical alignment using text-box-trim. Forces block display. |
hasStrikethrough | boolean (default: false) | Apply strikethrough text decoration. |
hasTabularNumbers | boolean (default: false) | Use tabular (monospace) numbers for aligned numeric data. |
id | string | HTML id attribute. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |