ChatBubbles Component

Animated chat message display component with auto-scrolling, consecutive message grouping, and typing indicators

ChatBubbles Component

The ChatBubbles component provides a polished chat message display with smooth animations, intelligent message grouping, auto-scrolling behavior, and integrated typing indicators. It automatically renders messages using Cedar’s message rendering system and adapts to different container sizes.

Features

• Smooth Animations: Framer Motion powered message entrance animations
• Auto-Scrolling: Automatic scroll to bottom on new messages
• Message Grouping: Consecutive messages from same sender are visually grouped
• Typing Indicator: Animated typing indicator during message processing
• Flexible Sizing: Support for both fixed height and flexible containers
• Performance Optimized: Efficient scrolling with paint containment
• Dark Mode: Full dark mode support with theme integration
• Custom Scrollbar: Styled scrollbars for better visual integration

Import

import { ChatBubbles } from 'cedar-os-components/chatMessages/ChatBubbles';

Basic Usage

import { ChatBubbles } from 'cedar-os-components/chatMessages/ChatBubbles';

// Flexible height container (recommended for full-screen chats)
<ChatBubbles />

// Fixed height container
<ChatBubbles maxHeight="400px" />

Advanced Usage

With Custom Container Styling

<ChatBubbles
	maxHeight='60vh'
	className='border rounded-lg bg-gray-50 dark:bg-gray-900'
/>

In a Chat Interface Layout

const ChatInterface = () => {
	return (
		<div className='flex flex-col h-screen'>
			{/* Header */}
			<div className='border-b p-4'>
				<h1>Chat</h1>
			</div>

			{/* Messages - flexible height */}
			<div className='flex-1 min-h-0'>
				<ChatBubbles />
			</div>

			{/* Input */}
			<div className='border-t p-4'>
				<ChatInput />
			</div>
		</div>
	);
};

With Constrained Height

const SidebarChat = () => {
	return (
		<div className='w-80 h-full flex flex-col'>
			<div className='p-4'>
				<h2>Quick Chat</h2>
			</div>

			{/* Fixed height messages */}
			<ChatBubbles maxHeight='300px' className='border-y' />

			<div className='p-4'>
				<ChatInput />
			</div>
		</div>
	);
};

Props

maxHeight · string

Maximum height for the message container. When provided, creates a fixed-height scrollable container. When omitted, uses flex-1 for flexible height. Examples: “300px”, “60vh”, “20rem”

className · string · default: ""

Additional CSS classes for the container. Applied to the outer container element.

Behavior

Message Grouping

The component automatically groups consecutive messages from the same sender:

• First message in a group: Full spacing (mt-2)
• Consecutive messages: Reduced spacing (mt-1)
• Different senders: Full spacing between groups

// Visual grouping example:
// [User] Hello there        ← mt-2 (first message)
// [User] How are you?       ← mt-1 (consecutive)
// [Assistant] I'm doing well ← mt-2 (different sender)
// [Assistant] Thanks for asking ← mt-1 (consecutive)

Auto-Scrolling

• Initial render: Immediate scroll to bottom (useLayoutEffect)
• New messages: Smooth scroll to bottom when messages change
• Performance: Uses scrollTo with smooth behavior for fluid UX

Typing Indicator

When isProcessing is true in the Cedar store:

• Shows animated typing dots
• Positioned as assistant message
• Smooth entrance/exit animations
• Themed to match current styling

Message Rendering

The component integrates with Cedar’s message rendering system:

• Uses ChatRenderer for individual message display
• Supports all Cedar message types (text, tool calls, human-in-the-loop, etc.)
• Automatic message type detection and appropriate rendering
• Custom message renderers are supported through Cedar’s renderer system

Styling and Theming

Container Styling

// Default flexible container
<ChatBubbles className="bg-white dark:bg-gray-800" />

// Fixed height with custom styling
<ChatBubbles
  maxHeight="400px"
  className="border border-gray-200 dark:border-gray-700 rounded-lg shadow-sm"
/>

Scrollbar Customization

The component includes custom scrollbar styling:

/* Firefox scrollbar styling */
scrollbar-color: rgba(156, 163, 175, 0.8) transparent;

/* Webkit scrollbar styling (applied via Tailwind) */
/* Customize through global CSS if needed */

Message Animations

Messages use Framer Motion with these default animations:

// Entrance animation
initial={{
  opacity: 0,
  y: 20,
  filter: 'blur(4px)',
}}
animate={{
  opacity: 1,
  y: 0,
  filter: 'blur(0px)',
}}
transition={{
  duration: 0.15,
  ease: 'easeOut',
}}

Integration Examples

Complete Chat Application

import { ChatBubbles, ChatInput } from 'cedar-os-components';
import { useCedarStore } from 'cedar-os';

const ChatApp = () => {
	const messages = useCedarStore((state) => state.messages);
	const isProcessing = useCedarStore((state) => state.isProcessing);

	return (
		<div className='h-screen flex flex-col bg-gray-50 dark:bg-gray-900'>
			{/* Header */}
			<header className='border-b border-gray-200 dark:border-gray-700 p-4'>
				<div className='flex items-center justify-between'>
					<h1 className='text-xl font-semibold'>Cedar Chat</h1>
					<div className='text-sm text-gray-500'>
						{messages.length} messages
					</div>
				</div>
			</header>

			{/* Messages */}
			<main className='flex-1 min-h-0'>
				<ChatBubbles />
			</main>

			{/* Input */}
			<footer className='border-t border-gray-200 dark:border-gray-700 p-4'>
				<ChatInput />
			</footer>
		</div>
	);
};

