API Reference

Complete props and types reference for all chatcn components. Every prop listed below is fully typed — hover over any component in your editor to see the full type signature.

ChatProvider

The root context provider. Wrap your entire chat UI in ChatProvider to supply theme, user, and callback configuration to all child components.

Prop	Type	Default	Description
`currentUser`	ChatUser	—	The currently authenticated user object
`theme`	ChatTheme	"lunar"	Visual theme applied to all child components
`dateFormat`	string	"relative"	Date display format: "relative", "absolute", or a custom format string
`messageGroupingInterval`	number	120000	Max milliseconds between messages to group them under one sender header
`onEdit`	(id: string, text: string) => void	—	Called when a user edits a message
`onDelete`	(id: string) => void	—	Called when a user deletes a message
`onReaction`	(id: string, emoji: string) => void	—	Called when a user adds or removes a reaction

ChatMessages

Renders the scrollable message list with grouping, read receipts, and typing indicators.

Prop	Type	Default	Description
`messages`	ChatMessageData[]	[]	Array of message objects to render
`typingUsers`	ChatUser[]	[]	Users currently typing, shown as a typing indicator
`className`	string	—	Additional CSS classes for the scroll container
`onLoadMore`	() => void	—	Called when the user scrolls to the top to load older messages
`hasMore`	boolean	false	Whether there are more messages to load (shows a spinner when true)

ChatComposer

The message input area with auto-resize, file upload, and reply support.

Prop	Type	Default	Description
`onSend`	(text: string) => void	—	Called when the user sends a message
`onTyping`	(isTyping: boolean) => void	—	Called when the user's typing state changes
`onFileUpload`	(files: File[]) => void	—	Called when files are dropped or selected via the attachment button
`placeholder`	string	"Type a message..."	Placeholder text shown in the empty textarea
`disabled`	boolean	false	Disables the composer input and send button
`replyingTo`	ChatMessageData \| null	null	Message being replied to, shown as a preview above the input
`onCancelReply`	() => void	—	Called when the user dismisses the reply preview

ChatMessageData

The core data type representing a single message. Used throughout the library.

interface ChatMessageData {
  id: string
  senderId: string
  senderName: string
  senderAvatar?: string
  timestamp: Date | number
  text?: string
  status: "sending" | "sent" | "delivered" | "read" | "failed"
  replyTo?: {
    id: string
    senderName: string
    text: string
  }
  reactions?: {
    emoji: string
    userIds: string[]
    count: number
  }[]
  attachments?: {
    id: string
    type: "image" | "file" | "audio" | "video"
    url: string
    name: string
    size?: number
    mimeType?: string
  }[]
  images?: { url: string; alt?: string }[]
  files?: { url: string; name: string; size?: number }[]
  voice?: { url: string; duration: number }
  linkPreview?: { url: string; title?: string; image?: string }
  code?: { language: string; content: string }
  readBy?: { userId: string; name: string; avatar?: string }[]
  systemEvent?: { type: string; data?: Record<string, unknown> }
  isEdited?: boolean
  isDeleted?: boolean
  isSystem?: boolean
  isPinned?: boolean
}

ChatTheme

The union type for built-in theme names. Pass one of these to ChatProvider's theme prop, or cast a custom string for your own theme.

type ChatTheme = "lunar" | "aurora" | "ember" | "midnight"

← Theming Messages →