SlotText handbook

v1.11.2 · @snowui-design-system/components

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

Show text changes with a vertical roll for each character, suitable for short headings, statuses, counts, and time displays.

When to use it

Use it for slot-style text replacement. Use Text for static copy; NumberFlow or NumericText for number-specific rolling.

text updates content, replayKey replays identical content, and playOnMount controls the initial animation.
animated={false} shows content immediately. Enable respectMotionPreference to honor the system reduced-motion setting.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Button, Text } from '@snowui-design-system/components';	import { SlotText, chromatic } from '@snowui-design-system/components';	const componentNames = ['Button', 'DataTable', 'SidePanel', 'Tooltip'];	let componentIndex = $state(0);</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4);">	<SlotText text={componentNames[componentIndex]} motionRole="text" motionColor={chromatic()} size="--text-32" lineHeight="--leading-32" weight={600} />	<Button onclick={() => componentIndex = (componentIndex + 1) % componentNames.length}>Next component</Button></div>

API

Keyword	Type	Default	Description
text	`string \| number`	`""`	Final text
direction	`SlotTextDirection`	—	Semantic direction for text and numbers; `normal` uses the shared trend direction and `reverse` flips it entirely
trend	`SlotTextTrend`	`0`	Numeric trend; `0` infers automatically, rising values move up and falling values move down
motionRole	`SlotTextMotionRole`	`"auto"`	Content semantics. `text` explicitly disables number inference; other values designate ordinary numbers, timers, or countdowns.
skipUnchanged	`boolean`	`true`	Skip unchanged characters
interrupt	`boolean`	`true`	Whether new content interrupts the current animation. `true` transitions from the current frame to the latest text; `false` waits until the current animation ends, then handles the latest text.
replayKey	`string \| number`	`0`	When text is unchanged, a changed key replays from empty slots; when text changes, only the normal diff animation runs.
playOnMount	`boolean`	`false`	Whether to replay from empty slots after mounting
animated	`boolean`	`true`	Whether to animate text changes
respectMotionPreference	`boolean`	`false`	Honors the system reduced-motion setting only when explicitly enabled
transition	`Partial<SlotTextTransition>`	—	Timing override for debugging and demos; does not change the default reproduction baseline. Default: reference project values.
font	`string`	—	Font family; supports SnowUI Tokens
size	`string \| number`	—	Font size; supports SnowUI Tokens
weight	`string \| number`	—	Font weight
color	`SnowUIColor \| string`	—	Final text color; supports PascalCase semantic colors
lineHeight	`string \| number`	—	Line height; supports SnowUI Tokens
align	`TextMotionAlign`	—	Alignment; inherits from the parent by default
motionColor	`TextMotionColor`	—	Temporary color as target characters settle from left to right. Colors stay unchanged by default; supports a per-character `chromatic()` gradient.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Keyword

All six typography defaults inherit from the parent. On update, motionColor colors the full target text, then characters return from left to right to color or the inherited color after the main duration and each character delay. The color’s main timing remains duration + exitOffset; its return timing remains colorFade. Numeric movement still starts from least to most significant digit. These two timelines do not alter each other’s direction.

<script lang="ts">    import { SlotText, chromatic } from "@snowui-design-system/components";</script> <SlotText text="Deploy Ready" motionColor={chromatic()} />

Numeric content follows the shared trend protocol. Trend compares only old and new result values: -3 -> -2 increases and -2 -> -3 decreases. Multiplication and division use the larger or smaller result, not the operator, to choose Up or Down. Complete time strings use circular base-60 differences for mm:ss or HH:mm:ss: 59:59 -> 00:00 is an increasing timer and 00:00 -> 59:59 is a decreasing countdown. A single 00..59 segment also uses base-60 units when motionRole="timer" or "countdown". With direction="normal", text exits upward and enters from below, increasing numbers and timers move up, and decreasing numbers and countdowns move down. direction="reverse" flips all of these rules. Changed digits start from least to most significant, visually right to left. trend={1|-1} overrides automatic inference but is still flipped by reverse.

<SlotText    text="Deploy Ready"    size="--text-24"    weight={600}    color="Primary"    motionColor="Indigo"/>

<Field>    <SlotText as="label" text="Email" />    <Input /></Field>

SlotText style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

This component source does not directly consume a registered component-specific override. Style composed children through public parts or an explicit child; do not guess variable names.

Design guide · Tokens · Composition boundaries

SlotText types and states

Required Props: no named required Props.

Bindable Props: this component declares no named two-way binding; handle state updates through public callbacks or its host.

Inheritance: Omit<FrameProps, "children">. Consult the base class public documentation; fields excluded by Omit cannot be passed through unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

SlotTextDirection

Source: components/src/components/SlotText.svelte

export type SlotTextDirection = "normal" | "reverse";

SlotTextTrend

Source: components/src/components/SlotText.svelte

export type SlotTextTrend = TextMotionTrend;

TextMotionTrend

Source: components/src/lib/text-motion/types.ts

export type TextMotionTrend = -1 | 0 | 1;

TextMotionRole

Source: components/src/lib/text-motion/types.ts

export type TextMotionRole = "auto" | "text" | "number" | "timer" | "countdown";

SlotTextTransition

Source: components/src/components/SlotText.svelte

export interface SlotTextTransition {        stagger?: number;        duration?: number;        layoutDuration?: number;        exitOffset?: number;        colorFade?: number;    }

SnowUIColor

Source: components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

TextMotionAlign

Source: components/src/lib/text-motion/types.ts

export type TextMotionAlign = "left" | "center" | "right" | "justify";

TextMotionColor

Source: components/src/lib/text-motion/types.ts

export type TextMotionColor = SnowUIColor | string | TextMotionColorResolver;

TextMotionColorResolver

Source: components/src/lib/text-motion/types.ts

export type TextMotionColorResolver = (index: number, total: number) => string;