UIKit-SwiftUI Bridging

Systematic guidance for bridging UIKit and SwiftUI. Most production iOS apps need both — this skill teaches the bridging patterns themselves, not the domain-specific views being bridged.

Decision Framework

digraph bridge {
    start [label="What are you bridging?" shape=diamond];

    start -> "UIViewRepresentable" [label="UIView subclass → SwiftUI"];
    start -> "UIViewControllerRepresentable" [label="UIViewController → SwiftUI"];
    start -> "UIGestureRecognizerRepresentable" [label="UIGestureRecognizer → SwiftUI\n(iOS 18+)"];
    start -> "UIHostingController" [label="SwiftUI view → UIKit"];
    start -> "UIHostingConfiguration" [label="SwiftUI in UIKit cell\n(iOS 16+)"];

    "UIViewRepresentable" [shape=box];
    "UIViewControllerRepresentable" [shape=box];
    "UIGestureRecognizerRepresentable" [shape=box];
    "UIHostingController" [shape=box];
    "UIHostingConfiguration" [shape=box];
}

Quick rules:

• Wrapping a

  UIView

  →

  UIViewRepresentable

  (Part 1)
• Wrapping a

  UIViewController

  →

  UIViewControllerRepresentable

  (Part 2)
• Wrapping a

  UIGestureRecognizer

  subclass →

  UIGestureRecognizerRepresentable

  (Part 2b, iOS 18+)
• Embedding SwiftUI in UIKit navigation →

  UIHostingController

  (Part 3)
• SwiftUI in UICollectionView/UITableView cells →

  UIHostingConfiguration

  (Part 3)
• Sharing state between UIKit and SwiftUI →

  @Observable

  shared model (Part 4)

Part 1: UIViewRepresentable — Wrapping UIViews

Use when you have a

UIView

For comprehensive MapKit patterns and the SwiftUI Map vs MKMapView decision, see

axiom-mapkit

.

Lifecycle

makeUIView(context:)         → Called ONCE. Create and configure the view.
updateUIView(_:context:)     → Called on EVERY SwiftUI state change. Patch, don't recreate.
dismantleUIView(_:coordinator:) → Called when removed from hierarchy. Clean up observers/timers.

Critical:

updateUIView

struct MapView: UIViewRepresentable {
    let region: MKCoordinateRegion

    func makeUIView(context: Context) -> MKMapView {
        let map = MKMapView()
        map.delegate = context.coordinator
        return map
    }

    func updateUIView(_ map: MKMapView, context: Context) {
        // ✅ Guard: only update if region actually changed
        if map.region.center.latitude != region.center.latitude
            || map.region.center.longitude != region.center.longitude {
            map.setRegion(region, animated: true)
        }
    }

    static func dismantleUIView(_ map: MKMapView, coordinator: Coordinator) {
        map.removeAnnotations(map.annotations)
    }
}

State Synchronization

State flows in two directions across the bridge:

SwiftUI → UIKit: Via

updateUIView

UIKit → SwiftUI: Via the Coordinator, using

@Binding

struct SearchField: UIViewRepresentable {
    @Binding var text: String
    @Binding var isEditing: Bool

    func makeUIView(context: Context) -> UISearchBar {
        let bar = UISearchBar()
        bar.delegate = context.coordinator
        return bar
    }

    func updateUIView(_ bar: UISearchBar, context: Context) {
        bar.text = text  // SwiftUI → UIKit
    }

    func makeCoordinator() -> Coordinator { Coordinator(self) }

    class Coordinator: NSObject, UISearchBarDelegate {
        var parent: SearchField

        init(_ parent: SearchField) { self.parent = parent }

        func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
            parent.text = searchText  // UIKit → SwiftUI
        }

        func searchBarTextDidBeginEditing(_ searchBar: UISearchBar) {
            parent.isEditing = true  // UIKit → SwiftUI
        }

        func searchBarTextDidEndEditing(_ searchBar: UISearchBar) {
            parent.isEditing = false
        }
    }
}

Layout Property Warning

SwiftUI owns the layout of representable views. Never modify

center

bounds

frame

transform

intrinsicContentSize

sizeThatFits(_:)

Coordinator Pattern

