BlurText handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Reveal headings and short paragraphs one character at a time through sharpening, fade-in, and slight upward movement while preserving natural wrapping, font size, line height, and text baseline.

When to use it

Use Text for static content, BlurText for a blurred reveal, SlotText or FlowText for vertically changing text, and ScrambleText for character scrambling. BlurText accepts plain text, not a rich-text subtree, and does not interpret number or timer semantics. Prefer static Text for long prose to avoid the paint cost of per-character filters.

Quick start

<script lang="ts">  import { BlurText } from '@snowui-design-system/components';</script> <BlurText text="Let inspiration come into focus." size="--text-32" lineHeight="--leading-32" />

Typography Props inherit from the parent when omitted. You can also use class="text-32" directly without wrapping Text. A numeric size is in px; numeric lineHeight is a unitless multiplier. Use a Token or "40px" for a fixed line height.

API

Inherits applicable FrameProps. tag defaults to span; as still denotes the parent component role. Internal animation is layered separately from the root Frame’s while* motions; enableDefaultMotion={false} disables only the root default motion. Public speed changes character stagger in line with the reference site’s speedReveal; each character still lasts 600ms. There are no public duration, stagger, blur, or displacement parameters. A speed change applies on the next text update or replay, without restarting the current animation. Temporary-color timing scales with reveal speed; the return fade remains the shared 280ms.

Usage boundaries and details

Behavior and accessibility

• Initial playback and replayKey changes reveal the full text; a text update commits the latest content immediately and reveals it. During rapid updates, same-position characters still animating continue from their visible blur, opacity, and displacement. Old callbacks cannot replace new content. No numeric wheel or old-text exit animation runs.

• SSR and pages without JavaScript output the full text. With reduced motion or without the Web Animations API, content stays static and readable. All internal Animations are removed after completion.

• The root supplies a stable aria-label for the final text; the per-character visual layer is aria-hidden. Use tag="h2" or another semantic heading tag when appropriate. The default span uses an img role to expose the full text without reading each character separately.

• The browser’s inline layout determines wrapping. Chinese characters, English words, spaces, and explicit line breaks are not simulated with fixed per-character widths or extra margins. The browser also handles final font shaping, including ligatures.

Reference sources

• Local reference source: ../../../../github/ui/animations-master/ (relative to this document). The Blur Reveal example is in src/lib/components/spell/blur-reveal/blur-reveal.svelte.

• Original example: Svelte Animations · Blur Reveal.

• Reference site: Text Motion Observatory · References (ChatGPT sign-in required; this supplementary reference is not required to use the component).

The local source is used to inspect the blur-reveal motion; the reference site provides additional examples. The reference repository is neither built into SnowUI nor required at runtime.