# Goal tape

> How far to free shipping, and the moment you get there: the fill runs into a satin ribbon stretched across the bar at the goal and bows it until it snaps.

A free-shipping bar is usually a thin line that fills up, and reaching the goal turns it green or throws confetti over the cart. Goal tape is a finish line seen from above. A recessed lane fills with your colour as the total grows, and at each goal a satin ribbon is stretched across it between two pins. Add the item that gets you there and the fill’s nose runs into the ribbon and bows it forward until it snaps: the two halves whip back towards their pins and curl up beside them, the satin catching the light as it twists, while the line above rolls from “Add $6.50 more for free shipping” to “You’ve unlocked free shipping”. Take the item back out and the two ends swing out, meet in the middle and tie, leaving a small knot. Several goals each get their own ribbon (free shipping, then a free gift). The total is yours: it shows whatever value you pass, glides to each new one on a spring, and needs nothing else from your cart.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/goal-tape.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/goal-tape
- Registry item (source): https://hairlineui.com/r/goal-tape.json

## Usage

```tsx
import { GoalTape } from "@/components/goal-tape";

<GoalTape
  value={subtotal}
  goal={50}
  label="free shipping"
  format={{ style: "currency", currency: "USD" }}
/>
```

## In a cart drawer

The subtotal comes from your cart; the tiers come from your shipping and promotion settings.

```tsx
"use client";
import { GoalTape } from "@/components/goal-tape";
import { useCart } from "@/lib/cart"; // your cart

export function CartRewards() {
  const { subtotal, currency } = useCart();
  return (
    <GoalTape
      value={subtotal}
      format={{ style: "currency", currency }}
      goals={[
        { at: 50, label: "free shipping" },
        { at: 100, label: "a free tote", color: "var(--chart-3)" },
      ]}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | – | The running total: a subtotal, money raised, points. |
| `goals` | `{ at, label, color? }[]` | – | Each goal and what it unlocks, read in a sentence (“free shipping”). Any order. |
| `goal / label` | `number / string` | – | A single goal, instead of goals. |
| `format / locales` | `Intl.NumberFormatOptions / string` | – | How amounts are written, e.g. { style: "currency", currency: "USD" }. |
| `messages` | `{ add?, more?, unlocked? }` | `"Add ", " more for ", "You’ve unlocked "` | The words around the amount and the label. |
| `sound` | `boolean` | `false` | A soft snap as a ribbon breaks and a tick as it ties. |

## States

- **filling**: A new total glides the fill on a spring (stiffness 150, a slight overshoot); the line above rolls the amount still to go.
- **bow**: Past a goal, the fill’s nose pushes the ribbon’s middle forward; it bows up to 13px.
- **snap**: At 13px of bow, or once the fill comes to rest past the goal, the ribbon snaps: each half is thrown forward and back towards its pin, its length contracting to about a third in 60ms, then curls and settles. The line morphs to “You’ve unlocked …” and the goal’s caption gains a check.
- **retie**: Back under a goal, the free ends are drawn to the middle of the lane and grow back to full length; when they meet the ribbon is whole again with a small knot.
- **at rest**: Nothing moves once the ropes settle; ribbons already broken on first show lie curled by their pins.
- **reduced motion**: The fill jumps to the total, and ribbons are simply whole or gone.

## What it handles

A free-shipping bar that only fills and turns green gives no moment for the thing the shopper just did.

- **The amount to go, in words**: The line above says how much more and for what, and rolls to the unlocked line at the goal.
- **A moment at the goal**: The ribbon bows under the fill and snaps, with no confetti over your cart.
- **Going back under**: Take an item out and the ribbon ties itself again, so the state always matches the total.
- **Several goals**: Pass a list and each goal gets its own ribbon and caption, in order.
- **Any currency or unit**: Amounts are written with Intl.NumberFormat from your format and locale.
- **Screen readers**: The lane is a meter with the total; each goal reached is announced once.

## Replaces

free shipping bar, progress bar, spend threshold banner, confetti on unlock, reward tier meter

## Where it fits

- **Cart drawers**: How much more for free shipping, under the subtotal.
- **Reward tiers**: Spend thresholds that unlock a gift, a discount, then free delivery.
- **Fundraising**: A campaign goal, with stretch goals after it.
- **Loyalty points**: Points toward the next perk on an account page.

## Notes

- The lane is a role="meter" with the total as its value and the sentence as its name. Reaching a goal is announced once from a polite status region; the rolling amount isn’t announced on every change.
- Ribbons take your chart colours in turn, or a gold satin when your theme’s chart colours are greys. The fill is your primary, the pins are mixed from your foreground and background.
- Each ribbon half is a twelve-point rope (Verlet, six constraint passes a step) drawn on one canvas around the lane; the frame loop runs only while the fill moves or a rope is still settling.
- The fill moves by transform on its own layer. Reduced motion drops the springs and ropes: the fill jumps and ribbons are simply whole or gone.

License: MIT (https://hairlineui.com/license#components)
