Heading
A responsive heading renderer that maps a visual size scale onto the correct semantic HTML heading element. Supports fluid typography, colour, alignment, weight, and ellipsis truncation.
Properties
| Name | Type | Default | Description |
|---|---|---|---|
size | 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'inherit' | 'h2' | Visual size and inferred semantic heading level. Determines the rendered HTML tag when no explicit tag prop is given. |
tag | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'div' | undefined | Override the rendered HTML tag. If omitted, the tag is inferred from the size prop. Use to decouple visual size from semantic heading level. |
weight | 'semibold' | 'bold' | 'bold' | Font weight. |
align | 'start' | 'center' | 'end' | 'start' | Horizontal text alignment. start and end are RTL-aware. |
color | 'primary' | 'secondary' | 'inherit' | 'primary' | Colour alias. inherit passes through the surrounding text colour unchanged — useful inside styled containers. |
ellipsis | boolean | false | Clips overflow text to a single line with a trailing ellipsis. The host element must have a defined width. |
theme | 'dark' | 'light' | 'dark' | Per-component theme override. Sets data-theme on the host so token overrides cascade into the shadow DOM. |
Events
diwa-heading is a non-interactive display component and emits no events.
Slots
| Slot | Description |
|---|---|
default | Heading text content. Inline elements (strong, em, span) are permitted. Do not slot block-level elements — the heading element cannot contain block-level children. |
CSS custom properties
These properties can be set on the diwa-heading host element to override styles at the component level without modifying global design tokens.
| Property | Default | Description |
|---|---|---|
--diwa-heading-font-size | From size prop | Overrides the computed fluid font size. Accepts any valid CSS length or font-size value. |
--diwa-heading-letter-spacing | From size prop | Overrides the letter-spacing. Default is -0.03em for display/h1, -0.015em for h2/h3, and 0 for h4–h6. |
--diwa-heading-line-height | var(--diwa-line-height-tight) | Overrides the line-height. Defaults to the tight token (1.1) for compact heading stacks. |
--diwa-heading-color | From color prop | Overrides the text colour. Accepts any valid CSS colour value or token reference. Ensure the override meets WCAG contrast requirements. |
Auto-tag behaviour
The component resolves the HTML tag to render using the following priority order:
| Condition | Rendered tag |
|---|---|
| A direct child of the slot is an h1–h6 element | div |
| The tag prop is explicitly set | Value of tag prop |
| size is display | h1 |
| size is h1–h6 | Matching h1–h6 element |
| size is inherit | h2 |