ChatBubble

A chat UI component supporting three message role variants. Bold-bordered bubbles with shadow offsets give the conversation interface a distinctive personality.

Demo

Preview

对话开始于 2025-06-01

AL

Alex

嘿！这个新粗野主义 UI 库看起来太赞了！

14:01

我

我

对吧！粗边框 + 硬朗阴影，直接把普通组件卷死。

14:02

AL

Alex

Kanban + TreeView 这两个复合组件是重头戏 🔥

14:03

我

我

还有 Carousel！Embla 驱动的，性能拉满 💪

14:03

颜色（仅 sent 生效）

AL

Alex

received 不受 color 影响

14:00

我

我

default 配色

14:01

我

我

primary 配色

14:02

我

我

accent 配色

14:03

尺寸

我

我

sm 小号气泡

14:00

我

我

default 默认气泡

14:01

我

我

lg 大号气泡

14:02

Installation

pnpm dlx brutx-vue@latest add chat-bubble

Usage

vue

<script setup>
import { ChatBubble } from 'brutx-ui-vue'

const message = {
    id: '1',
    variant: 'received',
    name: 'Alex',
    content: 'This UI library is amazing!',
    timestamp: '14:01',
}
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'received', name: 'Alex', content: 'Hello!' }" />
        <ChatBubble :message="{ id: '2', variant: 'sent', content: 'Hey!' }" />
        <ChatBubble :message="{ id: '3', variant: 'system', content: 'Conversation started' }" />
    </div>
</template>

Color Variants

The color prop switches the background color scheme for variant="sent" bubbles, combining orthogonally with variant (e.g., variant="sent" color="accent"). received and system bubbles are not affected by color.

vue

<script setup>
import { ChatBubble } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'sent', content: 'Default color', timestamp: '14:00' }" color="default" />
        <ChatBubble :message="{ id: '2', variant: 'sent', content: 'Primary color', timestamp: '14:01' }" color="primary" />
        <ChatBubble :message="{ id: '3', variant: 'sent', content: 'Accent color', timestamp: '14:02' }" color="accent" />
    </div>
</template>

Variants

Message Roles

Variant	Style	Purpose
`received`	Left-aligned, background color	Messages from others
`sent`	Right-aligned, primary color background	Messages sent by yourself
`system`	Centered, italic, dashed border, no shadow, forced text-xs	System notifications

Note: The system variant ignores the size prop and always uses text-xs. It also hides the avatar and sender name.

Colors

Color	Description
`default`	Default color scheme; sent bubbles use primary color (brutal-primary) background
`primary`	Primary color scheme; sent bubbles use primary color (brutal-primary) background with primary color shadow (shadow-brutal-primary)
`accent`	Accent color scheme; sent bubbles use accent color (brutal-accent) background

Sizes

The size prop controls bubble padding, text size, and avatar dimensions simultaneously.

Size	Bubble Padding	Text Size	Avatar Size
`sm`	`px-3 py-1.5`	`text-xs`	`w-6 h-6`
`default`	`px-4 py-2.5`	`text-sm`	`w-8 h-8`
`lg`	`px-5 py-3.5`	`text-base`	`w-10 h-10`

vue

<script setup>
import { ChatBubble } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'sent', name: 'Me', content: 'Small bubble', timestamp: '14:00' }" size="sm" />
        <ChatBubble :message="{ id: '2', variant: 'sent', name: 'Me', content: 'Default bubble', timestamp: '14:01' }" size="default" />
        <ChatBubble :message="{ id: '3', variant: 'sent', name: 'Me', content: 'Large bubble', timestamp: '14:02' }" size="lg" />
    </div>
</template>

Sub-components

ChatContainer

A chat message container with time-based grouping support:

vue

<script setup>
import { ChatContainer } from 'brutx-ui-vue'

const messages = [
    { id: '1', variant: 'received', name: 'Alex', content: 'Hello!', timestamp: new Date() },
    { id: '2', variant: 'sent', content: 'Hey!', timestamp: new Date(), status: 'read' },
]
</script>