Embedded Chat Widget

const ChatWidget = ({ isOpen, onClose }) => {
	if (!isOpen) return null;

	return (
		<div className='fixed bottom-4 right-4 w-96 h-[500px] bg-white dark:bg-gray-800 rounded-lg shadow-xl border border-gray-200 dark:border-gray-700 flex flex-col'>
			{/* Widget header */}
			<div className='flex items-center justify-between p-3 border-b border-gray-200 dark:border-gray-700'>
				<span className='font-medium'>Chat Support</span>
				<button onClick={onClose} className='text-gray-400 hover:text-gray-600'>
					<X size={20} />
				</button>
			</div>

			{/* Messages with fixed height */}
			<div className='flex-1 min-h-0'>
				<ChatBubbles />
			</div>

			{/* Input */}
			<div className='p-3 border-t border-gray-200 dark:border-gray-700'>
				<ChatInput className='bg-gray-50 dark:bg-gray-700/50' />
			</div>
		</div>
	);
};

Multi-Column Layout

const MultiColumnChat = () => {
	return (
		<div className='h-screen flex'>
			{/* Sidebar */}
			<div className='w-64 border-r border-gray-200 dark:border-gray-700 p-4'>
				<h2>Conversations</h2>
				{/* Conversation list */}
			</div>

			{/* Main chat */}
			<div className='flex-1 flex flex-col'>
				<div className='border-b border-gray-200 dark:border-gray-700 p-4'>
					<h1>Current Chat</h1>
				</div>

				{/* Messages take remaining space */}
				<div className='flex-1 min-h-0'>
					<ChatBubbles />
				</div>

				<div className='border-t border-gray-200 dark:border-gray-700 p-4'>
					<ChatInput />
				</div>
			</div>

			{/* Right panel */}
			<div className='w-80 border-l border-gray-200 dark:border-gray-700 p-4'>
				<h2>Context</h2>
				{/* Context information */}
			</div>
		</div>
	);
};

Performance Considerations

Container Optimization

// The component uses paint containment for better performance
style={{
  contain: 'paint layout'
}}

Scroll Performance

• Uses scrollTo instead of scrollIntoView for better control
• Immediate scroll on initial render prevents flash
• Smooth scrolling for subsequent updates

Animation Performance

• Uses will-change: transform for smooth animations
• Blur effects are hardware accelerated
• Short animation duration (0.15s) for responsiveness

Accessibility

Screen Reader Support

• Messages are announced as they appear
• Proper semantic structure with message roles
• Typing indicator is announced appropriately

Keyboard Navigation

• Scrollable content is keyboard accessible
• Focus management integrates with ChatInput
• Proper tab order maintained

Visual Accessibility

• High contrast support in both light and dark modes
• Respects user’s motion preferences
• Clear visual hierarchy with proper spacing

Best Practices

Layout Design

// ✅ Good: Use flex-1 for main chat interfaces
<div className="flex flex-col h-screen">
  <Header />
  <div className="flex-1 min-h-0">
    <ChatBubbles />
  </div>
  <ChatInput />
</div>

// ✅ Good: Use maxHeight for constrained spaces
<ChatBubbles maxHeight="300px" />

// ❌ Avoid: Fixed height without maxHeight prop
<div style={{ height: '300px' }}>
  <ChatBubbles /> {/* Will not scroll properly */}
</div>

Performance

// ✅ Good: Let the component handle scrolling
<ChatBubbles />

// ❌ Avoid: Manual scroll management
<div onScroll={handleScroll}>
  <ChatBubbles />
</div>

Styling

// ✅ Good: Use className for container styling
<ChatBubbles
	maxHeight='60vh'
	className='border rounded-lg bg-white dark:bg-gray-800'
/>

// ✅ Good: Respect theme system
// Component automatically adapts to Cedar's theme

Troubleshooting

Scrolling Issues

Problem: Messages don’t scroll to bottom Solution: Ensure parent container has proper height constraints

// ✅ Correct
<div className="h-screen flex flex-col">
  <div className="flex-1 min-h-0">
    <ChatBubbles />
  </div>
</div>

// ❌ Incorrect
<div className="flex flex-col">
  <ChatBubbles /> {/* No height constraint */}
</div>

Animation Performance

Problem: Choppy animations on mobile Solution: Reduce motion for better performance

// Add to your global CSS for motion-sensitive users
@media (prefers-reduced-motion: reduce) {
  .chat-message {
    animation: none;
    transition: none;
  }
}

Message Grouping

Problem: Messages not grouping correctly Solution: Ensure message roles are consistent

// Messages need consistent role values
const messages = [
	{ id: '1', role: 'user', content: 'Hello' },
	{ id: '2', role: 'user', content: 'How are you?' }, // Same role = grouped
	{ id: '3', role: 'assistant', content: 'I am well' }, // Different role = new group
];