TextMask

Data Display
stable

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.

Anatomy of OrigamTextMaskSchematic of the TextMask component — root with inline background-clip style. Hello World 1 origam-text-mask background-clip: text · -webkit-text-fill-color: transparent
Anatomy of <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.

text
string
Text to mask. Ignored when the default slot is provided.
background
required
string | 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.
animated
boolean
false
Enables CSS keyframe animation on the background. Pair with animationType.
animationDuration
string
'3s'
Duration of one animation cycle. Any CSS <time> value (3s, 750ms, …).
animationType
'pan'
Animation strategy: 'pan' (horizontal pan), 'rotate' (hue-rotate), 'pulse' (size pulse), 'zoom' (scale zoom).
align
'left'
text-align of the masked content: 'left', 'center', or 'right'.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
tag
string
'span'
HTML element rendered at root. Defaults to span; use div for block display.
fontFamily
TFontFamily
'inherit'
font-family stack applied to the masked text.
fontSize
TFontSize
'inherit'
font-size of the masked text. Numbers are interpreted as px.
fontWeight
TFontWeight
'inherit'
font-weight of the masked text. Accepts numeric weights (100–900) or keywords.
lineHeight
TLineHeight
1.1
line-height applied to the masked text. Tight by default for large display text.
letterSpacing
TLetterSpacing
letter-spacing applied to the masked text. Defaults to the CSS initial value.
fontStyle
string
textTransform
TTextTransform

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

(none — inline text)

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.

Source
dimension
var(--origam-font__size---5xl)
Reference display font size used in the DS story defaults.
fontWeight
var(--origam-font__weight---bold)
Reference font weight used in the DS story defaults.
number
var(--origam-font__lineHeight---tight)
Tight line-height suited to large display text.
duration
3s
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

vue

Animated gradient

vue

Image clipping

vue