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

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

text
string
Text to mask. Ignored when the default slot is provided.
background
requis
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

Emplacements de contenu exposés par ce composant.

#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

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

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.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Rôles ARIA

(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.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

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.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Gradient text

vue

Animated gradient

vue

Image clipping

vue