# FlipText (flip-text)

> Letters tumble on hover with a vermilion accent. Click, tap, or use the keyboard to flip the whole phrase. Respects reduced motion.

- Entry: component
- Category: Interactive
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/flip-text
- JSON: https://jbm-ui.bns.studio/catalog/flip-text.json
- Registry item: https://jbm-ui.bns.studio/r/flip-text.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/flip-text
```

Also installs @jbm/tokens (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/flip-text.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/flip-text.tsx` | `src/jbm/ui/flip-text.tsx` | `@/jbm/ui/flip-text` |

## API

### `FlipText` (component)

A native button whose graphemes each flip 360° on the X axis (lifting 0.15em and passing through the accent color at the midpoint) using the Web Animations API. Mouse hover flips one character; click, tap, Enter, or Space flips every character in sequence, staggered 25ms apart. The accessible name is `Flip text: <children>`. No animation runs under reduced motion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `string` | required | The phrase, as a plain string. Split into words and graphemes; whitespace is preserved. |
| `duration` | `number` | `450` | Milliseconds for each character's flip. Negative values clamp to 0; non-finite values fall back to 450. |
| `accentColor` | `string` | `color.accent` | Color each character passes through at the middle of its flip. |
| `reducedMotion` | `boolean` | none | Overrides the system prefers-reduced-motion setting. When reduced, flips are skipped and any running flips are cancelled. |
| `className` | `string` | none | Class name on the button. |
| `style` | `CSSProperties` | none | Inline styles merged over the defaults (Geist sans, weight 800, line-height 1.3, ink, transparent background); set fontSize here. |

## Stage

fluid: An inline-block button sized by its text: height is lines × fontSize × 1.3 plus 0.2em top and bottom padding, width follows the text up to 100% of the container, where it wraps.

## Examples

### Flip a headline

```tsx
import { FlipText } from "@/jbm/ui/flip-text"

<FlipText duration={450} style={{ fontSize: 48 }}>Una idea viva.</FlipText>
// Hover individual letters. Click, tap, Enter, or Space flips all.
// A button: do not nest inside another button or link.
```

## QA

- Hover single letters with a mouse: each tumbles once and returns to ink; re-hovering mid-flip restarts that letter cleanly.
- Click, tap, and press Enter or Space with keyboard focus: every letter flips in a left-to-right stagger, then all characters return to ink.
- Check touch: tapping flips the whole phrase; pointer-enter from touch does not flip single letters.
- Enable prefers-reduced-motion, or pass reducedMotion: no letter moves, and flips in progress are cancelled when the preference turns on.
- Check the focus ring is visible and the phrase wraps between words on a narrow screen.

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
