Skip to main content
Welcome to the WhatsApp Chat application documentation. This project delivers a production-ready messaging experience with real-time updates, media sharing, and an authentic WhatsApp-inspired interface.

​
What you’ll build

A complete chat application featuring:
  • Real-time messaging with delivery status indicators (sent, delivered, read)
  • Chat list management with unread counts, search, and pinned conversations
  • Media sharing with drag-and-drop image uploads and previews
  • Message status system tracking message lifecycle from queued to read
  • Contact management with online presence and last seen timestamps
  • Typing indicators showing when contacts are composing messages
  • Draft message persistence automatically saving unfinished messages
  • Responsive design optimized for mobile, tablet, and desktop
  • WhatsApp-like UI with custom theming and smooth animations

​
Key features

Real-time messaging

Send and receive messages with instant delivery status updates using Zustand state management and automated message lifecycle simulation.

Media sharing

Share images with drag-and-drop upload, preview thumbnails, and caption support. Built with react-dropzone for seamless file handling.

Smart search

Search conversations by contact name or message content with search history that persists across sessions.

Status indicators

Track message delivery with visual status icons: queued, sending, sent, delivered, and read with color-coded feedback.

Typing awareness

See when contacts are typing with animated indicators that automatically timeout after periods of inactivity.

Draft persistence

Never lose your messages – drafts are automatically saved to localStorage and restored when you return to a conversation.

​
Tech stack

This application is built with modern web technologies:
  • Next.js 15 with App Router and React Server Components
  • React 19 with hooks for state management
  • Zustand for predictable state management with persistence
  • TypeScript for type safety and better developer experience
  • Tailwind CSS v4 with custom theming and animations
  • Radix UI for accessible, unstyled component primitives
  • Phosphor Icons for the complete icon set
  • date-fns for date formatting and relative timestamps

​
Architecture overview

The application follows a component-based architecture: 
components/chat/
├── chat-app.tsx          // Main application container
├── chat-panel.tsx        // Active conversation view
├── sidebar.tsx           // Chat list with search
├── message-bubble.tsx    // Individual message display
├── message-composer.tsx  // Message input with media
└── typing-indicator.tsx  // Animated typing dots

lib/chat/
├── state.ts             // Zustand store definition
├── types.ts             // TypeScript interfaces
├── helpers.ts           // Utility functions
└── mock-data.ts         // Demo chat data

​
Get started

Quickstart

Get the chat app running in 5 minutes with our step-by-step guide

Installation

Detailed installation instructions for npm, yarn, or pnpm

​
Core concepts

​
State management

The application uses Zustand for centralized state management with localStorage persistence. All chat data, messages, contacts, and drafts are stored in a single store: 
const useChatStore = create<ChatStore>()(persist(
  (set, get) => ({
    chats: {},
    messages: {},
    contacts: {},
    drafts: {},
    sendMessage: (chatId, payload) => { /* ... */ },
    receiveMessage: (chatId, message) => { /* ... */ },
  }),
  { name: 'chat-store' }
))

​
Message lifecycle

Messages progress through multiple states automatically:
  1. queued – Message created locally
  2. sending – Upload in progress
  3. sent – Delivered to server
  4. delivered – Received by recipient
  5. read – Viewed by recipient
The status system is implemented in lib/chat/state.ts with automated transitions: 
const steps: MessageStatus[] = ["queued", "sending", "sent", "delivered", "read"]
steps.forEach((status, idx) => {
  const delay = initialDelay + idx * 450
  setTimeout(() => updateMessageStatus(messageId, status), delay)
})

​
Responsive layout

The chat interface adapts to screen size:
  • Mobile: Single-column view with navigation between chat list and conversation
  • Tablet/Desktop: Side-by-side layout with persistent chat list sidebar
Implemented using Tailwind’s responsive utilities and the useIsMobile hook.

​
Next steps

Ready to build your chat application? Start with the Quickstart guide to get up and running, or dive into the Installation instructions for detailed setup steps.

Build docs developers (and LLMs) love

Get started for freeTalk to us