Skip to main content

Theming and dark mode

Token groups, runtime switching and themed components

The look starts from an appearance, a complete light and dark theme picked with the appearance prop:

appearanceDayNight
'plain' (default)Neutral #F4F5F7 background, white incoming bubbles, solid blue outgoing with white textNear-black background, dark grey incoming, the same blue outgoing
'wallpaper'Green swirl wallpaper, pale green outgoing bubbles with tailsDark blue, a purple-to-blue outgoing gradient fixed to the screen
'mono'White, light grey incoming, black outgoing, grey avatars, 12pt cornersBlack, the bubbles reversed
'soft'Faint violet background, lavender outgoing bubbles with dark text, 20pt cornersDeep plum

Every value is a token. Override any subset via theme (light) and darkTheme (dark); your overrides are deep-merged over the appearance, and the resolved theme switches at runtime with the color scheme (system, or forced via colorScheme). Explicit per-component style props still win over the theme. For a look of your own, pass appearance={{ light, dark }}, for example { light: mergeTheme(chatAppearances.mono.light, {...}), dark: ... }. Pass the same appearance to ChatList and ChatHeader so the whole app matches.

<Chat
appearance='wallpaper'
theme={{
colors: { accent: '#3390EC', outgoingBubble: '#3390EC', outgoingText: '#FFFFFF' },
radii: { bubble: 18 },
wallpaper: { colors: ['#7FA381', '#FFF5C5', '#336F55', '#FBE37D'] },
}}
darkTheme={{ bubble: { outgoingGradient: ['#5B3FA8', '#2F6FD6'] } }}
// colorScheme="dark" // optional: force a scheme instead of following the system
{...props}
/>

Token groups: colors, radii, spacing, typography, avatar, sendButton, composer, voice, plus:

  • bubble - hasTail (a curled tail on the last bubble of a run; drawn with react-native-svg when installed), isTimeInline (the time on the last line of text when it fits; false gives it a row), outgoingGradient (stops, top to bottom, or null for the solid colors.outgoingBubble), outgoingGradientMode ('screen': one gradient across the list, each bubble shows its slice as it scrolls; 'bubble': each bubble carries the whole gradient), maxWidthInset (the text column is min(width, height) - maxWidthInset, 80 by default), bigEmojiMaxCount (a message of up to this many emoji and nothing else drops its bubble and draws them large, with the time in a service pill; 20 by default, 0 turns it off), bigEmojiSizes (font size by emoji count, 40.8, 40.8, 33.6, 26.4, 22.8).
  • wallpaper - isEnabled, colors (three or four, for the swirl gradient), isAnimated (one step per outgoing message), pattern (an image tiled over the gradient; no pattern is bundled), patternOpacity, patternColor. Off, the chat shows colors.background. Replace it entirely with the renderWallpaper prop, or draw it elsewhere with the exported ChatWallpaper component.
  • nameColors - the seven sender-name colors, picked per user id. Empty uses colors.senderName.
  • avatar.palette / avatar.paletteEnd - initials avatar gradient stops, picked per user id. An empty paletteEnd draws flat colors.
  • textScale - the text size the user picked, a multiplier of every typography size (1 by default): messages, times, names, day and service pills, quotes and the composer grow together, e.g. theme={{ textScale: 1.2 }}.
  • chatList.headerSubtitle / chatList.headerSubtitleActive - ChatHeader's status line, grey and in the accent color.

A few behaviours follow from the tokens: setting colors.outgoingBubble turns the gradient off, setting colors.senderName empties nameColors, and setting avatar.palette without paletteEnd draws flat avatars - so an app that picks its own colors keeps seeing them. Bubbles in a run (same sender, at most five minutes apart, utils.isSameGroup) share one tail and one name, 2pt apart (spacing.withinGroup), with 6pt between runs (spacing.betweenGroups).

Build your own theme-aware components with the exported hooks:

import { useTheme, useThemedStyles } from '@kesha-antonov/react-native-chat'
import { StyleSheet } from 'react-native'

const MyBadge = () => {
const theme = useTheme()
const styles = useThemedStyles(t => StyleSheet.create({
badge: { backgroundColor: t.colors.accent, borderRadius: t.radii.bubble },
}))
return <View style={styles.badge} />
}

Also exported: chatAppearances (every built-in appearance), defaultLightTheme / defaultDarkTheme (the 'plain' pair), mergeTheme, ChatWallpaper, and the ChatTheme / PartialChatTheme / ChatAppearance / ChatAppearanceName types.

The built-in panels have their own token groups: emojiKeyboard, contextMenu, attachments and chatList. The full set of tokens is the ChatTheme type; every appearance's values are in chatAppearances. colors.onAccent colors the icons and text on an accent fill (the send button, badges, checks); a link whose color matches its text is underlined.