Heading
Semantic heading component that renders h1-h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Heading
Semantic heading component that renders h1-h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.
| Prop | Type | Default | Description |
|---|---|---|---|
| level * | 1 | 2 | 3 | 4 | 5 | 6 | Heading level. Determines the semantic HTML element (h1-h6) and the visual styling from the theme (unless type is set). | |
| type | 'display-1' | 'display-2' | 'display-3' | Display type variant. Overrides the visual styling from level with display-scale sizing (larger, lighter weight, tighter line-height). Themes may add custom visual types. The level still determines the HTML element for accessibility. Use for hero banners, marketing headlines, and data callouts. | |
| weight | 'normal' | 'medium' | 'semibold' | 'bold' | Explicit font-weight override. Wins over the selected visual type or heading-level default. | |
| children * | 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' | 'accent' | 'inherit' | 'primary' | Text color. Themes may add custom colors. |
| display | 'inline' | 'block' | 'block' | Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true. |
| maxLines | number | 0 | Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated. |
| hasTruncateTooltip | boolean | 'above' | 'below' | 'start' | 'end' | true | Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' | 'below' | 'start' | 'end') 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. | |
| justify | 'start' | 'center' | 'end' | 'start' | Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility. |
| hasCapsize | boolean | false | Enable optical alignment using text-box-trim. Forces block display. |
| hasStrikethrough | boolean | false | Apply strikethrough text decoration. |
| id | string | HTML id attribute. |
Theming API
{
"targets": [
{
"className": "astryx-heading",
"visualProps": [
"level",
"color",
"type",
"weight"
]
}
]
}
Examples
- Heading:
- Heading — Card Grid: Responsive card grid with truncated headings and descriptions for uniform layout
- Heading — Page Hierarchy: Real-world page layout demonstrating heading levels h1 through h3 with supporting text
- Heading — Truncation: Single-line and multi-line heading truncation with ellipsis for constrained layouts