MotionText

Overview

TxMotionText preserves the 45 original Amicro catalog IDs and seven independent registry/source additions. Each preset keeps its own direction, grouping, stagger, scale, blur, mask, 3D transform or continuous rhythm. MOTION_TEXT_VARIANTS provides typed names, groups, segmentation and fixed source references; MOTION_TEXT_VARIANT_IDS is the complete ID list.

Entrance and decorative playback are separate from value changes. A mounted TxTextMorph owns every text update; there is no second diff engine and replay does not remount it. The original is exposed to screen readers once. Only one text layer is selectable: the decorative original during normal playback, the unchanged original during scramble, and the TextMorph layer at rest. Whitespace, newlines, emoji ZWJ sequences and combining marks are retained.

Usage

All source variants

Select any of the 52 IDs in the live catalog, filter by group/name/ID, use Next to traverse them, edit multilingual text, or replay repeatedly. Hover presets respond to individual graphemes/words and support keyboard focus. Pause restores the complete readable text, including during typewriter and scramble playback.

Source interactions

Scramble is real hover/focus-driven substitution, not a static title. It can reveal from the start, end or center using whole graphemes, and can use the original character pool or caller-supplied characters. Whitespace is never scrambled. focus-blur takes caller items: links remain native links and items without href are buttons emitting select. The hovered/focused item remains sharp while peers soften; focus brackets use the shared spring.

<TxMotionText
  text="保留 👩🏽‍💻 和 é"
  variant="scramble-hover"
  sequential
  reveal-direction="center"
  :use-original-chars-only="false"
  characters="ABC123✦"
/>
<TxMotionText
  variant="focus-blur"
  :items="[
    { id: 'design', label: 'Design', href: '/design' },
    { id: 'motion', label: 'Motion' },
  ]"
  @select="item => selectedId = item.id"
/>

Inline media uses caller mediaSrc, image/video properties, or the media slot. With the default hover trigger, leaving both pointer and keyboard focus closes the media. trigger="manual" uses the exposed animate()/reset() methods; trigger="in-view" opens on visibility. Reduced motion reveals media immediately without a width/scale animation. Built-in and slotted videos pause when motion is inactive or the media closes; slotted media receives active and open for its own resource lifecycle.

<TxMotionText
  variant="media-between-text"
  first-text="Crafting"
  second-text="experiences"
  :media-src="imageUrl"
  media-alt="Abstract texture"
/>
<TxMotionText variant="media-between-text" first-text="Your" second-text="media">
  <template #media="{ active, open }">
    <img :src="imageUrl" alt="Caller illustration">
  </template>
</TxMotionText>

Best Practices

• Keep text, media and items caller-owned. No demo business data is embedded in the component.
• Keep the component mounted when replacing text. Use replayKey or replay() for decorative replay rather than keying the component by the value.
• Use a valid locale for Chinese word segmentation. Grapheme effects never split a family emoji or a combining mark; without Intl.Segmenter, decorative grapheme playback keeps the whole value as a safe unit.
• Hover effects are decoration, not action buttons. Use the native focus-blur items or a separate semantic control for navigation/actions.
• Use paused to stop all owned animations, scramble timeouts and video playback. Ambient effects run only while mounted, intersecting, document-visible, enabled and not reduced, including across KeepAlive suspension.
• The morph engine does not soft-wrap. Supply explicit newlines (text-reveal animates each line) or choose a wrapping text primitive for prose.
• Tracking presets converge to natural body spacing. Glow crossfades two static shadow layers, and hover colors change immediately rather than tweening.

API Reference

Props

Events

Slots

Exposed Methods

MotionTextProps, MotionTextItem, MotionTextVariant, MotionTextVariantInfo, MotionTextTrigger, MotionTextRevealDirection, MotionTextMediaSlotProps, MotionTextSlots, MotionTextExpose and TxMotionTextInstance are exported from @talex-touch/tuffex/motion-text.

Variant catalogue

CSS Variables

Ink, glow, focus, surfaces and rings use the existing --tx-* theme tokens.

Technologies

• Fixed upstream Amicro commit 43c29ce9cdd16459e3eab4992381b8d35b38776a; MIT, Copyright (c) 2026 SYED SUBHAN UDDIN.
• The 45 catalog rows map to src/data/textAnimations.ts and their individual src/components/text/AnimatedText.tsx branches. The four registry sources live in registry/ui/text/. Extra sources are ScrambleHover.tsx, MediaBetweenText.tsx, and both FocusBlur.tsx implementations. Exact ranges are exported in MOTION_TEXT_VARIANTS and shown by the demo.
• Implementation: motion-text/src/TxMotionText.vue, source trajectories in src/presets.ts, typed API in src/types.ts. Decorative WAAPI resources and the single scramble timeout have an idempotent cancel boundary through useMotionActivity; value changes reuse TxTextMorph, word grouping reuses stream-text/src/segment.ts, and spring easing reuses liquid/src/spring.ts.
• Typewriter is stepped by whole graphemes rather than cropping half a glyph. Spacing settles to natural body spacing. The two hover catalog IDs that share an upstream switch branch remain separately discoverable without pretending to have different source trajectories.
• This page documents implementation behavior; integration/build/browser acceptance is performed by the owning workflow, not claimed by this page.