7onicDESIGN SYSTEM

ChatMessage

ChatMessage는 AI 채팅 인터페이스용 메시지 표시 컴포넌트입니다. assistant는 왼쪽, user는 오른쪽에 정렬되며, 타이핑 애니메이션, 전송 상태, 호버 액션을 지원합니다.

2
Variants
3
Sizes
Compound
4 Parts
Pure
React

Playground

Preview
messengerbubbledefault
Sure! Let me help you with that.
12:33
That makes sense!
12:34
Message
Type
AI Color
User Color
Size
Radius
Tail
Status
Avatar
Size
Options
Options
Options
<div className="flex flex-col gap-4">
  <ChatMessage avatarSize="md">
    <ChatMessageAvatar />
    <div className="flex flex-col gap-1">
      <ChatMessageContent>Sure! Let me help you with that.</ChatMessageContent>
      <ChatMessageFooter timestamp="12:33" />
    </div>
  </ChatMessage>

  <ChatMessage role="user" color="muted">
    <div className="flex flex-col gap-1 items-end">
      <ChatMessageContent>That makes sense!</ChatMessageContent>
      <ChatMessageFooter timestamp="12:34" />
    </div>
  </ChatMessage>
</div>

Variants

How do design tokens work?
12:34
Bubble
테두리와 배경색이 있는 버블 스타일. 채팅 UI의 기본 디자인입니다.
Default
How do design tokens work?
They map values to semantic names.
Flat
배경 없는 플랫 스타일. 콘텐츠 중심 레이아웃에 적합합니다.
Minimal

Sizes

sm
패딩12 × 6px
폰트13px
Avatar24px
default
패딩14 × 8px
폰트14px
Avatar28px
lg
패딩16 × 10px
폰트16px
Avatar32px

Features

Role

role="assistant"는 왼쪽 정렬, role="user"는 오른쪽 정렬로 표시됩니다. role에 따라 레이아웃과 정렬이 자동으로 전환됩니다.

How can I help you?
12:34
That makes sense!
Read12:35
<ChatMessage role="assistant">
  <ChatMessageAvatar />
  <div className="flex flex-col gap-1">
    <ChatMessageContent>How can I help you?</ChatMessageContent>
    <ChatMessageFooter timestamp="12:34" />
  </div>
</ChatMessage>

<ChatMessage role="user" color="muted">
  <div className="flex flex-col gap-1 items-end">
    <ChatMessageContent>That makes sense!</ChatMessageContent>
    <ChatMessageFooter timestamp="12:35" status="read" />
  </div>
</ChatMessage>

UI Type

Messenger는 버블 스타일 채팅 UI, History는 플랫 스타일 히스토리 UI입니다. 용도에 맞게 선택해 사용합니다.

Messenger
Sure! Let me help.
12:33
That makes sense!
Read12:34
History
Sure! Let me help.
That makes sense!

Typing

typing=true로 설정하면 Content 영역에 타이핑 점 애니메이션이 표시됩니다. AI 응답 스트리밍 중에 사용합니다.

Here is the previous message.
12:34
<ChatMessage role="assistant" typing>
  <ChatMessageAvatar />
  <ChatMessageContent />
</ChatMessage>

Actions

actions prop에 ReactNode를 전달하면 버블에 호버 시 액션 버튼이 표시됩니다.

Hover over the bubble to reveal actions.
12:34
<ChatMessage
  role="assistant"
  actions={
    <button className="p-1 rounded hover:bg-background-muted">
      <svg>...</svg>
    </button>
  }
>
  <ChatMessageAvatar />
  <div className="flex flex-col gap-1">
    <ChatMessageContent>How can I help?</ChatMessageContent>
    <ChatMessageFooter timestamp="12:34" />
  </div>
</ChatMessage>

API

Component Structure

ChatMessage— Compound · Pure React
ChatMessage컨텍스트 프로바이더 + flex 컨테이너
ChatMessageAvatar아바타(이미지, 이니셜, 아이콘)
ChatMessageContent버블 또는 플랫 메시지 내용
ChatMessageFooter타임스탬프와 전송 상태

서브컴포넌트 구성. ChatMessage(루트), ChatMessageAvatar, ChatMessageContent, ChatMessageFooter로 구성됩니다.

Props

ChatMessage

role"assistant"
"assistant" | "user"

발신자 role. assistant는 왼쪽 정렬, user는 오른쪽 정렬. 버블 색상도 자동 전환

variant"bubble"
"bubble" | "flat"

버블 스타일. bubble(테두리), flat(배경 없음)

color"default"
"default" | "muted" | "primary" | "dark"

버블 배경색. default(테두리), muted(연한 배경), primary(브랜드), dark

size"default"
"sm" | "default" | "lg"

사이즈 스케일. sm, default, lg

radius"2xl"
"md" | "lg" | "xl" | "2xl"

버블 모서리 둥글기

tailtrue
boolean

비대칭 테일, 아바타 쪽 버블 모서리를 0으로 설정합니다

avatarSizeundefined
"sm" | "md" | "lg"

아바타 크기, 버블과의 간격도 함께 조정됩니다

typingfalse
boolean | { variant?: "dots" | "cursor", color?: "default" | "primary" | "muted", speed?: "slow" | "default" | "fast", label?: string, showLabel?: boolean }

Content 영역에 타이핑 점 애니메이션 표시

actionsundefined
ReactNode

호버 시 표시되는 액션 버튼(복사, 리액션 등)

classNameundefined
string

추가 CSS 클래스

ChatMessageAvatar

size"md"
"sm" | "md" | "lg"

아바타 표시 크기

srcundefined
string

아바타 이미지 URL

alt"Avatar"
string

아바타 이미지 대체 텍스트

initialsundefined
string

이미지 없을 때 표시되는 이니셜(1~2자)

iconundefined
ReactNode

아바타 안에 표시되는 커스텀 아이콘

classNameundefined
string

추가 CSS 클래스

ChatMessageContent

classNameundefined
string

추가 CSS 클래스

ChatMessageFooter

timestampundefined
string

타임스탬프 문자열(예: "12:34 PM")

statusundefined
ReactNode | "sending" | "sent" | "read" | "error"

전송 상태. sending, sent, read, error

sizeundefined
"sm" | "default" | "lg"

푸터 폰트 크기 오버라이드. 생략 시 ChatMessage root의 컨텍스트 값을 사용합니다

classNameundefined
string

추가 CSS 클래스

Anatomy

1
2
AI
3
Message text
4Read12:34
1
ChatMessage
role 기반 flex 레이아웃 컨테이너
2
ChatMessageAvatar
발신자 아바타
3
ChatMessageContent
스타일이 적용된 메시지 버블
4
ChatMessageFooter
타임스탬프와 전송 상태

Best Practices

✓

권장

  • ✓role="assistant"에는 ChatMessageAvatar를 포함합니다
  • ✓user 메시지 Footer에 status를 지정해 전송 상태를 표시합니다
  • ✓typing=true일 때 ChatMessageContent를 비워 둡니다
✕

지양

  • ✗role="user"에 ChatMessageAvatar를 배치하지 않습니다
  • ✗typing과 children을 동시에 사용하지 않습니다
  • ✗일반 콘텐츠 표시에는 사용하지 않습니다. Card를 사용하세요

Accessibility

키보드 조작

Tab액션 버튼으로 포커스 이동
Enter / Space포커스된 액션 실행

ARIA / WCAG

  • 아바타에 aria-hidden="true" 설정(장식용 요소)
  • 전송 상태는 스크린 리더가 읽을 수 있는 텍스트로 표시
  • 타이핑 점에 aria-hidden="true" 설정