<template>
    <ChatContainer :messages="messages" group-by-time show-status />
</template>

Data Types

ChatMessage

ts

interface ChatMessage {
    id: string                        // Unique message identifier (required)
    content: string                   // Message text content (required)
    variant?: 'sent' | 'received' | 'system'  // Message variant, defaults to 'received'
    avatar?: string                   // Avatar image URL; falls back to initials on load failure
    name?: string                     // Sender name, used for display and initial generation
    timestamp?: string | Date         // Timestamp; strings are displayed directly, Date objects are formatted via dateFormat or toLocaleString
    status?: MessageStatus            // Message status, only effective for variant="sent"
}

MessageStatus

ts

type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed'

Status	Icon	Style
`sending`	Spinning loader icon	Semi-transparent + rotation animation
`sent`	Single check	Semi-transparent
`delivered`	Double check	Slightly darker
`read`	Double check	Theme primary color
`failed`	Warning icon	Destructive color

Note: status is a closed union type at the type level, but message data usually comes from backend APIs and may carry values outside the enum at runtime; in that case ChatBubble silently ignores the status (no status icon is rendered) without throwing an error.

Props

ChatBubble

Prop	Type	Default	Description
`message`	`ChatMessage`	—	Message data object (required)
`color`	`'default' \| 'primary' \| 'accent'`	`'default'`	Background color scheme for sent bubbles; only effective for `variant="sent"`, received/system are unaffected
`size`	`'sm' \| 'default' \| 'lg'`	`'default'`	Bubble padding/text size, also adjusts avatar size
`showAvatar`	`boolean`	`true`	Whether to show the avatar area (system messages always hidden)
`showStatus`	`boolean`	`true`	Whether to show the message status icon (sent messages only)
`showTimestamp`	`boolean`	`true`	Whether to show the timestamp
`dateFormat`	`(date: Date) => string`	—	Custom date formatting function; uses `Date.toLocaleString()` when unset
`class`	`string`	—	Custom CSS class for the bubble

ChatContainer

Prop	Type	Default	Description
`messages`	`ChatMessage[]`	—	Message array (required)
`groupByTime`	`boolean`	`false`	Whether to group by time (today/yesterday/date)
`groupInterval`	`number`	`5`	Time grouping interval (minutes) within the same date, clamped to a minimum of 1; adjacent messages whose gap exceeds this interval (strictly `>`) are split into a new group
`showAvatar`	`boolean`	`true`	Whether to show avatars
`showStatus`	`boolean`	`true`	Whether to show message status
`showTimestamp`	`boolean`	`true`	Whether to show timestamps
`dateFormat`	`(date: Date) => string`	—	Custom date formatting function, also used for group date labels (non today/yesterday) and interval-split group time labels
`class`	`string`	—	Custom CSS class

Note: When groupByTime is true:
Messages with a valid timestamp are sorted by timestamp ascending, so unordered input still yields continuous, non-jumping date groups; messages without a valid timestamp (missing, or display-only strings like '14:30', 'yesterday' that cannot be parsed) stay anchored at their original index — they do not sink to the end and keep their relative order;
Group boundaries are compared by the real calendar date (year/month/day), decoupled from the display string produced by dateFormat: even if a custom format outputs a time-only dimension (e.g., HH:mm), messages from different days are never merged and same-day messages are never split into separate date groups;
Groups are separated by dividers and date labels (today/yesterday/specific date);
Within the same date, adjacent messages whose time gap exceeds groupInterval minutes are further split into separate groups that show the specific time (HH:mm, customizable via dateFormat), without repeating the date label.

Slots

Slot	Scope	Description
`default`	—	Custom bubble content (defaults to displaying `message.content`)

Accessibility

ARIA Attributes: ChatContainer uses role="log" for accessibility support
Semantics: Message bubbles use semantic structure, supporting correct screen reader narration