Migrating from 4.x to 5.x

Version 5.x of the SwiftUI SDK keeps the overall architecture from 4.x, but it includes several source-breaking API updates in the customization layer. Most migrations are straightforward and fall into these buckets:

• Appearance customization now goes through mutable properties instead of initializer parameters.
• Several SwiftUI-specific helper views were renamed.
• ViewFactory methods now take a single options object instead of many individual parameters.
• Several modifier methods moved from ViewFactory to the new Styles protocol.
• Utils gained new formatter parameters and dropped a few deprecated ones.
• supportedMoreChannelActions, supportedMessageActions, and navigationBarDisplayMode moved to config objects.

If your app mostly uses the default UI components, the upgrade should be limited to dependency updates and a small number of customization fixes.

Please don't hesitate to contact our Support team or open a ticket in our GitHub repository. We'll help you during your migration process and any issues you might face.

Update the SDK Version

First, update your Swift Package Manager dependency to version 5.x.

Appearance no longer uses parameterized initializers

In v4, many docs and examples initialized Appearance with parameters such as colors, fonts, or images.

In v5, Appearance has a public empty initializer and you customize it by mutating its properties:

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

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

let images = Appearance.Images()

let appearance = Appearance()
appearance.colorPalette = colors
appearance.fontsSwiftUI = fonts
appearance.images = images

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

Replace usages like these:

let appearance = Appearance(colors: colors)
let appearance = Appearance(colors: colors, fonts: fonts, images: images)

with property-based configuration on a mutable Appearance value.

Use Appearance.FontsSwiftUI for SwiftUI font customization

Appearance now exposes both UIKit fonts and SwiftUI fonts:

• appearance.fonts for UIKit font values
• appearance.fontsSwiftUI for SwiftUI font values

If you are customizing SwiftUI screens, use Appearance.FontsSwiftUI:

let fonts = Appearance.FontsSwiftUI()
fonts.footnoteBold = .footnote

let appearance = Appearance()
appearance.fontsSwiftUI = fonts

If you were previously using Fonts() in SwiftUI snippets, switch those usages to Appearance.FontsSwiftUI().

Replace tintColor customizations with ColorPalette

The SwiftUI SDK reads brand and navigation colors from Appearance.colorPalette.

The most common v4 migration is replacing generic tint configuration with explicit palette values:

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

let appearance = Appearance()
appearance.colorPalette = colors

In custom SwiftUI views, when you need the configured brand color, prefer the palette values:

@Injected(\.colors) private var colors

Text("Create")
    .foregroundColor(Color(colors.accentPrimary))

Migrate removed ColorPalette tokens

The v5 color palette removed many broad aliases from v4 and now prefers semantic tokens such as textPrimary, backgroundCoreApp, chatBackgroundIncoming, and borderCoreDefault.

The table below lists suggested replacements. Some old tokens do not have a 1:1 replacement because the new palette uses more specific tokens for text, surfaces, chat bubbles, reactions, controls, and overlays.

Important: Before mapping every removed token individually, start by adjusting the brand and chrome ramps on Appearance.ColorPalette — most semantic tokens derive from them, so a small number of overrides reskins the whole SDK. Reach for the individual replacements below only when a specific surface needs to deviate from what the ramps produce.

Gradient message bubbles

In v4, SwiftUI message bubble colors were arrays, so you could create gradients directly on ColorPalette:

colors.messageCurrentUserBackground = [purple, pink]
colors.messageCurrentUserEmphemeralBackground = [
    purple.withAlphaComponent(0.85),
    pink.withAlphaComponent(0.85)
]
colors.messageOtherUserBackground = [card]

In v5, the main chat background tokens such as chatBackgroundOutgoing and chatBackgroundIncoming are single UIColor values. Migrating the code above directly to colors.chatBackgroundOutgoing = purple keeps the app compiling, but it also changes the outgoing bubble from a gradient to a solid color.

Single-color bubbles can keep using the default MessageBubbleModifier. For gradient bubbles, move the customization to Styles.makeMessageViewModifier(for:) and use the lower-level BubbleModifier, which accepts backgroundColors: [Color] and renders a LinearGradient when more than one color is provided:

RegularStyles is public class (not open), so you cannot subclass it from your own module. Conform to Styles directly and provide the three required methods that have no protocol-extension default (makeComposerInputViewModifier, makeComposerButtonViewModifier, makeSuggestionsContainerModifier) using the public Regular* modifier types:

