TextMask
Renders text with a gradient or image as a transparent fill via background-clip: text. Supports animated gradients (pan, rotate, pulse, zoom).
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-text-mask> — single root element with background-clip: text. The text content is preserved in the DOM; the gradient/image visual is CSS-only.- 1.origam-text-mask
- Root element (span by default). Sets background-image, background-clip:text and -webkit-text-fill-color:transparent. Animation classes are added when animated=true.
API
Props
All props accepted by this component, with their type, default value and description.
- textstring
- Text to mask. Ignored when the default slot is provided.
- backgroundrequiredstring | IGradient
- REQUIRED. Background painted through the text glyphs. Accepts: a structured IGradient object (intent-aware), a raw CSS gradient string (linear-gradient/radial-gradient/conic-gradient), a preset name (gradient-sunset → var(--origam-gradient---{slug})), or an url(...) image.
- animatedbooleanfalse
- Enables CSS keyframe animation on the background. Pair with animationType.
- animationDurationstring'3s'
- Duration of one animation cycle. Any CSS <time> value (3s, 750ms, …).
- Animation strategy: 'pan' (horizontal pan), 'rotate' (hue-rotate), 'pulse' (size pulse), 'zoom' (scale zoom).
- text-align of the masked content: 'left', 'center', or 'right'.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring'span'
- HTML element rendered at root. Defaults to span; use div for block display.
- fontFamilyTFontFamily'inherit'
- font-family stack applied to the masked text.
- fontSizeTFontSize'inherit'
- font-size of the masked text. Numbers are interpreted as px.
- fontWeightTFontWeight'inherit'
- font-weight of the masked text. Accepts numeric weights (100–900) or keywords.
- lineHeightTLineHeight1.1
- line-height applied to the masked text. Tight by default for large display text.
- letterSpacingTLetterSpacing
- letter-spacing applied to the masked text. Defaults to the CSS initial value.
- fontStylestring
- textTransformTTextTransform
API
Slots
Content slots exposed by this component.
- #default
- Rich content to mask (wins over the text prop). Accepts multiple lines, nested <span>, <h1>, <em>… The DOM text is preserved for screen readers and search engines.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- ComputedRef<string>
- The resolved background-image CSS value (gradient or url()). Derived from the background prop after resolveGradient() processing.
- ComputedRef<boolean>
- True when the default slot is provided. When false, the text prop is rendered.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Resolved background-image value (gradient or url()). Set from the background prop.
- Animation cycle duration. Maps to animationDuration prop.
- Font size of the masked text.
- Font weight of the masked text.
- Font family of the masked text.
- Line height of the masked text.
- Letter spacing of the masked text.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Notes
- The text content is preserved in the DOM as plain text (or semantic slot content). The background-clip:text transform is purely CSS — screen readers and search engines read the real text.
- All CSS animations are disabled under prefers-reduced-motion: reduce. The background-size reverts to cover so the gradient is still visible.
- Gradient backgrounds may produce low-contrast regions. Verify WCAG AA contrast ratios for the minimum-contrast point of the gradient. Add a fallback color for browsers that do not support background-clip:text.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- dimensionvar(--origam-font__size---5xl)
- Reference display font size used in the DS story defaults.
- fontWeightvar(--origam-font__weight---bold)
- Reference font weight used in the DS story defaults.
- numbervar(--origam-font__lineHeight---tight)
- Tight line-height suited to large display text.
- duration3s
- Default animation cycle duration.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Gradient text
Animated gradient
Image clipping