# Integrate `StretchType` from Motion Garden

You are helping me add the **StretchType** component to an existing project.
Everything you need is below — full source, dependencies, props and the
behavioural contract. Read it all before writing anything.

- **Component:** StretchType
- **Category:** Text Animations
- **Summary:** Type that deforms with how fast you are scrolling rather than how far. Each glyph springs toward the same velocity signal on a softer spring than the one before it, so the wave down the word is a consequence of the physics instead of a list of delays — change the string and it re-tunes itself.
- **Reference:** https://motion-garden.netlify.app/components/stretch-type
- **Full catalog (for you, the agent):** https://motion-garden.netlify.app/llms.txt

## Stack this source assumes

- React 19 with the Next.js App Router (never the `pages/` directory)
- TypeScript, strict
- Tailwind CSS v4, CSS-first config (utilities are inline; no `tailwind.config` needed)

If my project differs, adapt the integration — but do not rewrite the animation math to suit a different stack. Ask me first.

## Dependencies

```bash
bun add motion clsx tailwind-merge
```

## Design tokens this source uses

Some classes in the source are Motion Garden theme tokens, not stock Tailwind (`text-ink`, `bg-panel`, `font-display` and the like). Without them, parts of the component render unstyled. Add this to my global CSS, after the Tailwind import:

```css
@theme {
  --font-display: "Space Mono", ui-monospace, "SFMono-Regular", monospace;
}

@theme inline {
  --color-ink: var(--sg-ink);
}

:root {
  --sg-ink: #16191d;
}

.dark {
  --sg-ink: #e2e6e9;
}
```

The values are Motion Garden's own light and dark themes. If my project already has tokens for these roles, point the `--sg-*` variables at mine instead and tell me which you mapped. `.dark` assumes class-based dark mode — adapt the selector to how my project switches themes.

`font-display` expects Space Mono, and this CSS only names it. Load the font (with `next/font/google`, for example) or put my own display face first in the stack; until then it falls back to the system monospace.

## Files to create

2 files — all of them are required. Paths are as shipped; the component may live anywhere in my project, but keep every peer file at the exact path shown so the import aliases resolve.

### 1. `components/registry/stretch-type/stretch-type.tsx`

```tsx
"use client";

import { type RefObject } from "react";
import {
  motion,
  useMotionValue,
  useScroll,
  useSpring,
  useTransform,
  useVelocity,
  type MotionValue,
} from "motion/react";
import { cn } from "@/lib/utils";

export interface StretchTypeProps {
  text?: string;
  className?: string;
  stretch?: number;
  skew?: number;
  tracking?: number;
  stiffness?: number;
  damping?: number;
  maxVelocity?: number;
  stagger?: number;
  direction?: "vertical" | "horizontal";
  scrollContainerRef?: RefObject<HTMLElement | null>;
  reducedMotion?: boolean;
}

export default function StretchType({
  text = "MOTION GARDEN",
  className,
  stretch = 0.55,
  skew = 12,
  tracking = 0.12,
  stiffness = 260,
  damping = 22,
  maxVelocity = 1600,
  stagger = 0.7,
  direction = "vertical",
  reducedMotion = false,
  scrollContainerRef,
}: StretchTypeProps) {
  const { scrollY } = useScroll({ container: scrollContainerRef });
  const velocity = useVelocity(scrollY);

  const signal = useTransform(velocity, [-maxVelocity, 0, maxVelocity], [-1, 0, 1], {
    clamp: true,
  });

  const characters = [...text];
  const last = Math.max(1, characters.length - 1);

  return (
    <span className={cn("inline-flex font-display text-5xl text-ink select-none", className)}>
      <span aria-hidden>
        {characters.map((character, index) =>
          character === " " ? (
            <span key={`space-${index}`}> </span>
          ) : (
            <Glyph
              key={`${character}-${index}`}
              character={character}
              signal={signal}
              position={index / last}
              stretch={stretch}
              skew={skew}
              tracking={tracking}
              stiffness={stiffness}
              damping={damping}
              stagger={stagger}
              direction={direction}
              reducedMotion={reducedMotion}
            />
          ),
        )}
      </span>
      <span className="sr-only">{text}</span>
    </span>
  );
}

function Glyph({
  character,
  signal,
  position,
  stretch,
  skew,
  tracking,
  stiffness,
  damping,
  stagger,
  direction,
  reducedMotion,
}: {
  character: string;
  signal: MotionValue<number>;
  position: number;
  stretch: number;
  skew: number;
  tracking: number;
  stiffness: number;
  damping: number;
  stagger: number;
  direction: "vertical" | "horizontal";
  reducedMotion: boolean;
}) {
  const softness = Math.max(1 - stagger * position, 0.15);
  const springed = useSpring(signal, {
    stiffness: Math.max(stiffness * softness, 10),
    damping,
    mass: 0.35,
  });

  const still = useMotionValue(0);
  const value = reducedMotion ? still : springed;

  const load = useTransform(value, (v) => Math.abs(v));
  const grow = useTransform(load, (v) => 1 + v * stretch);
  const give = useTransform(load, (v) => 1 - v * stretch * 0.66);
  const lean = useTransform(value, (v) => -v * skew);
  const spacing = useTransform(load, (v) => `${v * tracking}em`);

  const vertical = direction === "vertical";

  return (
    <motion.span
      className="inline-block"
      style={{
        scaleY: vertical ? grow : give,
        scaleX: vertical ? give : grow,
        skewX: lean,
        letterSpacing: spacing,
        transformOrigin: vertical ? "50% 100%" : "0% 50%",
      }}
    >
      {character}
    </motion.span>
  );
}
```

