Chat UI for Compose Multiplatform — ready to use, easy to make your own.
Android · iOS · Desktop JVM
Get started · Customize · Guides · Sample
Your content. Your style. Custom messages and themes in the same conversation.
The Scout sample, running with local messages and bundled images.
Add a message timeline and composer to your app without building every bubble, delivery indicator and scroll interaction yourself. Start with the Material 3 components, then adapt the colors, message content and controls to your product.
Your app supplies the messages and handles user events. Connect your own API, database or AI service through ordinary Kotlin callbacks.
- A ready-made chat screen. Grouped messages, sender details, send status, retry controls and a growing composer.
- Reading that stays in place. Load earlier messages without losing your position; jump back to the latest when you’re ready.
- Room for your product. Replace individual slots to show a booking, recommendation or another custom message.
- Images and actions when you need them. Add attachment presentation or copy, quote, edit and delete flows as separate modules.
- One shared UI. Compose targets for Android, arm64 iOS and desktop JVM.
Add the Material 3 module to your shared module’s commonMain dependencies. Use mavenCentral() in your dependency repositories.
# gradle/libs.versions.toml
[versions]
chat = "0.0.1"
[libraries]
chat-material3 = { module = "dev.forntoh.chat:chat-material3", version.ref = "chat" }// Your shared module's build.gradle.kts
kotlin {
sourceSets.commonMain.dependencies {
implementation(libs.chat.material3)
}
}chat-material3 includes chat-ui and chat-core. Your shared module also needs its normal Compose and Material 3 dependencies for the composables it uses directly. Chat 0.0.1 uses Kotlin 2.4.0, Compose Multiplatform 1.11.1 and Material 3 1.11.0-alpha07.
Keep your app’s users, messages, repository and ViewModel. Chat supplies the conversation UI; its Participant and Message types are presentation values you map to at the screen boundary. Your domain models do not need to implement a library interface or change their database schema.
For example, suppose your app already has models with these fields. These declarations only describe the example’s existing app types; use your own equivalents:
// Existing application models, independent of Chat.
data class User(val id: String, val name: String)
enum class SendStatus { Pending, Delivered, Failed }
data class ChatMessage(
val id: String,
val author: User,
val sentAtMillis: Long,
val body: String,
val status: SendStatus,
)Map those models to UI values. Preserve the original IDs so outgoing alignment, retry and custom-content lookups refer to the same users and messages your app already knows:
import dev.forntoh.chat.core.Delivery
import dev.forntoh.chat.core.Message as UiMessage
import dev.forntoh.chat.core.Participant
fun User.toChatParticipant(): Participant = Participant(id = id, displayName = name)
fun ChatMessage.toChatMessage(formatTime: (Long) -> String): UiMessage = UiMessage(
id = id,
sender = author.toChatParticipant(),
timestampEpochMillis = sentAtMillis,
displayTime = formatTime(sentAtMillis),
text = body,
delivery = when (status) {
SendStatus.Pending -> Delivery.Sending
SendStatus.Delivered -> Delivery.Sent
SendStatus.Failed -> Delivery.Failed
},
)Then render the messages your app already observes. This screen receives the current user and conversation from your state holder, plus a retained UI draft and an event handler:
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import dev.forntoh.chat.core.ConversationEvent
import dev.forntoh.chat.core.ConversationState
import dev.forntoh.chat.core.Draft
import dev.forntoh.chat.material3.ChatScaffold
import dev.forntoh.chat.material3.ChatTheme
import dev.forntoh.chat.ui.Conversation
@Composable
fun AppChatScreen(
conversationId: String,
title: String,
currentUser: User,
messages: List<ChatMessage>,
draft: Draft,
formatTime: (Long) -> String,
onEvent: (ConversationEvent) -> Unit,
) {
val state = ConversationState(
conversationId = conversationId,
currentParticipantId = currentUser.id,
messages = messages.map { it.toChatMessage(formatTime) },
draft = draft,
)
ChatTheme {
ChatScaffold(title = { Text(title) }) {
Conversation(state = state, onEvent = onEvent)
}
}
}Call AppChatScreen with the user and messages from your existing ViewModel or state holder. Pass your app’s localized time formatter and handle onEvent there. When your repository emits updated messages, publish a new list; the screen maps it to a new UI snapshot. No separate in-memory message store is needed.
Draft is UI state for composing and acknowledging submissions; retain it in your state holder and update it in response to events. If you already have a draft model, map its text and attachments too, retaining the Chat revision and submission state alongside it. For image messages, map your existing media records to Attachment descriptors; keep file loading and uploads in your app. See Images.
Handle UI events in your existing state holder and translate them into your app’s commands. Continue to observe messages from your repository; do not write the mapped UI rows back as database entities.
| Event or update | What your application does |
|---|---|
DraftChanged |
Replace the retained UI draft’s text (or update your existing draft model), preserving the other fields. |
SendDraft |
Validate the conversation, draft revision, text and attachments against current state. Accept or refuse that exact submission. |
| Accepted send | Call your existing send command with the accepted text/attachments. Let your app create one stable domain message ID with pending status; the mapper presents it as Delivery.Sending. Clear the accepted draft and increment its revision. |
| Refused send | Retain the draft content and increment its revision to unlock the composer. |
| Service result | Update your existing domain message status; the mapper produces Sent or Failed for the same ID. Recheck conversation and request identity before applying asynchronous results. |
RetryMessage |
Resolve event.messageId in your app’s messages and invoke your existing retry command for that outgoing failed message, keeping its ID. |
Supply immutable snapshots with unique message IDs in display order, oldest first. Your host owns deduplication, persistence, cancellation and permissions; enforce access in your backend as well. Draft.submitting represents unresolved acceptance, independently of message delivery. See Integration for the full state contract.
Change the palette, replace one control, or render a completely different message. All of these use the same conversation state and callbacks.
Wrap your screen in ChatTheme. It accepts an ordinary Material 3 color scheme and typography:
import androidx.compose.material3.Text
import androidx.compose.material3.Typography
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color
import dev.forntoh.chat.core.ConversationEvent
import dev.forntoh.chat.core.ConversationState
import dev.forntoh.chat.material3.ChatScaffold
import dev.forntoh.chat.material3.ChatTheme
import dev.forntoh.chat.material3.chatColorScheme
import dev.forntoh.chat.ui.Conversation
@Composable
fun BrandedChat(state: ConversationState, onEvent: (ConversationEvent) -> Unit) {
ChatTheme(
colorScheme = chatColorScheme().copy(
primary = Color(0xFF356859),
onPrimary = Color.White,
primaryContainer = Color(0xFFD6EDDF),
onPrimaryContainer = Color(0xFF153C2F),
),
typography = Typography(),
) {
ChatScaffold(title = { Text("Weekend plans") }) {
Conversation(state = state, onEvent = onEvent)
}
}
}Use chatColorScheme(darkTheme = true) for the dark palette, or pass your existing design system’s colors and typography. Keep the conversation mounted when changing themes so its draft and reading position survive.
The sample’s Forest palette demonstrates theme customization; it also customizes the header and message content.
Use messageBody to put a recommendation, booking or product card inside the existing bubble. Keep domain data in your app, keyed by the same message ID preserved by toChatMessage. Copy the current slots to retain defaults for ordinary messages:
import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import dev.forntoh.chat.core.ConversationEvent
import dev.forntoh.chat.core.ConversationState
import dev.forntoh.chat.ui.Conversation
import dev.forntoh.chat.ui.LocalConversationSlots
@Composable
fun RecommendationsChat(
state: ConversationState,
onEvent: (ConversationEvent) -> Unit,
recommendations: Map<String, String>,
) {
val defaults = LocalConversationSlots.current
val slots = defaults.copy(
messageBody = { message ->
val recommendation = recommendations[message.id]
if (recommendation == null) {
defaults.messageBody(message)
} else {
Column {
Text("RECOMMENDED FOR YOU")
Text(recommendation)
}
}
},
)
Conversation(state = state, onEvent = onEvent, slots = slots)
}Call RecommendationsChat inside ChatTheme and ChatScaffold, in place of the plain Conversation call. Populate recommendations with IDs from state.messages. The bubble, sender/time and delivery presentation stay in place.
Scout uses this same slot for a richer trail card. See the complete TrailCard and message-body wiring. The smaller example above renders a heading and recommendation text.
If the visible content differs from Message.text, also supply messageDescription with an accurate accessible summary, including sender, content, time and delivery. Give interactive controls their own labels.
This changes Send into a labeled Material button, retaining the field, draft and guarded submission callback:
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import dev.forntoh.chat.core.ConversationEvent
import dev.forntoh.chat.core.ConversationState
import dev.forntoh.chat.ui.Conversation
import dev.forntoh.chat.ui.LocalConversationSlots
@Composable
fun CustomSendChat(state: ConversationState, onEvent: (ConversationEvent) -> Unit) {
val defaults = LocalConversationSlots.current
Conversation(
state = state,
onEvent = onEvent,
slots = defaults.copy(
composerSend = { content ->
Button(onClick = content.onSend, enabled = content.canSend) {
Text(if (content.pending) "Sending…" else "Send message")
}
},
),
)
}Call this inside ChatTheme and your screen shell. To replace the entire input area, use the composer slot or composerContent argument. Render the supplied ComposerContent.draft, forward onTextChange and onSend, and respect pending and canSend. Use onDraftAction for attachment mutations. Custom fields should honor focusRequest in an effect when nonzero. Keep one shared draft throughout.
Read LocalConversationSlots.current inside ChatTheme, then pass defaults.copy(...) to Conversation(slots = ...). You can also set defaults across screens with ChatTheme(slots = chatConversationSlots().copy(...)), or use ConversationTheme with your own design system and chat-ui.
| Slot | What you can change |
|---|---|
messageBody |
Content inside the bubble: text, cards, rich domain content. |
messageMetadata |
Sender and time presentation. |
messageDelivery |
Sending, sent and failed indicators. |
messageAvatar |
Per-message avatar presentation; your app loads the image. |
messageSpacing |
Spacing based on the message’s group context. |
messageDescription |
Accessible summary of a message. |
retry |
The failed-message Retry control, using its supplied callback. |
message |
The whole message row; receives the message, outgoing flag and optional retry callback. |
presentedMessage |
A whole row with transient highlight/navigation context. Overrides message when set. |
composerField |
The editable field, using the shared composer content. |
composerSend |
Send control and pending presentation. |
composer |
The complete composer layout. |
history |
Earlier-history area, including empty-state context. |
historyFeedback |
Feedback inside the default history area: load, loading, error or exhausted. |
latest |
The return-to-latest control and its activation. |
latestLabel |
Just the label inside the default Latest control. |
A replacement controls its own rendering: if you replace a whole row or composer, call the smaller slots you still want to use. Forward supplied guarded callbacks on user activation, and provide appropriate focus and accessibility semantics.
Explicit Conversation renderer arguments (messageContent, composerContent, historyContent, latestContent) take precedence over the corresponding bundle slots; an explicit bundle takes precedence over theme defaults. historyContent receives HistoryContent, while the history slot receives HistoryFeedbackContent with empty-state context. See ConversationSlots for all callback types.
ChatScaffold accepts title, avatar, navigationIcon and actions for its default header. Replace the whole header with topBar, and add bottomBar, snackbarHost or floatingActionButton as needed. These are ordinary composable lambdas; wire them to your own navigation and screen state.
You can also use your own shell: give Conversation a bounded height, such as Modifier.weight(1f) in a full-height column, and handle window insets. The sample screen demonstrates a subtitle, avatar and overflow menu alongside a custom composer and message body.
Start with Material 3, or select the foundation layer for your own design system. All modules use version 0.0.1.
| Module | What it supplies |
|---|---|
chat-core |
Messages, participants, drafts, attachments and events without Compose UI. |
chat-ui |
Conversation behavior, scrolling, history and replaceable foundation renderers. Includes core. |
chat-material3 |
Material 3 theme, bubbles, composer and scaffold. Includes UI and core. |
chat-media |
Optional attachment presentation, upload status and media intents. Depends on UI. |
chat-actions |
Optional copy, quote, edit and delete presentation and intents. Depends on UI. |
Add the optional modules to the same version catalog and commonMain dependencies:
[libraries]
chat-media = { module = "dev.forntoh.chat:chat-media", version.ref = "chat" }
chat-actions = { module = "dev.forntoh.chat:chat-actions", version.ref = "chat" }implementation(libs.chat.media)
implementation(libs.chat.actions)Your app supplies the picker, image renderer, upload and viewer. The module supplies the shared UI and user intents:
- Retain a
MediaStatebeside your conversation state. Put attachment descriptors inDraft.attachmentsandMessage.attachments. - Obtain the adapter with
rememberMedia(conversation, mediaState, onRequest, onEvent); pass itsonConversationEventtoConversation. - Render
MediaAttachments(media, message, renderer)alongside the text row, outside its merged message semantics. The renderer receives aMediaTarget; resolve its attachment’s opaquecontentReferencewith your image loader. - Render
MediaDraft(media, content, renderer)above the field. Passmedia.composer(content)to your composer renderer so selection locks apply to both field and Send. - Handle
MediaRequestcommandsSelect,Remove,RetryandViewin your host. Advance the media revision after resolution, including cancellation or denial; selection/removal also require a new draft revision. Recheck exact targets and permissions before applying asynchronous results.
Both user and bot images use the same timeline. The sample supplies a local chooser and bundled image renderer.
Copy the complete sample wiring, then replace its chooser and renderer with your adapters. The media guide explains loading, progress, failure and resource identity.
Retain ActionState with capabilities keyed by message ID. Create the adapter with rememberMessageActions(conversation, actionState, onAction, onEvent) and route events through its onConversationEvent. Render MessageActions(adapter, message.id) alongside each row and ActionComposerStatus(adapter) above the input. Pass adapter.composer(content) to the composer renderer.
The host handles clipboard access, quoted sends, edits and confirmed deletion, rechecking permissions and request revisions. Advance action revisions after each transition and draft revisions after resolving submissions or restoring drafts. When combining media and actions, chain their event adapters and preserve the same draft and its attachments. See Message actions.
The optional modules have their own replaceable slots, independent of Material 3:
| Bundle | Slots |
|---|---|
MediaSlots via MediaTheme |
control for buttons; feedback for image status; description for accessible image text; selectionError for picker errors. |
ActionSlots via ActionTheme |
control, status, quote, plus menu, composerStatus and confirmation containers. Containers render their supplied child content once. |
Derive copies from LocalMediaSlots.current or LocalActionSlots.current to retain other defaults; explicit component slots take precedence over module themes. MediaTheme also accepts a text style, and ActionTheme accepts ActionStyle for typography, backgrounds, shapes and spacing. Custom controls honor their supplied enabled state and guarded activation callback.
History is off by default. Supply a retained HistoryState and handler to enable it:
import androidx.compose.runtime.Composable
import dev.forntoh.chat.core.ConversationEvent
import dev.forntoh.chat.core.ConversationState
import dev.forntoh.chat.ui.Conversation
import dev.forntoh.chat.ui.HistoryRequest
import dev.forntoh.chat.ui.HistoryState
@Composable
fun PagedChat(
state: ConversationState,
onEvent: (ConversationEvent) -> Unit,
history: HistoryState,
onLoadEarlier: (HistoryRequest) -> Unit,
) {
Conversation(
state = state,
onEvent = onEvent,
history = history,
onLoadEarlier = onLoadEarlier,
)
}Start with HistoryStatus.Idle when an earlier page exists. Publish Loading before requesting it; merge overlapping IDs in your host, prepend the results and increment the history revision. Publish Idle if more pages exist, Exhausted at the end, or Error on failure. Retry follows explicit user activation.
Prepending retains the visible message and offset. New messages follow a reader already at the bottom; someone reading earlier messages gets a Latest control. Send and Latest return to following. For initial hydration and empty-page handling, see Earlier history.
From this repository, with JDK 21 and Android SDK 37 configured:
./gradlew :sample:runMeet Scout: send a message, attach the bundled mountain illustration, or switch to Forest from the overflow menu. The bot shares a short burst of text, images and trail ideas, then waits. No service credentials are needed.
Sample setup for desktop, Android and iOS →
| I want to… | Read |
|---|---|
| Get a working screen | Getting started |
| Connect my data and choose dependencies | Integration |
| Change the theme or render custom messages | Customization |
| Add images, message actions or earlier history | Features |
| Run the project or contribute | Sample · Contributing |
Apache 2.0. See third-party notices for the icons used by the Material 3 components.



