Skip to content

Text ​

A versatile typography component with semantic variants for consistent text styling across your application. Provides complete control over typography with design system integration and accessibility built-in.

Variants ​

Body (Default) ​

Normal paragraph text with standard line height. The default variant for general content.

Full width

Heading ​

Emphasized text for headings with tighter line height and semibold weight. Defaults to md on the heading scale (--heading-md, 1.5rem / 24px): set size explicitly to pick a different step.

Heading scale vs body scale

variant="heading" maps the size attribute to the heading scale (--heading-xs → --heading-2xl) rather than the body text scale. This gives a much wider range: from 0.875rem (xs) all the way to 4rem (2xl). See Size Options for the full mapping.

Always set an explicit size when using variant="heading" to select the correct step from the heading scale: size="2xl" on a heading renders at 4rem (64px), not 1.5rem. Pair with as="h1"–as="h6" to get correct visual hierarchy and document semantics in one attribute set.

Full width

Label ​

Medium weight text for form labels and UI labels.

Full width

Caption ​

Smaller, secondary text for additional context or metadata. Use variant="caption" with color="muted" for helper text, timestamps, and metadata.

Full width

Overline ​

Uppercase text with letter spacing, ideal for categories or eyebrow text. Pair variant="overline" with size="xs" for category labels and eyebrow headings.

Full width

Code ​

Monospace text for inline code snippets.

Full width

Size Options ​

Choose from 7 size steps. The token scale resolved depends on the active variant:

sizeBody scale tokenValueHeading scale tokenValue
2xs--text-2xs11px(no heading step)11px
xs--text-xs12px--heading-xs14px
sm--text-sm14px--heading-sm16px
md--text-base16px--heading-md24px
lg--text-lg18px--heading-lg32px
xl--text-xl20px--heading-xl48px
2xl--text-2xl24px--heading-2xl64px

variant="heading" resolves sizes against the heading scale. All other variants (body, label, caption, overline, code) resolve against the body scale. The heading scale has no 2xs step, so size="2xs" resolves against the body scale even on a heading and renders at 11px.

--text-2xs (11px) is the legibility floor: never render component text below it.

Full width

Colors ​

Semantic Colors ​

Use semantic colors to convey meaning and maintain consistency. Do not rely on color alone to convey meaning: always pair with a descriptive text label.

Full width

Text Colors ​

Automatic text colors that adapt to your theme. Each value maps to a semantic --text-color-* token from the theme. Note that color="muted" resolves to --text-color-secondary (contrast-600) and may not meet AAA for small heading sizes.

colorTokenContrast stepWCAG
heading--text-color-heading--color-contrast-900AAA
body--text-color-body--color-contrast-800AAA
muted--text-color-secondary--color-contrast-600AA
tertiary--text-color-tertiary--color-contrast-500AA (large text)
disabled--text-color-disabled--color-contrast-400decorative only
contrast--text-color-contrast--color-contrast-100for dark backgrounds
Full width

Font Weights ​

Four weight options for emphasis control.

Full width

Text Alignment ​

Control text alignment for layout purposes.

Display behaviour

ore-text is display: block by default. as="span", as="label", and as="code" switch it to display: inline. The align attribute has no effect on these inline variants unless display: block is also applied.

Full width

Special Features ​

Truncate ​

Enable single-line truncation with ellipsis for overflow text. The truncate attribute is a boolean flag. Set a width constraint on the element or its container for truncation to apply.

Full width

Line Clamp ​

Clamp text to a fixed number of lines with an ellipsis: ideal for card descriptions and teasers. Use lines for multi-line truncation and truncate for single-line. They are mutually exclusive: lines takes precedence if both are present.

Full width

Expandable ​

expandable lets a reader tap or click clamped text to reveal the rest. Pair it with truncate or lines: without a clamp there is nothing to expand, and the dev build warns. The host takes role="button", tabindex="0", and aria-expanded, so keyboard users can toggle it with Enter or Space.

Full width

Every ore-text that is actually clipped mirrors its full text into a title attribute, so a pointer user can hover to read what the ellipsis hid. The title is dropped as soon as there is room, so it never shadows a real tooltip.

For a controlled disclosure (an accordion header, a "Show more" button elsewhere), set expanded and listen for expand-change; the component then only emits and never toggles itself.