final class CustomStyles: Styles {
    var composerPlacement: ComposerPlacement = .docked

    func makeMessageViewModifier(for info: MessageModifierInfo) -> some ViewModifier {
        GradientMessageBubbleModifier(info: info)
    }

    func makeComposerInputViewModifier(options: ComposerInputModifierOptions) -> some ViewModifier {
        RegularInputViewModifier()
    }

    func makeComposerButtonViewModifier(options: ComposerButtonModifierOptions) -> some ViewModifier {
        RegularButtonViewModifier()
    }

    func makeSuggestionsContainerModifier(options: SuggestionsContainerModifierOptions) -> some ViewModifier {
        SuggestionsRegularContainerModifier()
    }
}

private struct GradientMessageBubbleModifier: ViewModifier {
    @Environment(\.layoutDirection) private var layoutDirection

    let info: MessageModifierInfo

    func body(content: Content) -> some View {
        let backgroundColors = info.injectedBackgroundColor.map { [Color($0)] } ?? [.purple, .pink]

        content.modifier(
            BubbleModifier(
                corners: info.message.bubbleCorners(
                    isFirst: info.isFirst,
                    forceLeftToRight: info.forceLeftToRight,
                    layoutDirection: layoutDirection
                ),
                backgroundColors: backgroundColors,
                cornerRadius: info.cornerRadius ?? 18
            )
        )
    }
}

DefaultViewFactory.shared.styles = CustomStyles()

channelNamer became channelNameFormatter

Channel name customization changed in v5.

Replace:

let channelNamer: ChatChannelNamer = { channel, currentUserId in
    "This is our custom name: \(channel.name ?? "no name")"
}

let utils = Utils(channelNamer: channelNamer)

with:

final class CustomChannelNameFormatter: ChannelNameFormatter {
    func format(channel: ChatChannel, forCurrentUserId currentUserId: UserId?) -> String? {
        "This is our custom name: \(channel.name ?? "no name")"
    }
}

let utils = Utils(channelNameFormatter: CustomChannelNameFormatter())

If you were using DefaultChatChannelNamer, migrate to DefaultChannelNameFormatter.

Update renamed reusable SwiftUI views

If you built custom UI with the SDK's reusable views, update the renamed view types:

• MessageAvatarView -> UserAvatar
• ChannelAvatarView -> ChannelAvatar
• TypingIndicatorBottomView -> TypingIndicatorView

For example, this v4 code:

MessageAvatarView(
    url: user.imageURL,
    size: 40
)

becomes:

UserAvatar(
    user: user,
    size: 40
)

Note that UserAvatar takes a ChatUser value directly rather than a URL, and size is now a CGFloat instead of CGSize. If you only have a URL (for example in a quoted message context), use the URL-and-initials initializer:

UserAvatar(
    url: url,
    initials: initials,
    size: 40,
    indicator: .none
)

The showOnlineIndicator: Bool parameter was replaced by an AvatarIndicator enum: .online, .offline, or .none.

And this:

TypingIndicatorBottomView(
    users: users,
    typingIndicatorString: typingText
)

becomes:

TypingIndicatorView(
    users: users,
    typingText: typingText
)

MessageDisplayOptions avatar parameters split

In v4, MessageDisplayOptions had a single showAvatars: Bool parameter that controlled both incoming and outgoing message avatars. In v5, this is split into two parameters with different defaults:

Replace:

let displayOptions = MessageDisplayOptions(
    showAvatars: false,
    showAvatarsInGroups: false
)

with:

let displayOptions = MessageDisplayOptions(
    showIncomingMessageAvatar: false,
    showOutgoingMessageAvatar: false,
    showAvatarsInGroups: false
)

The default behavior also changed — v5 shows incoming avatars and hides outgoing avatars unless you specify otherwise. If you previously relied on MessageDisplayOptions() defaults, your outgoing-message avatar visibility flips.

Utils API changes

Several parameters were added, removed, or renamed on the Utils initializer. The Utils class itself is now marked @MainActor.

Removed parameters:

Renamed parameter:

New parameters in v5:

CDN and Media Loading

v5 replaces several image/video loading and CDN types with a unified architecture. If you customized any of these in v4, update to the new types.

Image and Video Loading

The separate imageLoader and videoLoader on Utils are replaced by a single mediaLoader:

// v4
let utils = Utils(
    imageLoader: CustomImageLoader(),
    videoLoader: CustomVideoLoader()
)

// v5
let utils = Utils(
    mediaLoader: CustomMediaLoader()
)

