# Merge button

> Merge a pull request and see it go in: the button carries a small branch graph, and pressing it draws what your merge strategy really does to main.

Most merge buttons turn green, show a spinner, then say “Merged”, and the button looks the same whether the branch was merged, squashed or rebased. Merge button carries the branch on it: main along the bottom, your branch forking off with its commits. While your merge call runs, a pulse travels the branch the way checks run. When it’s in, the graph does what the strategy did: for a merge the branch bends down into main and a merge commit lands where they meet; for a squash the commits slide together into one and that one drops onto main; for a rebase each commit lifts off and lands on main in turn while the branch fades. The label morphs the whole way, Merge pull request → Merging → Merged. If the merge fails, the branch dips towards main, the lines cross under a red mark, the button shakes once and turns to “Resolve conflicts” (or the reason you threw); press it again to retry.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/merge-button.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): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/merge-button
- Registry item (source): https://hairlineui.com/r/merge-button.json

## Usage

```tsx
import { MergeButton } from "@/components/merge-button";

<MergeButton strategy="squash" onMerge={() => mergePullRequest(pr.number)} />
```

## Merging a GitHub pull request

Call your own route, which merges with the GitHub API; a 405 or 409 there means the branch can’t be merged, so throw with the reason and the button shows it.

```tsx
"use client";
import { MergeButton } from "@/components/merge-button";

export function MergePr({ pr }: { pr: { number: number; merged: boolean; commits: number } }) {
  return (
    <MergeButton
      strategy="squash"
      commits={pr.commits}
      merged={pr.merged}
      onMerge={async () => {
        const res = await fetch(`/api/pulls/${pr.number}/merge`, { method: "PUT", body: JSON.stringify({ merge_method: "squash" }) });
        if (res.status === 405 || res.status === 409) throw new Error("Resolve conflicts");
        if (!res.ok) throw new Error("Couldn’t merge");
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onMerge` | `() => Promise<unknown> \| void` | – | Your merge call. Resolve when it’s in; throw or reject to show a failure, with the error’s message as the label. |
| `strategy` | `"merge" \| "squash" \| "rebase"` | `"merge"` | What the graph draws when it lands, and the labels it uses. |
| `commits` | `number` | `3` | Commits drawn on the branch, 1 to 4. |
| `merged` | `boolean` | `false` | Already merged: shows the merged graph, still. |
| `labels` | `Partial<Record<"idle" \| "pending" \| "done" \| "error", string>>` | – | Your own words for any state. |
| `sound` | `boolean` | `false` | A soft sound when it lands, and another on a failure. |

## States

- **ready**: Main along the bottom, the branch forking off it with 1 to 4 commits, beside the label for the strategy.
- **merging**: While onMerge is pending the branch dims over 240ms, a bright dash runs along it from the fork every 1.3s and each commit lights as the dash passes it, the way checks run. The label morphs to Merging.
- **merged (merge)**: The branch bends down into main over 440ms, a merge commit pops in where they meet with a slight overshoot, and main draws on past it.
- **merged (squash)**: The commits slide into the head over 380ms and fade into it; that one commit arcs down onto main and settles with a small squash, and the branch draws back to the fork.
- **merged (rebase)**: Each commit lifts off the branch and lands on main in turn, 150ms apart, while the branch fades.
- **conflict**: If onMerge throws, the button turns outlined, the branch dips towards main, a red mark pops where the lines cross and the graph shakes once over 400ms. The label reads Resolve conflicts, or the error’s message.
- **reduced motion**: Every state is drawn in its final position at once; only the label changes.

## What it handles

A merge button that only changes colour doesn’t say what happened to main, and a failed merge usually leaves a toast somewhere else on the screen.

- **Your merge call**: Pass onMerge; it owns pending, merged and failed, with no state of yours to track.
- **Three strategies**: Merge, squash and rebase each draw what they really do to the history.
- **Checks running**: A pulse runs along the branch for as long as your call is pending.
- **Conflicts in place**: A throw crosses the lines under a red mark and puts the reason on the button.
- **Retry**: Pressed again after a failure, it runs onMerge again from the start.
- **Screen readers**: “Merged” or the failure is announced once; the graph is decoration and hidden.

## Replaces

merge pull request button, merging spinner, merged badge, conflict toast, squash and merge button

## Where it fits

- **Pull request pages**: The merge action at the foot of a PR, with the strategy the repo uses.
- **Agents that open PRs**: Merging what a coding agent proposed, from the chat or the run summary.
- **Deploy dashboards**: Promoting a preview branch into main, with the result drawn on the button.
- **Content and docs tools**: Publishing a draft branch of a page or a dataset into the live one.

## Notes

- The graph is one small SVG moved by a frame loop that runs only while something is changing; it sleeps when the button is still.
- The label changes through TextMorph, so the button’s width eases with it.
- While merging or once merged the button is aria-disabled and ignores presses; after a failure it takes a press again to retry.
- The result is announced once from a live region beside the button; the graph is hidden from screen readers.
- Reduced motion draws each state in place with no pulse, bend or shake.

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