### 2. `lib/utils.ts` — peer util, required

```tsx
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stretch` | `number` | `0.55` | How far the leading glyph deforms at full velocity. The opposite axis gives up two thirds of what this gains — a full reciprocal preserves the area exactly and reads as the letter being squeezed through a gap rather than pulled. Range 0–1.5. |
| `skew` | `number` | `12` | Degrees of lean at full velocity. Signed off the scroll direction, so scrolling back up leans the word the other way — this is what stops a fast reversal from looking like the same animation replayed. Range 0–40 °. |
| `tracking` | `number` | `0.12` | Extra letter-spacing at full velocity. Unsigned, because the word should open up in both directions — spacing that closed on an upward scroll would read as the type being compressed rather than stressed. Range 0–0.5 em. |
| `stiffness` | `number` | `260` | Spring stiffness of the leading glyph; every other glyph is a fraction of it. Low values keep deforming after the scroll has stopped, which reads as the word still catching up. Range 40–700. |
| `damping` | `number` | `22` | How fast a glyph settles back to its resting shape. Under about 12 the word rings after every scroll stop and the effect stops being about the scroll. Range 5–60. |
| `maxVelocity` | `number` | `1600` | Scroll speed that counts as full deformation. A real ceiling, not a scale factor — the mapping clamps, so one trackpad flick cannot tear the type apart on a scroll nobody meant to be dramatic. Range 200–5000 px/s. |
| `stagger` | `number` | `0.7` | How much softer the last glyph's spring is than the first. At 0 the word deforms as a single block; near the top the tail lags far enough to read as a wave travelling down the line. Range 0–0.95. |
| `direction` | `"vertical" | "horizontal"` | `"vertical"` | Which axis grows under load. Vertical grows from the baseline, which is how a letterform under tension actually behaves; horizontal grows from the leading edge and reads more like smearing. |

## Usage

```tsx
import StretchType from "@/components/registry/stretch-type/stretch-type";

<StretchType
  stretch={0.55}
  skew={12}
  tracking={0.12}
  stiffness={260}
  damping={22}
  maxVelocity={1600}
  stagger={0.7}
  direction="vertical"
/>
```

The import path matches the file path above; change it if you move the component. Every value shown is the documented default — pass only what you actually want to change. The snippet lists the tunable props only: if the component's props type in the source requires others (content, handlers, data), pass those too.

## Integration rules

- Keep the `"use client"` directive. This is a client component and will not render as a Server Component.
- It fills its parent. Give the wrapper an explicit height (or a definite grid area) — against a height-auto parent it collapses to nothing.
- It takes a `reducedMotion` prop and quiesces when true. Wire it to a `prefers-reduced-motion` listener rather than hardcoding `false`.
- `lib/utils.ts` is required, not optional. It exports the `cn` helper the component imports from `@/lib/utils` — keep it at that path, or rewrite every `cn` import to wherever you already keep yours. If your project is shadcn-based you almost certainly have this file already; keep yours and drop mine.

## Your task

1. Tell me where in my project this should live and why.
2. Create the files above verbatim.
3. Add the design tokens to my global CSS, or map them to tokens I already have.
4. Wire the component into the place I point you at, with sensible props for that context.
5. Flag anything in my setup that conflicts with the stack assumptions above.

Do not restyle the component or alter the animation math unless I ask.