The underlying protocols changed as follows:

CDN Customization

CDN URL handling was split into two distinct concerns: storage (uploads/deletes) and requesting (signed URLs, auth headers, resizing).

Configure CDNStorage on ChatClientConfig:

var config = ChatClientConfig(apiKeyString: apiKeyString)
config.cdnStorage = CustomStorage()

Configure CDNRequester through StreamMediaLoader:

// UIKit
Components.default.mediaLoader = StreamMediaLoader(downloader: StreamImageDownloader(), cdnRequester: CustomCDNRequester())

// SwiftUI
let loader = StreamMediaLoader(downloader: StreamImageDownloader(), cdnRequester: CustomCDNRequester())
let utils = Utils(mediaLoader: loader)

navigationBarDisplayMode, supportedMoreChannelActions, and supportedMessageActions moved to config objects

In v4 these were methods on the ViewFactory protocol. In v5 they are properties on the relevant config objects.

DefaultViewFactory still exposes a compatibility navigationBarDisplayMode() helper on the v5 branch, but the channel list and message list read ChannelListConfig.navigationBarDisplayMode and MessageListConfig.navigationBarDisplayMode. For migrations, move your customization to the config objects.

navigationBarDisplayMode — remove the ViewFactory override and set the property on ChannelListConfig or MessageListConfig instead:

// v4 – ViewFactory override
func navigationBarDisplayMode() -> NavigationBarItem.TitleDisplayMode { .inline }

// v5 – config property
var channelListConfig = ChannelListConfig()
channelListConfig.navigationBarDisplayMode = .inline

var messageListConfig = MessageListConfig()
messageListConfig.navigationBarDisplayMode = .inline

let utils = Utils(channelListConfig: channelListConfig, messageListConfig: messageListConfig)

supportedMoreChannelActions — remove the ViewFactory override and supply a closure on ChannelListConfig:

// v4 – ViewFactory override
func supportedMoreChannelActions(
    for channel: ChatChannel,
    onDismiss: @escaping () -> Void,
    onError: @escaping (Error) -> Void
) -> [ChannelAction] { ... }

// v5 – ChannelListConfig closure
var channelListConfig = ChannelListConfig()
channelListConfig.supportedMoreChannelActions = { options in
    // options.channel, options.onDismiss, options.onError
    return [...]
}

supportedMessageActions — remove the ViewFactory override and supply a closure on MessageListConfig:

// v4 – ViewFactory override
func supportedMessageActions(
    for message: ChatMessage,
    channel: ChatChannel,
    onFinish: @escaping (MessageActionInfo) -> Void,
    onError: @escaping (Error) -> Void
) -> [MessageAction] { ... }

// v5 – MessageListConfig closure
var messageListConfig = MessageListConfig()
messageListConfig.supportedMessageActions = { options in
    // options.message, options.channel, options.onFinish, options.onError
    return [...]
}

New Styles protocol — modifier customization moved out of ViewFactory

v5 introduces a Styles protocol that owns all ViewModifier-returning customizations. Several methods that were on ViewFactory in v4 now live on Styles instead.

The SDK ships two concrete implementations:

• LiquidGlassStyles — uses the iOS 26 Liquid Glass material where available.
• RegularStyles — the classic appearance for earlier OS versions.

DefaultViewFactory uses RegularStyles by default. If you want the built-in Liquid Glass look, set styles = LiquidGlassStyles() on your custom factory.

RegularStyles and LiquidGlassStyles are both declared public class (not open), so you cannot subclass them from your own module. To customize modifier behavior, conform to Styles directly. The protocol provides default implementations for most methods, but three methods have no default and must be implemented: makeComposerInputViewModifier(options:), makeComposerButtonViewModifier(options:), and makeSuggestionsContainerModifier(options:). The public RegularInputViewModifier, RegularButtonViewModifier, and SuggestionsRegularContainerModifier types match the default appearance and can be reused:

final class MyStyles: Styles {
    var composerPlacement: ComposerPlacement = .docked

    func makeComposerViewModifier(options: ComposerViewModifierOptions) -> some ViewModifier {
        ComposerBackgroundRegularViewModifier()
    }

    func makeComposerInputViewModifier(options: ComposerInputModifierOptions) -> some ViewModifier {
        RegularInputViewModifier()
    }

    func makeComposerButtonViewModifier(options: ComposerButtonModifierOptions) -> some ViewModifier {
        RegularButtonViewModifier()
    }