The Coordinator is a reference type (

class

1. Acts as the delegate/data source for the UIKit view
2. Holds a reference to the parent

   UIViewRepresentable

   struct
3. Bridges UIKit callbacks back to SwiftUI

   @Binding

   properties

makeCoordinator()

Why not closures? Closures capture

self

// ❌ Closure-based: retain cycle risk, no delegate protocol support
func makeUIView(context: Context) -> UITextField {
    let field = UITextField()
    field.addTarget(self, action: #selector(textChanged), for: .editingChanged) // Won't compile — self is a struct
    return field
}

// ✅ Coordinator: clean lifecycle, delegate support
func makeCoordinator() -> Coordinator { Coordinator(self) }

class Coordinator: NSObject, UITextFieldDelegate {
    var parent: SearchField
    init(_ parent: SearchField) { self.parent = parent }

    func textFieldDidChangeSelection(_ textField: UITextField) {
        parent.text = textField.text ?? ""
    }
}

Sizing

UIViewRepresentable views participate in SwiftUI layout. Control sizing with:

// If the UIView has intrinsicContentSize, SwiftUI respects it
// For views without intrinsic size (MKMapView, WKWebView), set a frame:
MapView(region: region)
    .frame(height: 300)

// For views that should size to fit their content:
WrappedLabel(text: "Hello")
    .fixedSize()  // Uses intrinsicContentSize

Override

sizeThatFits(_:)

struct WrappedLabel: UIViewRepresentable {
    let text: String

    func makeUIView(context: Context) -> UILabel {
        let label = UILabel()
        label.numberOfLines = 0
        return label
    }

    func updateUIView(_ label: UILabel, context: Context) {
        label.text = text
    }

    // Custom size proposal — SwiftUI calls this during layout
    func sizeThatFits(_ proposal: ProposedViewSize, uiView: UILabel, context: Context) -> CGSize? {
        let width = proposal.width ?? UIView.layoutFittingCompressedSize.width
        return uiView.systemLayoutSizeFitting(
            CGSize(width: width, height: UIView.layoutFittingCompressedSize.height),
            withHorizontalFittingPriority: .required,
            verticalFittingPriority: .fittingSizeLevel
        )
    }
}

Scroll-Tracking Navigation Bars (iOS 15+)

When wrapping a UIScrollView subclass, tell the navigation bar which scroll view to track for large title collapse:

func makeUIView(context: Context) -> UITableView {
    let table = UITableView()
    return table
}

func updateUIView(_ table: UITableView, context: Context) {
    // Tell the nearest navigation controller to track this scroll view
    // for inline/large title transitions
    if let navController = sequence(first: table as UIResponder, next: \.next)
        .compactMap({ $0 as? UINavigationController }).first {
        navController.navigationBar.setContentScrollView(table, forEdge: .top)
    }
}

Without this, navigation bar large titles won't collapse when scrolling a wrapped UIScrollView.

Animation Bridging

Use

context.transaction.animation

func updateUIView(_ uiView: UIView, context: Context) {
    if context.transaction.animation != nil {
        UIView.animate(withDuration: 0.3) {
            uiView.alpha = isVisible ? 1 : 0
        }
    } else {
        uiView.alpha = isVisible ? 1 : 0
    }
}

iOS 18+ animation unification: SwiftUI animations can be applied directly to UIKit views via

UIView.animate(_:)

• SwiftUI animations are NOT backed by CAAnimation — they use a different rendering path
• Incompatible with

  UIViewPropertyAnimator

  and

  UIView

  keyframe animations
• Velocity retargeting: Re-targeted SwiftUI animations carry forward velocity from interrupted animations, creating fluid transitions

For comprehensive animation bridging patterns, see

/skill axiom-swiftui-animation-ref

Part 2: UIViewControllerRepresentable — Wrapping UIViewControllers

Use when wrapping a full

UIViewController

Lifecycle

makeUIViewController(context:)         → Called ONCE. Create and configure.
updateUIViewController(_:context:)     → Called on SwiftUI state changes.
dismantleUIViewController(_:coordinator:) → Cleanup.

Canonical Example: PHPickerViewController

struct PhotoPicker: UIViewControllerRepresentable {
    @Binding var selectedImages: [UIImage]
    @Environment(\.dismiss) private var dismiss

    func makeUIViewController(context: Context) -> PHPickerViewController {
        var config = PHPickerConfiguration()
        config.selectionLimit = 5
        config.filter = .images
        let picker = PHPickerViewController(configuration: config)
        picker.delegate = context.coordinator
        return picker
    }

    func updateUIViewController(_ picker: PHPickerViewController, context: Context) {
        // PHPicker doesn't support updates after creation
    }

    func makeCoordinator() -> Coordinator { Coordinator(self) }

    class Coordinator: NSObject, PHPickerViewControllerDelegate {
        var parent: PhotoPicker

        init(_ parent: PhotoPicker) { self.parent = parent }

        func picker(_ picker: PHPickerViewController, didFinishPicking results: [PHPickerResult]) {
            parent.selectedImages = []
            for result in results {
                result.itemProvider.loadObject(ofClass: UIImage.self) { image, _ in
                    if let image = image as? UIImage {
                        DispatchQueue.main.async {
                            self.parent.selectedImages.append(image)
                        }
                    }
                }
            }
            parent.dismiss()
        }
    }
}

When the Controller Presents Its Own UI

Some controllers (UIImagePickerController, MFMailComposeViewController, SFSafariViewController) present their own full-screen UI. Handle dismissal through the coordinator:

class Coordinator: NSObject, MFMailComposeViewControllerDelegate {
    var parent: MailComposer

    func mailComposeController(_ controller: MFMailComposeViewController,
                                didFinishWith result: MFMailComposeResult, error: Error?) {
        parent.dismiss()  // Let SwiftUI handle the dismissal
    }
}

Don't call

controller.dismiss(animated:)

@Environment(\.dismiss)

Presentation Context

The wrapped controller doesn't automatically inherit SwiftUI's navigation context. If you need the controller to push onto a navigation stack, you need UIViewControllerRepresentable inside a NavigationStack, and the controller needs access to the navigation controller:

// ❌ This won't push — the controller has no navigationController
struct WrappedVC: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> MyViewController {
        let vc = MyViewController()
        vc.navigationController?.pushViewController(otherVC, animated: true) // nil
        return vc
    }
}

// ✅ Present modally instead, or use UIHostingController in a UIKit navigation flow
.sheet(isPresented: $showPicker) {
    PhotoPicker(selectedImages: $images)
}

Part 2b: UIGestureRecognizerRepresentable (iOS 18+)

Use when you need a UIKit gesture recognizer in SwiftUI — for gestures that SwiftUI's native gesture API doesn't support (custom subclasses, precise UIKit gesture state machine, hit testing control).

Pre-iOS 18 fallback: Attach the gesture recognizer to a transparent

UIView

UIViewRepresentable

CoordinateSpaceConverter

location(in:)

Lifecycle

makeUIGestureRecognizer(context:)              → Called ONCE. Create the recognizer.
handleUIGestureRecognizerAction(_:context:)    → Called when the gesture is recognized.
updateUIGestureRecognizer(_:context:)          → Called on SwiftUI state changes.
makeCoordinator(converter:)                    → Optional. Create coordinator for state.

No manual target/action — the system manages action target installation. Implement

handleUIGestureRecognizerAction

Canonical Example: Long Press with Location

struct LongPressGesture: UIGestureRecognizerRepresentable {
    @Binding var pressLocation: CGPoint?

    func makeUIGestureRecognizer(context: Context) -> UILongPressGestureRecognizer {
        let recognizer = UILongPressGestureRecognizer()
        recognizer.minimumPressDuration = 0.5
        return recognizer
    }

    func handleUIGestureRecognizerAction(
        _ recognizer: UILongPressGestureRecognizer, context: Context
    ) {
        switch recognizer.state {
        case .began:
            // localLocation converts UIKit coordinates to SwiftUI coordinate space
            pressLocation = context.converter.localLocation
        case .ended, .cancelled:
            pressLocation = nil
        default:
            break
        }
    }
}

// Usage
struct ContentView: View {
    @State private var pressLocation: CGPoint?

    var body: some View {
        Rectangle()
            .gesture(LongPressGesture(pressLocation: $pressLocation))
    }
}

CoordinateSpaceConverter

The

context.converter

localLocation

localTranslation

localVelocity

location(in:)

translation(in:)

velocity(in:)

When to Use This vs SwiftUI Gestures

UIGestureRecognizer

UIGestureRecognizerRepresentable

.possible

.began

.changed

UIGestureRecognizerRepresentable

delegate

UIGestureRecognizerRepresentable

UIGestureRecognizerRepresentable

Part 3: UIHostingController — SwiftUI Inside UIKit

Use when embedding SwiftUI views in an existing UIKit navigation hierarchy.

Basic Embedding

// Push onto UIKit navigation stack
let profileView = ProfileView(user: user)
let hostingController = UIHostingController(rootView: profileView)
navigationController?.pushViewController(hostingController, animated: true)

// Present modally
let settingsView = SettingsView()
let hostingController = UIHostingController(rootView: settingsView)
hostingController.modalPresentationStyle = .pageSheet
present(hostingController, animated: true)

Child View Controller Embedding

When embedding as a child VC (e.g., a SwiftUI card inside a UIKit layout):

let swiftUIView = StatusCard(status: currentStatus)
let hostingController = UIHostingController(rootView: swiftUIView)
hostingController.sizingOptions = .intrinsicContentSize  // iOS 16+

addChild(hostingController)
view.addSubview(hostingController.view)
hostingController.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    hostingController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
    hostingController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
    hostingController.view.topAnchor.constraint(equalTo: headerView.bottomAnchor)
])
hostingController.didMove(toParent: self)

