branching | Dosu

import { BranchingSample } from "@/components/docs/samples/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 */}
      ...
    </MessagePrimitive.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 scope and may only be called inside a message component.

import { useAui, useAuiState } from "@assistant-ui/react";

// read branch state
const { branchNumber, branchCount } = useAuiState((s) => s.message);

// navigation
const aui = useAui();
aui.message().switchToBranch({ position: "next" });
aui.message().switchToBranch({ position: "previous" });
aui.message().switchToBranch({ branchId: "some-id" });