Chat Bubbles

Messages spring in, with a typing indicator.

You: Can you move my 3pm with Lena?

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/chat-bubbles.json

Manual

Install the dependencies
npm install clsx motion tailwind-merge

Add the shared helpers

Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

lib/motion.ts

import type { Transition, Variants } from "motion/react";

/** Durations in seconds. */
export const duration = {
  instant: 0.1,
  quick: 0.18,
  base: 0.28,
  slow: 0.45,
} as const;

/** Cubic-bezier curves. */
export const ease = {
  /** Entering, UI response. */
  out: [0.22, 1, 0.36, 1],
  /** Moving on screen. */
  inOut: [0.65, 0, 0.35, 1],
  /** Sheets and the mobile menu. */
  drawer: [0.32, 0.72, 0, 1],
} as const;

/** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
export const ui = {
  press: { scale: 0.96, duration: 0.12 },
  icon: { type: "spring", duration: 0.3, bounce: 0 },
  popover: { duration: 0.18, ease: ease.out },
  modal: { duration: 0.24, ease: ease.out },
  exitFactor: 0.6,
} as const;

/** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
export const kinetic = {
  heroLetter: { duration: 0.6, ease: ease.out },
  /** Delay per letter, eased so the wave slows toward the end. */
  heroStep: 0.035,
  reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
  /** Two afterimages: lag in seconds and opacity of each. */
  ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
} as const;

/** Spring presets. */
export const spring = {
  snappy: { type: "spring", stiffness: 500, damping: 30 },
  smooth: { type: "spring", stiffness: 260, damping: 26 },
  bouncy: { type: "spring", stiffness: 300, damping: 15 },
} as const satisfies Record<string, Transition>;

/** Stagger between siblings, in seconds (0.03–0.06). */
export const stagger = {
  tight: 0.03,
  base: 0.045,
  loose: 0.06,
} as const;

/** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.base } },
      exit: { opacity: 0, transition: { duration: duration.quick } },
    };
  }
  return {
    hidden: { opacity: 0, y, filter: "blur(4px)" },
    visible: {
      opacity: 1,
      y: 0,
      filter: "blur(0px)",
      transition: { duration: duration.base, ease: ease.out },
    },
    exit: {
      opacity: 0,
      y: -y / 2,
      filter: "blur(4px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
  };
}

/** Scale 0.96 → 1 for popovers, menus and dialogs. */
export function overlayVariants(reduceMotion?: boolean | null): Variants {
  if (reduceMotion) {
    return {
      hidden: { opacity: 0 },
      visible: { opacity: 1, transition: { duration: duration.quick } },
      exit: { opacity: 0, transition: { duration: duration.instant } },
    };
  }
  return {
    hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
    visible: {
      opacity: 1,
      scale: 1,
      filter: "blur(0px)",
      transition: { duration: duration.quick, ease: ease.out },
    },
    exit: {
      opacity: 0,
      scale: 0.96,
      filter: "blur(2px)",
      transition: { duration: duration.instant + 0.02, ease: ease.out },
    },
  };
}

/** Parent variants that stagger their children in. */
export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
  return {
    hidden: {},
    visible: { transition: { staggerChildren: gap, delayChildren } },
    exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
  };
}

Copy the source

components/ui/chat-bubbles/chat-bubbles.tsx

"use client";

import { useEffect, type ComponentProps, type ReactNode } from "react";
import { AnimatePresence, motion, stagger, useAnimate, useReducedMotion } from "motion/react";
import { cn } from "@/lib/utils";
import { duration } from "@/lib/motion";

export interface ChatMessage {
  /** Stable identity. */
  id: string;
  /** Who sent it. */
  role: "user" | "assistant";
  /** Message content. */
  content: ReactNode;
  /** Optional timestamp shown under the last message of a group. */
  time?: string;
}

export interface ChatBubblesProps
  extends Omit<ComponentProps<"div">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
  /** Messages, oldest first. */
  messages: ChatMessage[];
  /** Show the assistant's typing indicator after the last message. @default false */
  typing?: boolean;
  /** Name read before assistant messages. @default "Assistant" */
  assistantLabel?: string;
  /** Name read before user messages. @default "You" */
  userLabel?: string;
}

const ENTER = { type: "spring", stiffness: 420, damping: 30, mass: 0.8 } as const;

/** Bouncing dots. Started imperatively so they run even if `typing` is true on first render. */
function TypingDots({ reduceMotion }: { reduceMotion: boolean }) {
  const [scope, animate] = useAnimate<HTMLSpanElement>();
  useEffect(() => {
    const controls = animate(
      "span",
      reduceMotion ? { opacity: [0.35, 1, 0.35] } : { y: [0, -4, 0], opacity: [0.45, 1, 0.45] },
      { duration: 0.9, repeat: Infinity, delay: stagger(0.15), ease: "easeInOut" },
    );
    return () => controls.stop();
  }, [animate, reduceMotion]);
  return (
    <span ref={scope} aria-hidden="true" className="flex h-10 items-center gap-1 rounded-2xl bg-muted px-4">
      {[0, 1, 2].map((dot) => (
        <span key={dot} className="size-1.5 rounded-full bg-muted-foreground" />
      ))}
    </span>
  );
}