sizingOptions: .intrinsicContentSize

sizingOptions

OptionSet

• .intrinsicContentSize

  — auto-invalidates intrinsic content size when SwiftUI content changes

• .preferredContentSize

  — tracks content's ideal size in the controller's

  preferredContentSize

Explicit Size Queries

Use

sizeThatFits(in:)

let hostingController = UIHostingController(rootView: CompactCard(item: item))

// Query preferred size for a given width constraint
let fittingSize = hostingController.sizeThatFits(in: CGSize(width: 320, height: .infinity))
// Returns the optimal CGSize for the SwiftUI content

This is useful when you need the hosting controller's size before adding it to the view hierarchy, or when embedding in contexts where

sizingOptions

Environment Bridging

Standard system environment values (

colorScheme

sizeCategory

locale

@Environment

UITraitBridgedEnvironmentKey

Option 1: Inject explicitly (simplest, works on all versions):

let view = DetailView(store: appStore, theme: currentTheme)
let hostingController = UIHostingController(rootView: view)

Option 2: UITraitBridgedEnvironmentKey (iOS 17+, bidirectional bridging):

Bridge custom environment values between UIKit traits and SwiftUI environment:

// 1. Define a UIKit trait
struct FeatureOneTrait: UITraitDefinition {
    static let defaultValue = false
}

extension UIMutableTraits {
    var featureOne: Bool {
        get { self[FeatureOneTrait.self] }
        set { self[FeatureOneTrait.self] = newValue }
    }
}

// 2. Define a SwiftUI EnvironmentKey
struct FeatureOneKey: EnvironmentKey {
    static let defaultValue = false
}

extension EnvironmentValues {
    var featureOne: Bool {
        get { self[FeatureOneKey.self] }
        set { self[FeatureOneKey.self] = newValue }
    }
}

// 3. Bridge them
extension FeatureOneKey: UITraitBridgedEnvironmentKey {
    static func read(from traitCollection: UITraitCollection) -> Bool {
        traitCollection[FeatureOneTrait.self]
    }
    static func write(to mutableTraits: inout UIMutableTraits, value: Bool) {
        mutableTraits.featureOne = value
    }
}

Now

@Environment(\.featureOne)

traitOverrides

.environment(\.featureOne, true)

To push values from UIKit into hosted SwiftUI content:

// In any UIKit view controller — flows down to UIHostingController children
viewController.traitOverrides.featureOne = true

UIHostingConfiguration (iOS 16+)

Use SwiftUI views as UICollectionView or UITableView cells:

cell.contentConfiguration = UIHostingConfiguration {
    HStack {
        Image(systemName: item.icon)
            .foregroundStyle(.tint)
        VStack(alignment: .leading) {
            Text(item.title)
                .font(.headline)
            Text(item.subtitle)
                .font(.subheadline)
                .foregroundStyle(.secondary)
        }
    }
}
.margins(.all, EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
.minSize(width: nil, height: 44)  // Minimum tap target height
.background(.quaternarySystemFill)  // ShapeStyle background

Cell clipping? UIHostingConfiguration cells self-size. If cells are clipped, the collection view layout likely uses fixed

itemSize

estimated

Advantages over full UIHostingController

• No child view controller management
• Automatic cell sizing
• Self-sizing invalidation on state change
• Compatible with diffable data sources

When to use UIHostingConfiguration vs UIHostingController

Scroll-Tracking for Navigation Bars

When a UIHostingController contains a scroll view and is pushed onto a UINavigationController, large title collapse may not work. Use

setContentScrollView

let hostingController = UIHostingController(rootView: ScrollableListView())

// After pushing, tell the nav bar to track the scroll view
if let scrollView = hostingController.view.subviews.compactMap({ $0 as? UIScrollView }).first {
    navigationController?.navigationBar.setContentScrollView(scrollView, forEdge: .top)
}

This is a common issue when embedding SwiftUI

List

ScrollView

Keyboard Handling in Hybrid Layouts

When mixing UIKit and SwiftUI, keyboard avoidance may not work automatically. Use

UIKeyboardLayoutGuide

// Constrain the hosting controller's view above the keyboard
hostingController.view.bottomAnchor.constraint(
    equalTo: view.keyboardLayoutGuide.topAnchor
).isActive = true

Part 4: Shared State with @Observable

When UIKit and SwiftUI coexist in the same app, you need a shared model layer.

@Observable

@Observable as the Shared Model Layer

@Observable
class AppState {
    var userName: String = ""
    var isLoggedIn: Bool = false
    var itemCount: Int = 0
}

SwiftUI side — standard property wrappers:

struct ProfileView: View {
    @State var appState: AppState  // or @Environment, @Bindable

    var body: some View {
        Text("Welcome, \(appState.userName)")
        Text("\(appState.itemCount) items")
    }
}

Why UIKit needs explicit observation: SwiftUI's rendering engine automatically participates in the Observation framework — when a view's

body

@Observable

UIKit side (pre-iOS 26) — manual observation with

withObservationTracking()

class DashboardViewController: UIViewController {
    let appState: AppState

    override func viewDidLoad() {
        super.viewDidLoad()
        observeState()
    }

    private func observeState() {
        withObservationTracking {
            // Properties accessed here are tracked
            titleLabel.text = appState.userName
            countLabel.text = "\(appState.itemCount) items"
        } onChange: {
            // Fires ONCE on the thread that mutated the property — must re-register
            // Always dispatch to main: onChange can fire on ANY thread
            DispatchQueue.main.async { [weak self] in
                self?.observeState()
            }
        }
    }
}

UIKit side (iOS 26+) — automatic observation tracking:

UIKit automatically tracks

@Observable

updateProperties()

layoutSubviews()

viewWillLayoutSubviews()

draw(_:)

class DashboardViewController: UIViewController {
    let appState: AppState

    // iOS 26+: Properties accessed here are auto-tracked
    override func updateProperties() {
        super.updateProperties()
        titleLabel.text = appState.userName
        countLabel.text = "\(appState.itemCount) items"
    }
}

Info.plist requirement: In iOS 18, add

UIObservationTrackingEnabled = true

iOS 16 Fallback: ObservableObject + Combine

If targeting iOS 16 (before

@Observable

ObservableObject

@Published

class AppState: ObservableObject {
    @Published var userName: String = ""
    @Published var itemCount: Int = 0
}

// UIKit side — observe with Combine sink
class DashboardViewController: UIViewController {
    let appState: AppState
    private var cancellables = Set<AnyCancellable>()

    override func viewDidLoad() {
        super.viewDidLoad()
        appState.$userName
            .receive(on: DispatchQueue.main)
            .sink { [weak self] name in
                self?.titleLabel.text = name
            }
            .store(in: &cancellables)
    }
}

Migration Note

@Observable

ObservableObject

@Published

• Replace

  ObservableObject

  classes with

  @Observable

• Remove

  @Published

  property wrappers (observation is automatic)
• SwiftUI views keep working —

  @State

  and

  @Environment

  support

  @Observable

  directly
• UIKit views gain observation through

  withObservationTracking()

  (iOS 17+) or automatic tracking (iOS 26+)

Part 5: Common Gotchas

var parent: X

let

updateUIView

UITraitBridgedEnvironmentKey

setContentScrollView(_:forEdge:)

sizingOptions: .intrinsicContentSize

hostingController.view.invalidateIntrinsicContentSize()

UIViewRepresentable

delegate = context.coordinator

makeUIView

updateUIView

center

bounds

frame

transform

UIKeyboardLayoutGuide

withObservationTracking()

UIObservationTrackingEnabled

updateProperties()

Part 6: Anti-Patterns

makeUIView

updateUIView

makeUIView

updateUIView

@Environment

UITraitBridgedEnvironmentKey

dismiss(animated:)

@Environment(\.dismiss)

@Binding var isPresented

dismantleUIView

deinit

Resources

WWDC: 2019-231, 2022-10072, 2023-10149, 2024-10118, 2024-10145, 2025-243, 2025-256

Docs: /swiftui/uiviewrepresentable, /swiftui/uiviewcontrollerrepresentable, /swiftui/uigesturerecognizerrepresentable, /uikit/uihostingcontroller, /uikit/uihostingconfiguration, /swiftui/uitraitbridgedenvironmentkey, /observation, /uikit/updating-views-automatically-with-observation-tracking

Skills: app-composition, swiftui-animation-ref, camera-capture, transferable-ref, swift-concurrency