TextMask
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.
<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.
- textstring
- Text to mask. Ignored when the default slot is provided.
- backgroundrequisstring | 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
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
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.
- 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.
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
Animated gradient
Image clipping