React AI Branch

Navigate between multiple AI response variations. Build interactive chat experiences with React, Next.js, and TypeScript, featuring branch navigation and version control for shadcn/ui applications.

AI Elements

Radix UI

Lucide React

Trying to implement AI Elements?

Join our Discord community for help from other developers.

Users want to compare different AI responses without losing the good ones. This builds branching into your chat UI so they can navigate between variations instead of refreshing and hoping for better luck.

Response branching

Navigate between different AI response variations:

Loading component...

'use client';import {  Branch,  BranchMessages,  BranchNext,  BranchPage,  BranchPrevious,  BranchSelector,} from '@/components/ui/shadcn-io/ai/branch';import { Message, MessageAvatar, MessageContent } from '@/components/ui/shadcn-io/ai/message';import { nanoid } from 'nanoid';const userMessages = [  {    id: nanoid(),    content: 'What are the key strategies for optimizing React performance?',  },  {    id: nanoid(),    content: 'How can I improve the performance of my React application?',  },  {    id: nanoid(),    content: 'What performance optimization techniques should I use in React?',  },];const assistantMessages = [  {    id: nanoid(),    content:      "Here's the first response to your question. This approach focuses on performance optimization.",  },  {    id: nanoid(),    content:      "Here's an alternative response. This approach emphasizes code readability and maintainability over pure performance.",  },  {    id: nanoid(),    content:      "And here's a third option. This balanced approach considers both performance and maintainability, making it suitable for most use cases.",  },];const Example = () => {  const handleBranchChange = (branchIndex: number) => {    console.log('Branch changed to:', branchIndex);  };  return (    <div style={{ height: '300px' }}>      <Branch defaultBranch={0} onBranchChange={handleBranchChange}>        <BranchMessages>          {userMessages.map((message) => (            <Message from="user" key={message.id}>              <MessageContent>{message.content}</MessageContent>              <MessageAvatar                name="Dov Azencot"                src="https://github.com/dovazencot.png"              />            </Message>          ))}        </BranchMessages>        <BranchSelector from="user">          <BranchPrevious />          <BranchPage />          <BranchNext />        </BranchSelector>      </Branch>      <Branch defaultBranch={0} onBranchChange={handleBranchChange}>        <BranchMessages>          {assistantMessages.map((message) => (            <Message from="assistant" key={message.id}>              <MessageContent>{message.content}</MessageContent>              <MessageAvatar name="AI" src="https://github.com/openai.png" />            </Message>          ))}        </BranchMessages>        <BranchSelector from="assistant">          <BranchPrevious />          <BranchPage />          <BranchNext />        </BranchSelector>      </Branch>    </div>  );};export default Example;

