# Branch navigator

A React component in [Beamline](https://beamline.io/)'s [AI & agents](https://beamline.io/components/ai) category. Live demo: https://beamline.io/components/branch-navigator

Part of [Beamline UI: React UI components and complete screens for apps built with coding agents](https://beamline.io/). [The code is copied into your repo; your app never depends on our servers](https://beamline.io/docs/install). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize). [200+ components and 50+ complete screens](https://beamline.io/components/). [$49 launch price; one payment; your whole team, no seats. Lifetime updates: every new version of the complete system, for as long as we publish it, and every version you received stays yours](https://beamline.io/pricing). [React 19, TypeScript, Tailwind v4, Radix](https://beamline.io/docs/install). [Free MIT sample, commercial use included](https://github.com/dprvda/beamline). [Made by Danylo Pravda in Kyiv, Ukraine](https://beamline.io/about).

The versions of an assistant conversation that forked when a message was edited or an answer regenerated: a “‹ 2 / 3 ›” switch on each message that has alternates, and a map of the whole conversation where the path you are on runs straight down and every other version branches off it with how many turns it holds; choosing one shows that branch and lands on where it starts.

## Use it for

- An assistant conversation where editing a message or regenerating an answer keeps the earlier version: show which version is on screen and switch between them.
- Finding your way back to an earlier branch of a long conversation, from a map of all of them.

## Not for

- The messages themselves ([message](https://beamline.io/components/message), [response](https://beamline.io/components/response)) or the scrolling column ([conversation](https://beamline.io/components/conversation)).
- Folders and records nested by hand ([tree-view](https://beamline.io/components/tree-view)).
- Comparing two answers side by side to pick one ([answer-compare](https://beamline.io/components/answer-compare)).

## Anatomy

- BranchNavigator: previous, “2 / 3” (the number rolls), next; a group named for what it counts (Answer 2 of 3)
- BranchNavigatorTree: a heading with the number of branches, then one row per turn on the path you are on (who, its first words) on a straight rail; at a fork the other versions branch off the rail as rows of their own (their first words, how many turns, Edited or Regenerated, n / m); the newest turn of the path is marked Latest
- rails: the path's rail in the accent colour; each fork's versions on a second rail joined to the turn they follow; a person's turn is a ring and the assistant's a dot, and the row says who

## Variants

- **size**: sm, md

## States

- one version (no switch is shown; the tree has no branches and says so)
- first and last version (the switch's end stays focusable and says there is no earlier or later one)
- switching (the number rolls toward the side asked for)
- the path changed (the tree's rows move to their new places, the versions trade rails)
- a turn chosen in the tree (aria-current)

## Keyboard

- BranchNavigator: Tab to its buttons; ← → change the version while focus is in it (mirrored in RTL)
- BranchNavigatorTree: one tab stop; ↑ ↓ move between rows, Home and End to the ends, Enter or Space opens the row (a version switches the path and lands on it, a turn lands on it)

## Motion

The switch's number rolls up for a later version and down for an earlier one. When the path changes, the tree's rows slide to their new places, rows of the new path grow in and the old path's rows fade where they stood, and a version moving onto the main rail travels across. Nothing moves at rest. Reduced motion: placed at once.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `BranchNavigator: value / defaultValue / onValueChange` | `number` | — | value: The version shown, from 0. defaultValue: Initial selection when uncontrolled; omitted by default. onValueChange: Reports the selected value after a change; no callback by default. |
| `BranchNavigator: count` (required) | `number` | — | count: How many versions there are. |
| `BranchNavigator: noun` | `[string, string]` | — | noun: What is counted, singular and plural, for the name read out. Default ["version", "versions"]. |
| `BranchNavigator: size / disabled` | `"sm" \| "md" / boolean` | — |  |
| `BranchNavigatorTree: turns` (required) | `BranchTurn[]` | — | { id, parentId (null for the first turn), from: "user" \| "assistant", label (first words), origin?: "edit" \| "regenerate", at? } |
| `BranchNavigatorTree: value / defaultValue / onValueChange` | `string` | — | value: On BranchNavigatorTree: The newest turn of the path on screen (the tip); default the most recent turn. defaultValue: Initial selection when uncontrolled; omitted by default. onValueChange: Reports the selected value after a change; no callback by default. |
| `BranchNavigatorTree: onTurnSelect` | `(turnId: string) => void` | — | onTurnSelect: On BranchNavigatorTree: A row was opened: land on that turn. |
| `BranchNavigatorTree: label` | `string` | — | label: On BranchNavigatorTree: The tree's name. Default "Branches". |
| `className / classNames / style / ref` | `root` | — | className: Classes on the documented visual root; no override by default. classNames: Classes for the named visual parts; no overrides by default. style: Inline styles on the documented visual root; no overrides by default. ref: Receives the documented native target or imperative handle; omitted by default. |
| `value` | `number` | — | The version shown, from 0. |
| `defaultValue` | `number` | — | Initial selection when uncontrolled; omitted by default. |
| `onValueChange` | `((index: number) => void)` | — | Reports the selected value after a change; no callback by default. |
| `count` (required) | `number` | — | How many versions there are. |
| `noun` | `[string, string]` | — | What is counted, singular and plural, for the name read out. Default ["version", "versions"]. |
| `size` | `"md" \| "sm"` | — |  |
| `disabled` | `boolean` | — |  |
| `className` | `string` | — | Classes on the documented visual root; no override by default. |
| `classNames` | `Partial<Record<"root" \| "next" \| "previous" \| "count", string>>` | — | Classes for the named visual parts; no overrides by default. |
| `style` | `CSSProperties` | — | Inline styles on the documented visual root; no overrides by default. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the documented native target or imperative handle; omitted by default. |
| `BranchNavigatorTree.turns` (required) | `BranchTurn[]` | — |  |
| `BranchNavigatorTree.onTurnSelect` | `((turnId: string) => void)` | — | On BranchNavigatorTree: A row was opened: land on that turn. |
| `BranchNavigatorTree.label` | `string` | — | On BranchNavigatorTree: The tree's name. Default "Branches". |

## Built from

- button
- [slot-text](https://beamline.io/components/slot-text)

## Dependencies

`lucide-react`

## Import

```tsx
import { BranchNavigator, BranchNavigatorTree } from "@beamline/branch-navigator";
```

## Get it

Branch navigator is part of Beamline: 200+ components and 50+ complete screens for React, installed as local code in your repo. Your app never depends on Beamline servers at runtime. Build your own style from any look with public tokens, your fonts, radii, density and motion; custom style files stay in your app. Use local kit tools or let your coding agent find and install parts through the optional hosted MCP server. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in AI & agents

- [Image generation](https://beamline.io/components/image-generation): The frame an AI image is generated into: a field of brand-hued pixels breathes with the progress while the model works, then the image arrives —…
- [Flowchart](https://beamline.io/components/flowchart): A workflow as steps on a dotted canvas: a trigger, conditions that branch into paths side by side, actions and waits, read top to bottom; during a run…
- [Run trace](https://beamline.io/components/run-trace): One agent run as a waterfall: every step (model calls, tools, retrieval, checks, sub-agents) nested under the step that started it, each a bar on a…
- [Answer compare](https://beamline.io/components/answer-compare): Two answers to the same prompt side by side, and a person's verdict: A is better, a tie, B is better, or both are bad, with the reasons that decided it…
- [Response](https://beamline.io/components/response): An assistant's answer as streamed markdown in the system's reading type: bursty tokens flow in at an even pace, each new word fades in through a short…
- [Chat thread](https://beamline.io/components/chat-thread): People talking to people: messages grouped by person and day, reactions, delivery and read receipts that glide to the newest message read, who is typing…
- [Model picker](https://beamline.io/components/model-picker): Choose the AI model for a request by what it can do and what it costs: a trigger with the model's name opens a searchable list grouped by provider, with…
- [Task rows](https://beamline.io/components/task-rows): Background work an agent is doing, one row per task: status as a glyph and a word, what it produced, how long it has run or took, a progress bar while…
- [Conversation](https://beamline.io/components/conversation): The scrolling column of a conversation: follows new content while you are at the bottom, stops when you scroll up to read, and offers a way back; shared…
- [Context cards](https://beamline.io/components/context-cards): The knowledge an agent retrieved before it answered: one card per chunk with what it is about, the text it read with the search words marked, how…
- [Prompt suggestions](https://beamline.io/components/prompt-suggestions): Ready-made prompts a person can start from or follow up with: chips, cards or a list; a picked one lifts off and flies into the composer as its text…
- [Plan](https://beamline.io/components/plan): An agent's plan: numbered steps with live status, progress, and Approve / Edit / Reject when it needs sign-off; approving shows progress, and a refusal…
- [Approval card](https://beamline.io/components/approval-card): The agent stops and asks before it acts: what it wants to do, exactly what that changes, any choices it needs, and Approve or Reject; both run your…
- [Tool call](https://beamline.io/components/tool-call): One tool call in an agent's run: status, what it did and a short result on one quiet row that opens to the exact input and output; stops for permission…
- [Recommendation card](https://beamline.io/components/recommendation-card): One suggestion from the agent that the person may take or leave: what it suggests, why, the expected effect and how sure it is (a meter and a word…
- [Citations](https://beamline.io/components/citations): Inline numbered citations that preview their source on hover or focus, plus a numbered source list; streamed answers flow in at an even pace with the…
- [Reasoning](https://beamline.io/components/reasoning): The agent's trace, fed by your stream: a shimmering label and the seconds so far while it works, then "Thought for N seconds"; steps that check off…
- [Attachment](https://beamline.io/components/attachment): A file tile: preview or typed glyph with the type named, name, size, upload progress, error with retry, and a keyboard-reachable remove.
- [Prompt bar](https://beamline.io/components/prompt-bar): The agent composer: a field that grows, @ to add a source, / for a command, a model picker, files and dictation, and one button that sends with progress…
- [Selection actions](https://beamline.io/components/selection-actions): Select a passage and hand it to the agent: a bar over the selection with quick actions, your own instruction and More; while the agent works it says so…
- [Message](https://beamline.io/components/message): One turn in a conversation with an agent: the person's words in a quiet bubble, the agent's answer on the page with its orb mark, trace, tool calls and…