# Morph Text

> Text that morphs from the old value to the new one when it changes.

- Install: `npx shadcn@latest add @0xui/morph-text`
- Registry JSON: https://0xui.io/r/morph-text.json
- Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/morph-text.tsx

Animates a label when its text changes. Characters the old and new text share slide to their new place, and the rest fade. Built on [torph](https://github.com/lochie/torph).

Click the button to step through a transaction's labels.

## Installation

```bash
npx shadcn@latest add @0xui/morph-text
```

## Usage

```tsx
import { MorphText } from "@/components/morph-text";

<Button>
  <MorphText>{isPending ? "Pending…" : "Send"}</MorphText>
</Button>;
```

Keep one `MorphText` mounted and change its text. Swapping between two `MorphText` elements replaces the label without a morph.

## Examples

### Numbers

Digits roll by place value, so only the places that changed move. Use `tabular-nums` on the parent to stop the width from shifting.

```tsx
<span className="tabular-nums">
  <MorphText>{blockNumber.toLocaleString()}</MorphText>
</span>
```

## Where 0xui uses it

| Component | What morphs |
| --- | --- |
| [Transaction Button](https://0xui.io/components/transaction-button.md), [Batch Transaction](https://0xui.io/components/batch-transaction.md), [Sign Message](https://0xui.io/components/sign-message.md), [Add Token](https://0xui.io/components/add-token.md) | The button label, across phases. This covers [Approve Button](https://0xui.io/components/approve-button.md), [Send](https://0xui.io/blocks/send.md) and [Swap](https://0xui.io/blocks/swap.md) too. |
| [Contract Form](https://0xui.io/components/contract-form.md) | "Read" and "Reading…". |
| [Chain Selector](https://0xui.io/components/chain-selector.md) | The current chain's name. |
| [Block Number](https://0xui.io/components/block-number.md), [Gas Price](https://0xui.io/components/gas-price.md) | The live value. |
| [Balance](https://0xui.io/components/balance.md), [Token Input](https://0xui.io/components/token-input.md) | The balance and the fiat value. |
| [Swap](https://0xui.io/blocks/swap.md), [Portfolio](https://0xui.io/blocks/portfolio.md) | The rate, price impact and total value. |

[Token Amount](https://0xui.io/components/token-amount.md) only morphs with `animate`, so long lists don't pay for it.

## Behavior

| Case | What happens |
| --- | --- |
| Text and numbers, alone or mixed like `Approve {symbol}` | Joined into one label and morphed. |
| Children that hold an element | Rendered as-is, with no animation. |
| Screen readers | Read the plain text once. The animated characters are hidden from them. |
| `prefers-reduced-motion` | The text changes without animating. |
| No Web Animations API, as in jsdom | Plain text in a `span`, so tests can query the label. |

The text never wraps: torph sets `white-space: nowrap`. Use it for short labels and values, not sentences.

torph adds one `<style>` element to the page. Under a strict Content Security Policy, allow it or set `disabled`.

## Props

Also accepts torph's options, such as `ease`, `scale`, `numbers`, `decimals`, `locale` and `onAnimationComplete`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Text to show. |
| `duration` | `number` | `400` | Length of the morph, in ms. |
| `disabled` | `boolean` | `false` | Change the text without animating. |
| `className` | `string` | — | Class for the wrapping `span`. |
