whatsapp-ui-react

A React component library that provides a chat window interface inspired by the design and interaction patterns of WhatsApp Web.

Notice: Some components are still placeholders and may not be fully functional; breaking changes may occur between releases.

Goal

This library was created to better understand WhatsApp's design system and interaction patterns. It is intended purely for educational purposes, including studying UI architecture, component composition, and interaction modeling. It is not intended to be an official client or production-ready replacement.

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners.

Install

npm install whatsapp-ui-react

Peer dependencies: React 18+ and TailwindCSS v4.

Setup

/* global.css */
@import 'tailwindcss';
@import 'whatsapp-ui-react/css/natural.css';
@import 'whatsapp-ui-react/css/preset.css';

Available themes: natural (default), ocean, forest, rose.

Use theme="dark" on <Chat> to switch to the dark variant of the loaded theme:

<Chat theme="dark" ... />

Usage

Chat

import { Chat } from 'whatsapp-ui-react';
<Chat name="Alice" subtitle="online" />

Messages

import { Chat, History, Message, Text } from 'whatsapp-ui-react';

<Chat name="Alice">
  <History>
    <Message direction="in" senderId="alice" timestamp="2026-03-03T09:41:00Z" mode="neutral" time="09:41">
      <Text content="Hey! 👋" />
    </Message>
    <Message direction="out" senderId="me" timestamp="2026-03-03T09:42:00Z" mode="neutral" time="09:42" status="read">
      <Text content="Hi! How are you?" />
    </Message>
  </History>
</Chat>

Animated messages

import { Chat, History, Message, Text, Animated } from 'whatsapp-ui-react';

<Chat name="Support Bot">
  <History>
    <Animated delay={1500}>
      <Message direction="in" senderId="bot" timestamp="2026-03-03T09:00:00Z" mode="neutral" time="09:00">
        <Text content="Hello! How can I help you?" />
      </Message>
    </Animated>
  </History>
</Chat>

Content types

| Component | Description | Implemented | | ------------ | ----------------------------- | ----------- | | <Text> | Plain text | ✅ | | <Image> | Image with optional caption | | | <Video> | Video with thumbnail | | | <Audio> | Audio file attachment | ✅ | | <Voice> | Voice message with waveform | ✅ | | <Sticker> | Sticker (frameless image) | ✅ | | <Gif> | Animated GIF | | | <File> | Generic file attachment | | | <Contact> | Contact card | | | <Location> | Location pin with map preview | | | <Poll> | Poll with options | | | <Emoji> | Large emoji message | | | <Event> | Event card | |

Reply rules

Automated replies that fire when an incoming message matches a trigger:

import { Chat, Message, Text, Reply } from 'whatsapp-ui-react';

<Chat
  name="Support Bot"
  onReply={
    <Reply
      once
      from="bot"
      onMessage={<Text content="!help" />}
      replyMessage={
        <Message direction="in" mode="neutral" time="now">
          <Text content="Available commands: !help, !status" />
        </Message>
      }
    />
  }
/>

| Prop | Type | Default | Description | | -------------- | ----------- | ------- | ---------------------------------------------------- | | onMessage | ReactNode | | Message content to match against (text is extracted) | | replyMessage | ReactNode | | <Message> to inject when the trigger matches | | from | string | 'me' | Only react to messages from this senderId | | once | boolean | false | Fire at most once per component lifetime |

Locked chat

Set locked to disable sending while still allowing typing:

<Chat name="Read-only" locked />

<History> props

| Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------------------------------------------------------------ | | children | ReactNode | | <Message> elements, optionally wrapped in <Animated>. Anything else is passed through as-is. | | className | string | | Additional CSS class names applied to the wrapper element |

<Animated> props

| Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------------------------------------------------- | | delay | number | 0 | Milliseconds from mount until the content fades in | | children | ReactNode | | Content to reveal | | className | string | | Additional CSS class names applied to the wrapper element |

<Message> props

| Prop | Type | Default | Description | | ------------ | ---------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | | direction | 'in' \| 'out' | | Received ('in') or sent ('out') message | | mode | 'neutral' \| 'free' \| 'custom' | 'custom' | Layout mode: 'neutral' overlays the timestamp; 'free' floats it below; 'custom' is unwrapped | | top | boolean | false | First message in a consecutive run - renders the bubble tail. Injected automatically by <History>. | | group | boolean | false | Group chat mode - shows sender avatar when top is true | | avatarUrl | string | | Sender avatar URL (group chats) | | senderName | string | | Sender display name (group chats) | | time | string | | Formatted time string shown in the bubble footer | | status | 'sending' \| 'sent' \| 'delivered' \| 'read' | | Delivery status icon (outgoing messages only) | | senderId | string | | Identifies the sender; used by <History> for grouping. No visual effect. | | timestamp | string \| Date | | ISO string or Date for the message time; used by <History> for day dividers. No visual effect. | | className | string | | Additional CSS class names applied to the root element |

<Chat> props

| Prop | Type | Default | Description | | -------------------- | -------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | name | string | | Contact or group name | | avatarUrl | string | | Avatar image URL | | subtitle | string | | Status text below the name | | children | ReactNode | | Static content rendered at the top of the message area. Typically a <History> component. | | showInputfield | boolean | true | Show / hide the input bar | | locked | boolean | false | Allow typing but disable sending | | inputPlaceholder | string | 'Enter a message.' | Textarea placeholder | | inputValue | string | | Controlled input value (use with onInputValueChange) | | defaultInputValue | string | | Uncontrolled initial value (internal state managed by component) | | onInputValueChange | (v: string) => void | | Called on every keystroke | | onSendMessage | (v: string) => void | | Called when a message is sent | | onReply | ReactNode | | <Reply> rules rendered inside the chat context | | background | string \| null | background image | Message area background. Hex color string for a solid fill; null or 'none' for plain #0a0a0a; omit to use the default tiled image. | | onEmojiClick | () => void | | Emoji button click handler | | onAttachClick | () => void | | Attach button click handler | | onCameraClick | () => void | | Camera button click handler | | onMicClick | () => void | | Mic button click handler | | theme | 'dark' \| 'light' | 'light' | Adds the dark class to the root element to activate the dark variant of the loaded colour scheme | | colorScheme | 'natural' \| 'ocean' \| 'forest' \| 'rose' | | Colour palette applied via data-wa-color. Requires the matching CSS file to be imported. Falls back to global @theme when omitted. | | width | number \| string | | Set Chat witdh | | height | number \| string | | Set Chat height |

License

This project is licensed under the Apache License 2.0.