# Handoff Divider

Marks the moment one agent passes the conversation to another.

- Category: AI & Agents
- Page: https://wunderui.com/components/handoff-divider
- Tier: Core and Pro

## Install

Handoff Divider ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { HandoffDivider } from "@wunderui/react"
```

## Minimal usage

Then use it between two messages:

```tsx
import { HandoffDivider } from "@wunderui/react"

export function Handoff() {
  return <HandoffDivider from="Planner" to="Writer" timestamp="09:42" reason="Outline approved, ready to draft" />
}
```

Expected result: You see a thin line, a small lightning icon with Planner handed off to Writer · 09:42 in grey, and a thin line again, across the column, with the reason in smaller grey text under it.

## When to use

### Use Handoff Divider for

- The point in a multi-agent transcript where one agent passes the conversation to another
- A log of handoffs, with the time after the sentence and the reason under each divider
- Any chat where the sender of the next message would otherwise change without a sign

### Use something else

- [Agent Avatar](https://wunderui.com/components/agent-avatar) for who sent a message: tint, name and role on the message itself
- [Divider with Label](https://wunderui.com/components/divider-with-label) for a labelled break that is not a handoff, such as a date or the word or
- [Separator](https://wunderui.com/components/separator) for a plain line between two groups

## Behavior

How the divider handles its text, width, assistive technology and motion.

- **Text:** The default label reads the first agent, handed off to, the second agent. The names can be styled; pass your own label to replace the whole sentence, for instance to translate it.
- **Width:** The divider fills its column. The lines share the rest of the row and keep at least 16 px; a long label wraps, an unbroken id breaks anywhere, and the icon keeps its size.
- **Direction:** Layout has no physical left or right, so a right-to-left parent mirrors it and the icon moves to the other end. The sentence stays in the language you give it.
- **Reason and timestamp:** The timestamp shows as given after the sentence, after a dot, in a tertiary tone. The reason sits on its own centred line under the divider, and both are optional.
- **Assistive technology:** It is a separator with an accessible name: your aria-label, or the plain text of the sentence, timestamp and reason. With styled names it falls back to Agent handoff, so pass an aria-label.
- **Keyboard:** Not interactive and not in the tab order. Nothing to press.
- **Motion:** None. The divider never animates; it is there when the message after it is.
- **Reduced motion:** Nothing to reduce.

## Anatomy

- `HandoffDivider`: A full-width row with the separator role and an accessible name. With a reason it becomes a column, the row on top and the reason under it; it is not focusable and not a live region.
- `Hairline`: Two 1 px lines in the border colour on each side of the label. They share the free width and keep at least 16 px each, so a long label wraps before the lines disappear.
- `Icon`: A 14 px lightning icon in the tertiary text colour. It is decorative and keeps its size when the label wraps.
- `Label`: The text between the lines, such as Planner handed off to Reviewer, in 12 px medium text. A timestamp can follow after a dot; pass your own label to change the wording.
- `Reason`: The reason in 12 px tertiary text under the row, centred. It only shows when you pass one.

## Best practices

### When to use

- Use a Handoff Divider in a multi-agent chat where the speaker changes. To show who speaks, put an Agent Avatar with name and role on the message itself.

### Do

- Use the same agent names the messages show, such as Planner and Reviewer, so the label reads: Planner handed off to Reviewer.
- Place one divider per handoff, between the last message of the first agent and the first message of the next.
- Announce a live handoff in a separate status line that exists before it has text. A separator is not a live region, so a screen reader won't hear the divider arrive.
- Pass a reason and a timestamp when they matter, and keep the reason to one short sentence a person can act on.
- Add an aria-label when the agent names are styled nodes. A name can't be built from a node, and a separator's children aren't read out.

### Don't

- Don't put the reason or a long sentence into the agent names. The label is one sentence between two lines; a long one wraps and the lines shrink to 16 px.
- Don't use it as a general section break. It always says handed off to, so use a Separator or a Divider with Label for anything else.
- Don't make it the only place that says who took over. Some screen readers skip the text inside a separator, so the next message must name its sender too.
- Don't use the label for a heading or a long note. It stays one row between two lines; put the reason in the reason prop.

## API reference

### HandoffDivider

| Prop | Type | Default | Description |
|---|---|---|---|
| from* | React.ReactNode |  | The agent that hands the conversation over. A node, shown before `handed off to`. Use the name the messages show. Required. |
| to* | React.ReactNode |  | The agent that takes the conversation over. A node, shown after `handed off to`. Required. |
| aria-label | string |  | The accessible name of the separator. By default built from the sentence, the timestamp and the reason when they are text; `Agent handoff` when they are nodes. |
| className | string |  | Extra classes for the row, for example a vertical margin. |
| label | React.ReactNode |  | Replaces the fixed sentence `{from} handed off to {to}`. A node. Use it when your product says the handoff another way. |
| reason | React.ReactNode |  | Why the conversation moved, shown under the row in tertiary text. Text or a node. Leave it out for the single row. |
| timestamp | React.ReactNode |  | When it happened, shown as given after the sentence, for example `09:42` or a `time` element. |

## Examples

### Names: short, long, agent ids and styled names

### Detail: the sentence alone, a timestamp, a reason, both, an own label

### Width: full, 280 px and 200 px

### Direction: left to right and right to left

## In context

### Transcript: the divider appears where the next agent takes over

Press the button to hand the conversation to the next agent. A separator is not a live region, so the same sentence also goes into a status line that screen readers hear.

### Handoff log: the time and the reason on each divider

The timestamp and reason belong to the divider. The timestamp is a time element, so its value stays machine-readable, and both are part of the separator's accessible name when they are text.

## For AI agents

`get_component("handoff-divider")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