'use client';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';import type { UIMessage } from 'ai';import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';import type { ComponentProps, HTMLAttributes, ReactElement } from 'react';import { createContext, useContext, useEffect, useState } from 'react';type BranchContextType = {  currentBranch: number;  totalBranches: number;  goToPrevious: () => void;  goToNext: () => void;  branches: ReactElement[];  setBranches: (branches: ReactElement[]) => void;};const BranchContext = createContext<BranchContextType | null>(null);const useBranch = () => {  const context = useContext(BranchContext);  if (!context) {    throw new Error('Branch components must be used within Branch');  }  return context;};export type BranchProps = HTMLAttributes<HTMLDivElement> & {  defaultBranch?: number;  onBranchChange?: (branchIndex: number) => void;};export const Branch = ({  defaultBranch = 0,  onBranchChange,  className,  ...props}: BranchProps) => {  const [currentBranch, setCurrentBranch] = useState(defaultBranch);  const [branches, setBranches] = useState<ReactElement[]>([]);  const handleBranchChange = (newBranch: number) => {    setCurrentBranch(newBranch);    onBranchChange?.(newBranch);  };  const goToPrevious = () => {    const newBranch =      currentBranch > 0 ? currentBranch - 1 : branches.length - 1;    handleBranchChange(newBranch);  };  const goToNext = () => {    const newBranch =      currentBranch < branches.length - 1 ? currentBranch + 1 : 0;    handleBranchChange(newBranch);  };  const contextValue: BranchContextType = {    currentBranch,    totalBranches: branches.length,    goToPrevious,    goToNext,    branches,    setBranches,  };  return (    <BranchContext.Provider value={contextValue}>      <div        className={cn('grid w-full gap-2 [&>div]:pb-0', className)}        {...props}      />    </BranchContext.Provider>  );};export type BranchMessagesProps = HTMLAttributes<HTMLDivElement>;export const BranchMessages = ({ children, ...props }: BranchMessagesProps) => {  const { currentBranch, setBranches, branches } = useBranch();  const childrenArray = Array.isArray(children) ? children : [children];  // Use useEffect to update branches when they change  useEffect(() => {    if (branches.length !== childrenArray.length) {      setBranches(childrenArray);    }  }, [childrenArray, branches, setBranches]);  return childrenArray.map((branch, index) => (    <div      className={cn(        'grid gap-2 overflow-hidden [&>div]:pb-0',        index === currentBranch ? 'block' : 'hidden'      )}      key={branch.key}      {...props}    >      {branch}    </div>  ));};export type BranchSelectorProps = HTMLAttributes<HTMLDivElement> & {  from: UIMessage['role'];};export const BranchSelector = ({  className,  from,  ...props}: BranchSelectorProps) => {  const { totalBranches } = useBranch();  // Don't render if there's only one branch  if (totalBranches <= 1) {    return null;  }  return (    <div      className={cn(        'flex items-center gap-2 self-end px-10',        from === 'assistant' ? 'justify-start' : 'justify-end',        className      )}      {...props}    />  );};export type BranchPreviousProps = ComponentProps<typeof Button>;export const BranchPrevious = ({  className,  children,  ...props}: BranchPreviousProps) => {  const { goToPrevious, totalBranches } = useBranch();  return (    <Button      aria-label="Previous branch"      className={cn(        'size-7 shrink-0 rounded-full text-muted-foreground transition-colors',        'hover:bg-accent hover:text-foreground',        'disabled:pointer-events-none disabled:opacity-50',        className      )}      disabled={totalBranches <= 1}      onClick={goToPrevious}      size="icon"      type="button"      variant="ghost"      {...props}    >      {children ?? <ChevronLeftIcon size={14} />}    </Button>  );};export type BranchNextProps = ComponentProps<typeof Button>;export const BranchNext = ({  className,  children,  ...props}: BranchNextProps) => {  const { goToNext, totalBranches } = useBranch();  return (    <Button      aria-label="Next branch"      className={cn(        'size-7 shrink-0 rounded-full text-muted-foreground transition-colors',        'hover:bg-accent hover:text-foreground',        'disabled:pointer-events-none disabled:opacity-50',        className      )}      disabled={totalBranches <= 1}      onClick={goToNext}      size="icon"      type="button"      variant="ghost"      {...props}    >      {children ?? <ChevronRightIcon size={14} />}    </Button>  );};export type BranchPageProps = HTMLAttributes<HTMLSpanElement>;export const BranchPage = ({ className, ...props }: BranchPageProps) => {  const { currentBranch, totalBranches } = useBranch();  return (    <span      className={cn(        'font-medium text-muted-foreground text-xs tabular-nums',        className      )}      {...props}    >      {currentBranch + 1} of {totalBranches}    </span>  );};

Handles branch state without Redux ceremony in React applications, uses CSS transitions so switching doesn't feel janky, and aligns navigation controls properly. Complete TypeScript definitions that actually make sense.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/ai.json

npx shadcn@latest add https://www.shadcn.io/registry/ai.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/ai.json

bunx shadcn@latest add https://www.shadcn.io/registry/ai.json

Usage

import {
  Branch,
  BranchMessages,
  BranchNext,
  BranchPage,
  BranchPrevious,
  BranchSelector,
} from "@/components/ai/branch";

<Branch defaultBranch={0}>
  <BranchMessages>
    <Message from="user">
      <MessageContent>Hello</MessageContent>
    </Message>
    <Message from="user">
      <MessageContent>Hi!</MessageContent>
    </Message>
  </BranchMessages>
  <BranchSelector from="user">
    <BranchPrevious />
    <BranchPage />
    <BranchNext />
  </BranchSelector>
</Branch>;

Why not just use a state library?

Most developers reach for Zustand or Redux for branch management in React applications. That's overkill. This React component handles the state you actually need—current branch index and navigation—without the ceremony.

Users don't get perfect responses on the first try in Next.js applications. They want to see alternatives without losing what's already good. Before this free open source component, they'd copy-paste responses into notes apps like animals.

Usage with Vercel AI SDK

Vercel AI SDK focuses on streaming and generation—it doesn't handle response variations in JavaScript applications. That's where this TypeScript component fits in. You manage the array of responses, we handle the UI for React applications:

"use client";

import {
  Branch,
  BranchMessages,
  BranchSelector,
  BranchPrevious,
  BranchPage,
  BranchNext,
} from "@/components/ai/branch";
import { Message, MessageContent } from "@/components/ai/message";
import { useState } from "react";

export default function Chat() {
  const [responses, setResponses] = useState<string[]>([]);
  const [currentBranch, setCurrentBranch] = useState(0);

  const generateVariation = async () => {
    // Your AI generation logic
    const newResponse = await generateResponse();
    setResponses([...responses, newResponse]);
  };

  return (
    <Branch defaultBranch={currentBranch} onBranchChange={setCurrentBranch}>
      <BranchMessages>
        {responses.map((response, index) => (
          <Message from="assistant" key={index}>
            <MessageContent>{response}</MessageContent>
          </Message>
        ))}
      </BranchMessages>
      {responses.length > 1 && (
        <BranchSelector from="assistant">
          <BranchPrevious />
          <BranchPage />
          <BranchNext />
        </BranchSelector>
      )}
    </Branch>
  );
}

Features

Branch state management that doesn't require a PhD in React applications
Navigation controls that work on mobile (not tiny buttons) in Next.js projects
CSS transitions instead of re-rendering everything for JavaScript performance
Shows "2 of 5" so users know where they are in TypeScript applications
Keyboard navigation that doesn't break accessibility
Works with any Vercel AI SDK setup in React frameworks
Free open source component designed for conversational AI interfaces

API Reference

Branch

Container managing branch state and navigation.

Prop	Type	Default	Description
`defaultBranch`	`number`	`0`	Index of the branch to show by default
`onBranchChange`	`(index: number) => void`	-	Callback when branch changes
`...props`	`HTMLAttributes<HTMLDivElement>`	-	HTML attributes for root div

BranchMessages

Container for branch message variations.

Prop	Type	Description
`...props`	`HTMLAttributes<HTMLDivElement>`	HTML attributes for root div

BranchSelector

Navigation control container with alignment.

Prop	Type	Description
`from`	`UIMessage["role"]`	Aligns selector for user/assistant/system
`...props`	`HTMLAttributes<HTMLDivElement>`	HTML attributes for container

BranchPrevious / BranchNext

Navigation buttons for branch control.

Prop	Type	Description
`...props`	`ComponentProps<Button>`	Spreads to underlying Button component

BranchPage

Branch position indicator.

Prop	Type	Description
`...props`	`HTMLAttributes<HTMLSpanElement>`	HTML attributes for span element

Keyboard interactions

Key	Description
`Tab`	Move focus to navigation controls
`Enter` / `Space`	Activate focused navigation button
`ArrowLeft`	Previous branch (when focused)
`ArrowRight`	Next branch (when focused)

Things that will bite you

Branch state gets lost on refresh: Store in localStorage if users care about persistence in React applications. Most don't for casual conversations.

Users click through branches too fast: Add a small transition delay or they'll think switching is broken in Next.js projects.

Memory leaks with too many branches: Limit to 5-7 branches and auto-prune old ones in JavaScript applications. Nobody needs 20 variations.

Showing navigation with only one branch: Hide the controls when there's nothing to navigate in TypeScript components. It just confuses people.

Auto-generating variations: Never do this automatically in React applications. Users want control over when you spend their tokens.

Integration with other components

Works great with Message components for displaying the actual content in React applications. Add Actions to each branch for copy/regenerate buttons in Next.js projects. This free open source component family is designed to work together in modern JavaScript frameworks.

Response branching

Installation

Usage

Why not just use a state library?

Usage with Vercel AI SDK

Features

API Reference

Branch

BranchMessages

BranchSelector

BranchPrevious / BranchNext

BranchPage

Keyboard interactions

Things that will bite you

Integration with other components

Questions developers actually ask

On this page

React AI Branch

Reactai/branch

Reactai/message

How do I persist branches across sessions?

Should I limit the number of branches?

When should I auto-generate variations?

How can users compare branches side-by-side?

How do I track which branch users prefer?

On this page