Docs

Message Branching

Switch between different conversation branches.

A new branch is created when:

  • a user message is edited
  • an assistant message is reloaded

Branches are automatically tracked by assistant-ui by observing changes to the messages array.

Enabling branch support

You can show a branch picker by using BranchPickerPrimitive.

import { BranchPickerPrimitive } from "@assistant-ui/react";
 
 
const Message = () => {
  return (
    <MessagePrimitive.Root>
      ...
      <BranchPicker /> {/* <-- show the branch picker */}
      ...
    </EditComposerPrimitive.Root>
  );
};
 
 
const BranchPicker = () => {
  return (
    <BranchPickerPrimitive.Root hideWhenSingleBranch>
      <BranchPickerPrimitive.Previous />
      <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
      <BranchPickerPrimitive.Next />
    </BranchPickerPrimitive.Root>
  );
};

API

You can access the current branch state or navigate via the API as well.
These APIs rely on the message state and may only be called inside a message component.

const hasBranches = useMessageIf({ hasBranches: true }); // whether branchCount is >= 2
 
// navigation
const goToNextBranch = useGoToNextBranch(); // null if there is no next branch
const goToPreviousBranch = useGoToPreviousBranch(); // null if there is no previous branch