# Reactions

> Emoji reactions for comments and messages: press, slide along the tray and let go, and the emoji flies into its chip.

Most reaction rows open a grid of emoji, swap a number and call it done. This one is picked the way people pick on a phone: press the add button and slide along the tray without letting go. The emoji under your finger swells on a spring and its name glides above it; let go to react. The emoji then flies from the tray into its chip, shrinking as it goes, and lands: the chip dips under the weight, the count rolls up and a few copies spring out of it. Other people's reactions bump their chip and roll the count, your own chip takes a reaction back, and a chip that empties lets its emoji go before the gap closes.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/reactions.json
```

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

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

## Usage

```tsx
import { Reactions } from "@/components/reactions";

<Reactions value={reactions} onValueChange={setReactions} onReact={save} />
```

## Saved to your API

Keep the row in state, save each change and let a throw undo it. Other people's reactions from a socket or a refetch just update the same state.

```tsx
"use client";
import { useState } from "react";
import { Reactions, type Reaction } from "@/components/reactions";

export function CommentReactions({ commentId, initial }: { commentId: string; initial: Reaction[] }) {
  const [reactions, setReactions] = useState(initial);

  return (
    <Reactions
      value={reactions}
      onValueChange={setReactions}
      onReact={async (emoji, on) => {
        const res = await fetch(`/api/comments/${commentId}/reactions`, {
          method: on ? "POST" : "DELETE",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ emoji }),
        });
        if (!res.ok) throw new Error("Not saved");
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Reaction[]` | – | The reactions shown: { emoji, count, mine?, people? }. count includes you; people are other people's names. |
| `defaultValue` | `Reaction[]` | `[]` | Starting reactions when you don't control the value. |
| `onValueChange` | `(value: Reaction[]) => void` | – | Called with the new row on every change, including an undo. |
| `onReact` | `(emoji: string, on: boolean) => Promise<unknown> \| unknown` | – | Save the change. Called after the row has changed; throw to undo it. |
| `choices` | `ReactionChoice[]` | `DEFAULT_REACTION_CHOICES` | The emoji in the tray, each with a label: 👍 ❤️ 😂 🎉 😮 🙏 👀 by default. |
| `label` | `string` | `"Add reaction"` | The add button's name. |
| `ref` | `Ref<ReactionsHandle>` | – | pick(emoji) plays the whole gesture for that emoji, for a keyboard shortcut or a tour. |

## States

- **pick**: Pressing the add button grows it into the tray: the button stretches out and up into a hairline pill and the emoji rise into it as it reaches them, outward from the button (about 0.3s); it folds back into the button on close. sliding swells the emoji under the finger to full size on a tight spring (about 0.2s), its neighbours part way, and the name glides above it. Release over one reacts; release elsewhere closes.
- **flight**: The picked emoji flies to its chip on three springs (across, down and size, about 0.35s, no overshoot). On landing the chip dips about 7% and the emoji on it pops, then five small copies are thrown out under gravity for 0.6s.
- **others**: A count that rises from your data bumps its chip gently and rolls the number up. A new emoji opens its chip in place.
- **remove**: Your own chip, or your emoji in the tray, takes your reaction back. At zero the emoji shrinks first and the gap closes 110ms later.
- **error**: If onReact throws, the change is undone, the chip shakes ±4px over 380ms (the add button, if the chip is gone) and the failure is announced.
- **reduced motion**: No swell, flight, burst or shake. Chips and counts change in place.

## What it handles

A reaction row looks small, but the usual one makes people open a menu, aim and click, then shows a number that jumps. And when the save fails, it quietly stays wrong.

- **Press, slide, release**: One gesture from the add button to the emoji, on touch and mouse; a tap still opens the tray to click.
- **A flight to the chip**: Springs carry the emoji from where it was drawn in the tray to its chip, so a new chip or an existing one both catch it.
- **Toggles like people expect**: Picking an emoji you already used, or pressing your own chip, takes your reaction back; a dot in the tray marks yours.
- **Optimistic, with an undo**: The row changes at once and onReact saves it; if that throws, the change is reversed and the chip shakes.
- **Who reacted**: Hover or focus a chip to read "You, Mira and 3 others reacted with Celebrate".
- **Keyboard and screen readers**: The tray is a menu with arrow keys, Home, End and Escape; chips are toggle buttons; changes are announced.

## Replaces

emoji picker popover, optimistic reaction state, reaction tooltip, emoji-mart, framer-motion

## Where it fits

- **Comment threads**: The row under each comment in a doc, a design file or an issue.
- **Team chat**: Reactions on messages, with names on hover so people see who agreed.
- **Changelogs and posts**: Let readers react to a release without writing a comment.
- **Support and feedback**: A quick thanks or a thumbs up on an answer, saved through your own API.

## Notes

- The tray is a role="menu" of menuitemcheckbox items: Enter, Space or Up on the add button opens it with focus inside; arrows, Home and End move; Escape closes and returns focus.
- Chips are toggle buttons (aria-pressed) named with the emoji's label and count; a status region outside them announces each change and each failure.
- Emoji are the system's own, drawn at their largest size and scaled down at rest, so the swell stays sharp. Nothing loads from a CDN.
- All motion runs on the shared spring loop and the compositor: transforms only, no layout reads while you slide, and the burst is capped.
- The tray opens above the row, below it when there's no room, and stays inside the screen on phones.

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