export function ChatBubbles({ messages, typing = false, assistantLabel = "Assistant", userLabel = "You", className, ...props }: ChatBubblesProps) {
  const reduceMotion = useReducedMotion();

  return (
    <div role="log" aria-live="polite" aria-relevant="additions" className={className} {...props}>
      <ol className="flex flex-col gap-1">
      {/* initial={false}: messages present on first render don't animate in; new ones do. */}
      <AnimatePresence initial={false}>
        {messages.map((message, i) => {
          const user = message.role === "user";
          const startsGroup = messages[i - 1]?.role !== message.role;
          const endsGroup = messages[i + 1]?.role !== message.role;
          return (
            <motion.li
              key={message.id}
              layout={!reduceMotion}
              initial={reduceMotion ? { opacity: 0 } : { opacity: 0, y: 14, scale: 0.94 }}
              animate={{ opacity: 1, y: 0, scale: 1 }}
              exit={{ opacity: 0, transition: { duration: duration.quick } }}
              transition={reduceMotion ? { duration: duration.base } : ENTER}
              style={{ originX: user ? 1 : 0, originY: 1 }}
              className={cn("flex max-w-[85%] flex-col", user ? "items-end self-end" : "items-start self-start", startsGroup && i > 0 && "mt-2")}
            >
              <div
                className={cn(
                  "px-3.5 py-2 text-sm leading-6",
                  user ? "bg-primary text-primary-foreground" : "bg-muted text-foreground",
                  // Consecutive messages from one sender share tighter inner corners, like a thread.
                  "rounded-2xl",
                  user ? !startsGroup && "rounded-tr-md" : !startsGroup && "rounded-tl-md",
                  user ? !endsGroup && "rounded-br-md" : !endsGroup && "rounded-bl-md",
                )}
              >
                <span className="sr-only">{user ? userLabel : assistantLabel}: </span>
                {message.content}
              </div>
              {endsGroup && message.time ? <span className="mt-1 px-1 text-[11px] text-muted-foreground">{message.time}</span> : null}
            </motion.li>
          );
        })}
        {typing ? (
          <motion.li
            key="typing"
            layout={!reduceMotion}
            initial={reduceMotion ? { opacity: 0 } : { opacity: 0, y: 10, scale: 0.9 }}
            animate={{ opacity: 1, y: 0, scale: 1 }}
            exit={{ opacity: 0, scale: reduceMotion ? 1 : 0.9, transition: { duration: duration.quick } }}
            transition={reduceMotion ? { duration: duration.base } : ENTER}
            style={{ originX: 0, originY: 1 }}
            className="mt-2 self-start"
          >
            <span className="sr-only">{assistantLabel} is typing</span>
            <TypingDots reduceMotion={!!reduceMotion} />
          </motion.li>
        ) : null}
      </AnimatePresence>
      </ol>
    </div>
  );
}

Usage

import { ChatBubbles } from "@/components/ui/chat-bubbles/chat-bubbles";

export function Conversation({ messages, typing }: { messages: ChatMessage[]; typing: boolean }) {
  return (
    <div className="h-96 overflow-y-auto">
      <ChatBubbles messages={messages} typing={typing} />
    </div>
  );
}

API reference

Prop	Type	Default	Description
`messages*`	`ChatMessage[]`	–	Messages, oldest first.
`typing`	`boolean`	`false`	Show the assistant's typing indicator after the last message.
`assistantLabel`	`string`	`"Assistant"`	Name read before assistant messages.
`userLabel`	`string`	`"You"`	Name read before user messages.

Also accepts every native <div> attribute, including ref and className.

New messages spring up from their sender's side; messages already present on first render don't animate.
Consecutive messages from the same sender group together with tighter inner corners, and the list re-flows with layout animation when the typing indicator comes and goes.
Scrolling is up to you: put it in a scroll container and scroll to the bottom when messages change (see the demo).

Accessibility

A polite log: new messages are announced as they arrive, each prefixed with who sent it (“You:”, “Assistant:”).
The typing indicator is announced as “Assistant is typing” and its dots are decorative.
With reduced motion enabled, messages fade in and the typing dots pulse instead of bouncing.

Installation#

CLI

Manual

Install the dependencies

Add the shared helpers

Copy the source

Usage#

API reference#

Accessibility#

Installation

Usage

API reference

Accessibility