XDS — Design System

XDSHeading@xds/core · Text

Usage

Text renders styled body text and headings from the theme. Use XDSText with a semantic type for body copy, labels, and captions, and XDSHeading for section titles that output the correct h1–h6 element.

Best practices

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.

Import

ts
import {XDSHeading} from '@xds/core/Text'

Props

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.

Examples

Common configurations, variations, and states.

Heading — Card GridResponsive card grid with truncated headings and descriptions for uniform layout

tsx
'use client';
import {XDSHeading, XDSText} from '@xds/core/Text';
const cards = [
  {
    title: 'Very Long Card Title That Gets Truncated',
    updated: '1 hour ago',
  },
  {
    title: 'Another Card',
    updated: '2 hours ago',
  },
  {
    title: 'Third Card With An Even Longer Title That Will Be Truncated',
    updated: '3 hours ago',
  },
];
export default function HeadingCardGrid() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fill, minmax(250px, 1fr))',
        gap: 16,
        maxWidth: 800,
      }}>
      {cards.map(card => (
        <div
          key={card.title}
          style={{
            padding: 16,
            borderRadius: 8,
            border: '1px solid #e0e0e0',
            boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
          }}>
          <XDSHeading level={3} maxLines={1}>
            {card.title}
          </XDSHeading>
          <XDSText type="body" maxLines={2} display="block">
            This is a card description that might be quite long and needs to be
            truncated after two lines to keep the card compact and uniform.
          </XDSText>
          <XDSText type="supporting" display="block">
            Updated {card.updated}
          </XDSText>
        </div>
      ))}
    </div>
  );
}

Heading — Page HierarchyReal-world page layout demonstrating heading levels h1 through h3 with supporting text

tsx
'use client';
import {XDSHeading, XDSText} from '@xds/core/Text';
export default function HeadingPageLayout() {
  return (
    <div style={{maxWidth: 800}}>
      <XDSHeading level={1}>Dashboard Overview</XDSHeading>
      <XDSText type="supporting" display="block">
        Last updated 5 minutes ago
      </XDSText>
      <div style={{marginTop: 32}}>
        <XDSHeading level={2}>Recent Activity</XDSHeading>
        <XDSText type="body" display="block">
          Here's what's been happening in your workspace.
        </XDSText>
      </div>
      <div style={{marginTop: 24}}>
        <XDSHeading level={3}>Today</XDSHeading>
        <XDSText type="body" display="block">
          • Project Alpha updated
          <br />
          • 3 new comments
          <br />• Task completed
        </XDSText>
      </div>
    </div>
  );
}

Heading — TruncationSingle-line and multi-line heading truncation with ellipsis for constrained layouts

tsx
'use client';
import {XDSHeading} from '@xds/core/Text';
export default function HeadingTruncation() {
  return (
    <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>
      <div style={{width: 300, border: '1px solid #ccc', padding: 12}}>
        <XDSHeading level={2} maxLines={1}>
          Very Long Heading That Will Be Truncated To One Line With Ellipsis
        </XDSHeading>
      </div>
      <div style={{width: 300, border: '1px solid #ccc', padding: 12}}>
        <XDSHeading level={2} maxLines={2}>
          Very Long Heading That Will Be Truncated To Two Lines To Keep Card
          Layout Compact
        </XDSHeading>
      </div>
    </div>
  );
}

Showcase source

tsx
'use client';
import {XDSHeading} from '@xds/core/Text';
export default function HeadingShowcase() {
  return <XDSHeading level={1}>Dashboard Overview</XDSHeading>;
}