    func makeSuggestionsContainerModifier(options: SuggestionsContainerModifierOptions) -> some ViewModifier {
        SuggestionsRegularContainerModifier()
    }
}

final class CustomFactory: ViewFactory {
    @Injected(\.chatClient) public var chatClient
    public var styles = MyStyles()

    private init() {}
    public static let shared = CustomFactory()
}

For channel list search, this change is behavioral as well as structural. In v5, search is applied through Styles.makeSearchableModifier(options:). makeChannelListTopView(options:) remains available, but it is now just a top content slot and no longer provides searchText or owns the search bar UI.

Methods moved from ViewFactory to Styles:

New Styles methods with no v4 equivalent:

• func makeComposerInputViewModifier(options: ComposerInputModifierOptions) -> ComposerInputViewModifier
• func makeComposerButtonViewModifier(options: ComposerButtonModifierOptions) -> ComposerButtonViewModifier
• func makeScrollToBottomButtonModifier(options: ScrollToBottomButtonModifierOptions) -> ScrollToBottomButtonViewModifier
• func makeBouncedMessageActionsModifier(viewModel: ChatChannelViewModel) -> BouncedMessageActionsModifierType
• func makeSuggestionsContainerModifier(options: SuggestionsContainerModifierOptions) -> SuggestionsContainerModifier
• func makeToolbarConfirmActionModifier(options: ToolbarConfirmActionModifierOptions) -> ToolbarConfirmActionViewModifier
• func makeSearchableModifier(options: SearchableModifierOptions) -> SearchableModifierType
• func makeMessageAttachmentsViewModifier(options: MessageAttachmentsViewModifierOptions) -> MessageAttachmentsViewModifier
• func makeMessageAttachmentItemViewModifier(options: MessageAttachmentItemViewModifierOptions) -> MessageAttachmentItemViewModifier

Translated text rendering changes (LinkDetectionTextView replacement)

Text rendering now goes through StreamTextView, replacing the earlier LinkDetectionTextView path.

For custom text rendering, use ChatMessage.attributedTextContent(layoutDirection:translationLanguage:) to build the attributed content shown in Text(...).

If you have custom text views or custom ViewFactory overrides, pass translationLanguage explicitly through options objects. These types now carry that value:

• StreamTextViewOptions(message:translationLanguage:)
• AttachmentTextViewOptions(message:availableWidth:translationLanguage:)
• MessageTextViewOptions(..., translationLanguage:)
• MessageAttachmentsViewOptions(..., translationLanguage:)

// v4
public func makeStreamTextView(options: StreamTextViewOptions) -> some View {
    StreamTextView(message: options.message)
}

// v5
public func makeStreamTextView(options: StreamTextViewOptions) -> some View {
    MyStreamTextView(
        message: options.message,
        translationLanguage: options.translationLanguage
    )
}

struct MyStreamTextView: View {
    @Environment(\.layoutDirection) private var layoutDirection

    let message: ChatMessage
    let translationLanguage: TranslationLanguage?

    var body: some View {
        Text(
            message.attributedTextContent(
                layoutDirection: layoutDirection,
                translationLanguage: translationLanguage
            )
        )
    }
}

Review your ViewFactory implementations

The biggest ViewFactory change in v5 is that the API moved from many ad-hoc parameters to option objects. If you had a custom factory in v4, you should review every override.

Below is the full mapping validated against the v4 and v5 of stream-chat-swiftui.

The safest migration path is to compile your custom UI against v5, then manually compare every custom override against ViewFactory, Styles, ChannelListConfig, and MessageListConfig.

Do not rely on compile failures alone. v5 still provides broad default implementations, so stale v4-shaped methods can compile while silently falling back to the default behavior. Pay special attention to old leading swipe action overrides, custom attachment picker and preview overrides, factory-level makeMessageViewModifier(for:), and old supportedMoreChannelActions(...) / supportedMessageActions(...) factory methods.

Migration Checklist

