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 or CocoaPods 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:

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

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

var images = Appearance.Images()

var 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:

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

var 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:

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

var 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))

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
)

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:

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 LiquidGlassStyles on iOS 26+ and RegularStyles otherwise. To customize modifiers, conform to Styles and assign your implementation to factory.styles:

struct MyStyles: Styles {
    // override only what you need
    func makeComposerViewModifier(options: ComposerViewModifierOptions) -> some ViewModifier {
        MyComposerModifier()
    }
}

DefaultViewFactory.shared.styles = MyStyles()

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

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 latest develop and v5 branches of stream-chat-swiftui.

The safest migration path is to take your custom ViewFactory, compile against v5, and then convert each failing override to the new signature shown above.

Migration Checklist

• Update your dependency to 5.x.
• Replace Appearance(...) initializers with var appearance = Appearance() and property assignment.
• Use Appearance.FontsSwiftUI() for SwiftUI font customization.
• Move tint customizations to ColorPalette, usually accentPrimary and navigationBarTintColor.
• 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.
• 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:).
• Migrate gallery/media customizations from makeGalleryView(...) and makeGalleryHeaderView(...) to makeMediaViewer(options:) and makeMediaViewerHeader(options:).
• Keep video player customizations, but update them to the new options-based makeVideoPlayerView/HeaderView/FooterView signatures.
• 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.
• 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.
• Replace removed ViewFactory methods with their v5 equivalents (see the Channel And Message List table above).

After these changes, most v4 SwiftUI integrations should compile against v5 without further structural changes.