Theming

You can customize the look and feel of all UI components provided by StreamChatSwiftUI. The SDK allows you to change the appearance of components such as colors, fonts, and images via the Appearance configuration. Changes to appearance should be done when initializing the StreamChat object, typically in your AppDelegate or at the start of your app lifecycle.

Brand Color

The shortest one-line tweak is to override the accent color in the ColorPalette configuration. UI elements respect this accent color as the main brand color throughout the chat interface — useful when you only need to retint interactive elements.

For example, by customizing the accent color in the Appearance configuration when creating the StreamChat object, you can easily modify the brand color of the whole chat UI:

let apiKeyString = "your_api_key_string"
let config = ChatClientConfig(apiKey: .init(apiKeyString))
let client = ChatClient(config: config)

let newTintColor = UIColor.systemPink
let colors = Appearance.ColorPalette()
colors.accentPrimary = newTintColor
colors.navigationBarTintColor = newTintColor

let appearance = Appearance()
appearance.colorPalette = colors

let streamChat = StreamChat(chatClient: client, appearance: appearance)

Before	After

For systematic theming across the whole SDK, override the brand and chrome ramps on ColorPalette instead — see Brand Ramp and Chrome Ramp below.

Colors and Fonts

The colors and fonts are part of the Appearance configuration type. Since all components have access to this configuration through dependency injection, all components will be impacted by the changes on this configuration.

For example, let's change the color of outgoing message bubbles and the body font. We can do this by modifying the values in the Appearance object when initializing StreamChat:

let colors = Appearance.ColorPalette()
colors.chatBackgroundOutgoing = UIColor(red: 0.98, green: 0.95, blue: 0.75, alpha: 1.0)

let fonts = Appearance.FontsSwiftUI()
fonts.body = .system(size: 20).italic()

let appearance = Appearance()
appearance.colorPalette = colors
appearance.fontsSwiftUI = fonts
let streamChat = StreamChat(chatClient: client, appearance: appearance)

Before	After

You can see the font and the background color of the message has changed. Also note, that the font in the composer text view is also changed, since it uses the same semantic font as the body of the message.

The example above changes a single semantic token. For changes that should propagate to every component derived from your brand or neutral palette, override the brand or chrome ramp instead — see Brand Ramp / Chrome Ramp below.

You can find the full reference of the SwiftUI font configuration in FontsSwiftUI and the color definitions in ColorPalette.

Color Tokens

Important: Start by adjusting the brand and chrome ramps — most semantic tokens derive from them, so a small number of overrides reskins the whole SDK. Reach for individual semantic tokens only when a specific surface needs to deviate from what the ramps produce.

Brand Ramp

The brand accent color ramp. Most accent and on-brand surfaces derive from these stops.

Chrome Ramp

The neutral gray ramp. Most surface, text, and border tokens derive from these stops.

Accent

Background — Elevation

The elevation scale establishes a vertical hierarchy. Higher numbers sit visually closer to the user. In dark mode, values step progressively lighter as depth increases. In light mode, all levels are white.

Background — Surface

Background — Utility

Text

Border

Avatar

Badge

Button

Chat

Control

Input

Presence

Reaction

Navigation

Image Assets

The image assets and icons used by buttons also use the Appearance configuration type. For example, let's modify the icon used for the "Send" button:

let images = Appearance.Images()
images.composerSend = UIImage(systemName: "arrowshape.turn.up.right")!

let appearance = Appearance()
appearance.images = images
let streamChat = StreamChat(chatClient: client, appearance: appearance)

Before	After

If the same image is used in multiple places, changing the image in the Appearance object will update it in all places.

The full reference of the Images object can be found here.

Data Formatting

Besides customizing the UI appearance, you can also customize the data formatting of the components. For example, you can change how the channel name is displayed or how the timestamp of messages are formatted. For this, you should use the Utils object, which is part of the StreamChat object.

Below is an example of how to change the channel name and message timestamp formatting.

final class CustomChannelNameFormatter: ChannelNameFormatter {
    func format(channel: ChatChannel, forCurrentUserId currentUserId: UserId?) -> String? {
        if let name = channel.name {
            return name
        }
        return channel.lastActiveMembers
            .map { $0.name ?? $0.id }
            .joined(separator: ", ")
    }
}

let customMessageDateFormatter: DateFormatter = {
    let formatter = DateFormatter()
    formatter.dateStyle = .short
    formatter.timeStyle = .short
    return formatter
}()
let utils = Utils(
    dateFormatter: customMessageDateFormatter,
    channelNameFormatter: CustomChannelNameFormatter()
)
let streamChat = StreamChat(
    chatClient: client,
    utils: utils
)