• Update your dependency to 5.x.
• Replace Appearance(...) initializers with let appearance = Appearance() and property assignment.
• Use Appearance.FontsSwiftUI() for SwiftUI font customization.
• Move tint customizations to ColorPalette, usually accentPrimary and navigationBarTintColor.
• Replace removed ColorPalette aliases with semantic v5 tokens such as textPrimary, backgroundCoreApp, chatBackgroundIncoming, and borderCoreDefault.
• Move SwiftUI gradient message bubble customizations from ColorPalette arrays to a custom Styles.makeMessageViewModifier(for:) implementation that uses BubbleModifier(backgroundColors:).
• Rename channelNamer to channelNameFormatter in your Utils initializer.
• Replace ChatChannelNamer closure type with a class conforming to ChannelNameFormatter.
• Replace DefaultChatChannelNamer with DefaultChannelNameFormatter.
• Remove imageMerger, channelAvatarsMerger, and channelHeaderLoader from your Utils initializer.
• Replace renamed reusable views: UserAvatar, ChannelAvatar, and TypingIndicatorView.
• Update UserAvatar call sites: pass a ChatUser (or use the URL+initials initializer), use CGFloat for size, and switch showOnlineIndicator: Bool to the AvatarIndicator enum.
• Replace MessageDisplayOptions(showAvatars:) with the new showIncomingMessageAvatar and showOutgoingMessageAvatar parameters; note that the new defaults differ (incoming true, outgoing false).
• Migrate message container customizations from makeMessageContainerView(...) to makeMessageItemView(options:).
• Migrate message translation/reply annotation customizations from makeMessageTranslationFooterView(...) and makeMessageRepliesShownInChannelView(...) to makeMessageTopView(options:) and makeMessageRepliesView(options:).
• For custom text rendering in the message list, replace removed LinkDetectionTextView usage with ChatMessage.attributedTextContent(layoutDirection:translationLanguage:) by optionally changing attributed string attributes or content through configs
• Migrate gallery, media, and video player customizations (makeGalleryView(...), makeGalleryHeaderView(...), makeVideoPlayerView(...), makeVideoPlayerHeaderView(...), makeVideoPlayerFooterView(...)) to makeMediaViewer(options:), makeMediaViewerToolbarModifier(options:), and makeMediaViewerFooterView(options:). The same MediaViewer now renders images and videos full-screen; there is no longer a separate video player factory.
• Migrate quoted-message content customization from makeQuotedMessageContentView(...) to makeQuotedMessageView(options:) and/or makeChatQuotedMessageView(options:).
• Move ViewFactory modifier overrides (makeChannelListContentModifier, makeChannelListModifier, makeMessageListModifier, makeMessageListContainerModifier, makeMessageViewModifier, makeComposerViewModifier) to a custom Styles implementation and assign it to factory.styles.
• When implementing your custom Styles, conform to the Styles protocol directly — RegularStyles and LiquidGlassStyles are public class (not open), so you cannot subclass them from your own module. The protocol provides defaults for most methods, but you must implement makeComposerInputViewModifier(options:), makeComposerButtonViewModifier(options:), and makeSuggestionsContainerModifier(options:) (use RegularInputViewModifier, RegularButtonViewModifier, and SuggestionsRegularContainerModifier to match the default appearance).
• If you customized channel-list search in v4, move that work out of makeChannelListTopView(...) and into Styles.makeSearchableModifier(options:). Treat makeChannelListTopView(options:) as a separate top content area in v5.
• Move supportedMoreChannelActions to ChannelListConfig.supportedMoreChannelActions.
• Move supportedMessageActions to MessageListConfig.supportedMessageActions.
• Move navigationBarDisplayMode to ChannelListConfig.navigationBarDisplayMode and/or MessageListConfig.navigationBarDisplayMode; do not rely on the compatibility helper on DefaultViewFactory.
• Update all ViewFactory overrides that take individual parameters to use the new single options object signature.
• Review every custom ViewFactory override manually even if your project compiles; stale v4 methods can still compile while no longer overriding anything.
• Pay special attention to old makeLeadingSwipeActionsView(...), custom attachment picker and preview overrides, factory-level makeMessageViewModifier(for:), and old supportedMoreChannelActions(...) / supportedMessageActions(...) methods.
• Replace removed ViewFactory methods with their v5 equivalents (see the Channel And Message List table above).
• Replace imageLoader and videoLoader on Utils with a single mediaLoader parameter.
• Replace ImageLoading/NukeImageLoader conformances with MediaLoader/StreamMediaLoader.
• Replace VideoLoading/VideoPreviewLoader with MediaLoader's loadVideoPreview method.
• Replace CDNClient / AttachmentUploader with CDNStorage on ChatClientConfig.cdnStorage.
• Replace ImageCDN / StreamImageCDN / FileCDN with CDNRequester / StreamCDNRequester configured through StreamMediaLoader(cdnRequester:).

After these changes, most v4 SwiftUI integrations should compile against v5, but custom factories still need a manual review to confirm each override is active and mapped to the correct v5 hook.