Text 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

Display text with consistent typography and truncation for body copy, labels, and space-limited information.

When to use it

Use Text for semantic text, truncation, expansion, and supplementary tooltips. Hover motion is off by default. Plain static copy may use semantic HTML; choose a motion component for animated numbers or text.

• tag chooses the text element, lines controls truncation, and more or tooltip supplies expansion or additional information.

• No hover interaction runs by default. stateText can replace copy by state; parts configures built-in Button and Tooltip instances.

• With lines=1, shortened visible text retains its complete accessible name, including when used inside a button, link or native label.

Quick start

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

<script lang="ts">	import { Text, Button, Frame } from '@snowui-design-system/components';</script> <div style="width: min(100%, 24rem); min-width: 0;">	<Text lines={1} tooltip style="font-size: var(--text-14); line-height: var(--leading-14); width: 100%;">Design system documentation — component behavior, accessibility, and release notes</Text></div>

API

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

Built-in component dual mode

• parts.Button: Configure the built-in expansion button generated by lines=0 + more.

• parts.Tooltip configures the built-in tooltip shown for truncated content.

• External Tooltip or other children are not controlled by Text's private DOM selector.

Inheritance: Text retains Frame’s general interaction, motion, responsive, and appearance features. Defaults: enableResponsive=false, enableContext=true, enableScaleObserver=false. Ownership: Text implements lines and onTruncate itself; Frame routes shared capabilities.

Without lines, truncation remains dormant: it does not read text, queue animation frames, or register MutationObserver/ResizeObserver. Setting lines later activates the existing protocol without changing the default appearance.

Layout model

Main layout model: text flow layout.

• Text preserves HTML text flow, semantic tags, truncation, and tooltip/more positioning. It does not register as a slot host, inline shell, or composite layout.

• tag determines the text flow display mode such as block / inline-block / list-item / code; lines=0/1/2/3 only changes the truncation and mask, not the main layout model of the component.

• <Tooltip as="tooltip"> and <Button as="more"> are role children. Tooltip explains truncated content; Button keeps its own inline-shell layout.

• Text uses no padding or gap to arrange children and no margin to change surrounding text flow. Interactive displacement uses transform variables only.

1.1 Overview of functions

• Smart truncation: Text directly supports lines={0|1|2|3} and onTruncate; single-line mode reuses fitTextToElement() to stably display the explicit ellipsis that follows the text.

• Complete accessible text: Single-line truncation keeps shortened text visual-only and reuses the existing fullText and bundled visually hidden style for the complete plain-text name. Parent buttons, links and native labels retain their full name. It does not render an interactive snippet twice or add a measurement controller.

• Built-in expansion: With lines=0, more may enable the built-in ArrowLineDown Button; it is off by default. The button uses the same backdrop blur as BarChart’s blur overlay.

• Scroll mode: With lines=0 and no More button, content uses Textarea’s shared top/bottom fade and overlay scrollbar. Showing More switches to expansion mode without a scrollbar.

• Role-oriented combination:

  • <Tooltip as="tooltip">: The prompt automatically displayed when truncated.

  • <Button as="more">: Expand/collapse control.

• Responsive: tag / class can be overwritten through responsive.

• Motion: Inherits Frame triggers such as whileHover and whileClick.

1.2 Keyword Definition (Keywords)

stateText parsing rules

1. Text reads the currentState of the recent parent Frame Context.

2. Render the text when the current state hits stateText[currentState].

3. If the current state has no match, fall back to stateText.Idle.

4. If stateText is absent or unresolved, render children.

5. stateText is only used to replace text with the same structure, and does not carry complex DOM. Complex custom subtrees are still exception scenarios of stateContent.

Load is reserved for Frame’s loading/Skeleton protocol. For a button task in progress that still shows real copy, prefer Pending.

1.3 Usage example

 <Text>Plain text without truncation.</Text>  <Text lines={1}>Very long text that will be truncated...</Text>  <Text lines={1}>    Very long text that will be truncated...    <Tooltip as="tooltip">The full long text...</Tooltip></Text>  <Text lines={3}>A long paragraph is clamped to three lines...</Text>  <Text lines={0} class="bg-black-5 p-4 rounded-8">    Long content can be expanded...    <Button as="more" variant="borderless" class="text-blue">        Read more    </Button></Text>  <Text lines={0} more>    Long content can be expanded.</Text>  <Text lines={0} style="height: 5rem;">    Long content can scroll within a constrained height.</Text>  <Text    lines={1}    enableResponsive    class="text-12"    responsive={{        sm: { class: "text-14" },        lg: { class: "text-16" }    }}>    Responsive text...</Text>  <Button Click="Active" Active={["Idle", "auto"]} whileActive={{ duration: 2000 }}>    <Icon stateIcon={{ Idle: Paperclip, Active: Check }} />    <Text stateText={{ Idle: "Copy", Active: "Copied" }} /></Button>  <Button    Click={{ Idle: "Pending", Active: "Idle" }}    Pending={["Active", "auto"]}>    <Icon stateIcon={{ Idle: null, Pending: Spinner, Active: Check }} />    <Text stateText={{ Idle: "Ready", Pending: "Loading...", Active: "Completed" }} /></Button>

1. Basic style

2. Layout Modes (Layout Modes)

3. Hover interaction

Closed by default; only effective when interactive === true:

5. Truncation and expandable style (lines=0/2/3)