html
<ore-text id="bio" lines="3" expandable expanded>…</ore-text>
<script>
  bio.addEventListener('expand-change', (e) => console.log(e.detail.expanded));
</script>

Italic Style ​

Apply italic styling to text.

Full width

Semantic HTML Tags ​

The as attribute controls document semantics. Use the as attribute to render a semantically correct element (h1–h6, p, label, code): especially inside forms, articles, and page headers. For h1–h6, the component automatically sets role="heading" and the correct aria-level on the host so screen readers announce the correct heading level without any extra markup. Changing as dynamically (e.g. by removing the attribute) removes both attributes.

Block elements (p, div, h1–h6) render as display: block. Inline elements (span, label, code) render as display: inline.

Full width

Combined Examples ​

Card Header ​

Combine multiple text components for rich layouts.

Full width

Form Field ​

Label with helper text pattern.

Full width

Status Messages ​

Use semantic colors for feedback.

Full width

Truncated Filename ​

Show file information with truncation using width constraints.

Full width

API Reference ​

Attributes ​

AttributeTypeDefaultDescription
variant'body' | 'heading' | 'label' | 'caption' | 'overline' | 'code'N/AText variant style
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'N/AFont size. variant="heading" resolves against --heading-* tokens; all other variants resolve against --text-* tokens
weight'normal' | 'medium' | 'semibold' | 'bold'N/AFont weight (falls back to variant default, then normal)
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error' | 'heading' | 'body' | 'muted' | 'tertiary' | 'disabled' | 'contrast'N/AText color (falls back to variant default, then inherit)
align'left' | 'center' | 'right' | 'justify'N/AText alignment (forces display: block)
truncatebooleanN/ASingle-line truncation with ellipsis
linesnumberN/AClamp to N lines with ellipsis (multi-line truncation)
expandablebooleanfalseReveal clamped text on click/tap; adds role="button" + aria-expanded. Pairs with truncate or lines
expandedbooleanN/AControlled expanded state. When set, the component shows this and only emits expand-change
default-expandedbooleanfalseInitial uncontrolled expanded state. Ignored when expanded is set
italicbooleanN/AItalic font style
as'span' | 'p' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label' | 'code'N/ASemantic element; h1–h6 auto-sets role="heading" + aria-level

Variant Defaults ​

VariantDefault sizeDefault weightDefault colorLine heightLetter spacing
body--text-base (16px)--font-normal (400)--text-color-body (contrast-800)--leading-normal (1.5)normal
heading--heading-md (24px)--font-semibold (600)--text-color-heading (contrast-900)--leading-tight (1.15)--tracking-header (-0.05em)
label--text-sm (14px)--font-medium (500)--text-color-heading (contrast-900)--leading-snug (1.375)normal
caption--text-sm (14px)--font-normal (400)--text-color-secondary (contrast-600)--leading-normal (1.5)normal
overline--text-xs (12px)--font-semibold (600)--text-color-body (contrast-800)--leading-none (1)0.08em
code--text-sm (14px)--font-normal (400)--text-color-body (contrast-800)--leading-normal (1.5)normal

Slots ​

SlotDescription
(default)Text content

Events ​

EventDetailFires when
expand-change{ expanded: boolean }An expandable text is toggled by the reader

CSS Custom Properties ​

PropertyDescriptionDefault
--text-sizeFont sizevar(--text-base)
--text-weightFont weightvar(--font-normal)
--text-colorText colorvar(--text-color-body)
--text-line-heightLine heightvar(--leading-normal)
--text-letter-spacingLetter spacingnormal

Accessibility ​

The text component follows WAI-ARIA best practices. It uses rem units throughout to respect the user's browser font size preferences, maintains WCAG-compliant line height (1.5 default for body text), and text colors maintain accessible contrast ratios with backgrounds.

When using as="h1" through as="h6", the component automatically sets role="heading" and the matching aria-level (1–6) on the host element. Screen readers announce the correct heading level without any extra markup. Changing as dynamically (e.g. by removing the attribute) removes both attributes.

Use the as attribute to give the element correct document semantics (h1–h6, p, label, etc.). as="span", as="label", and as="code" render as display: inline matching their native HTML counterparts.