SwiftUI’s declarative syntax often feels like magic. You can write natural-looking code with if statements, multiple view expressions, even loops, and somehow, it all just works. But how?

The secret lies in ViewBuilder, one of Swift’s most powerful tools that transforms your declarative code into optimized SwiftUI types. Let’s dive into what makes this possible.

The Foundation: Result Builders

Before focusing on ViewBuilder itself, it’s important to understand what it’s built on: Swift’s Result Builder system (previously called Function Builders).

Result builders are a compiler feature that lets you build domain-specific languages (DSLs) by transforming blocks of code into other structures, in SwiftUI’s case, views.

The Problem Without ViewBuilder

Imagine SwiftUI didn’t have ViewBuilder. Here’s what you’d be dealing with:

// ❌ This wouldn't compile without ViewBuilder
struct MyView: View {
    let showDetails: Bool

    var body: some View {
        if showDetails {
            DetailView()        // Type: DetailView
        } else {
            SummaryView()       // Type: SummaryView
        }
        // Error: inconsistent return types!
    }
}

What’s the issue?
Swift’s type system expects a consistent return type, but DetailView and SummaryView are two different types.

Without ViewBuilder, we’d need clunky workarounds like type erasure:

// ❌ Ugly workaround
var body: some View {
    if showDetails {
        return AnyView(DetailView())     // Type-erased
    } else {
        return AnyView(SummaryView())    // Adds runtime cost
    }
}

This works, but at the cost of performance and type safety.

The Magic of ViewBuilder

With ViewBuilder, SwiftUI handles the transformation behind the scenes:

// ✅ What you write
@ViewBuilder
var body: some View {
    if showDetails {
        DetailView()
    } else {
        SummaryView()
    }
}

This gets compiled roughly into:

// 🔄 What the compiler generates
var body: some View {
    let result: _ConditionalContent<DetailView, SummaryView>
    if showDetails {
        result = ViewBuilder.buildEither(first: DetailView())
    } else {
        result = ViewBuilder.buildEither(second: SummaryView())
    }
    return ViewBuilder.buildBlock(result)
}

Pretty cool, right? Let’s see how this works in more situations.

How ViewBuilder Transforms Code

ViewBuilder uses different transformation methods depending on the structure of your code. Here’s a breakdown:

1. Conditions: buildEither

When using if/else, ViewBuilder transforms it like this:

// Original
if isLoggedIn {
    ProfileView()
} else {
    LoginView()
}

// Transformed
ViewBuilder.buildEither(first: ProfileView())  // or second: LoginView()

➡️ Both branches return a _ConditionalContent type, which maintains type consistency while preserving concrete types for performance.

2. Optional Views: buildOptional

For if statements without else:

// Original
if shouldShow {
    NotificationView()
}

// Transformed
ViewBuilder.buildOptional(shouldShow ? NotificationView() : nil)

➡️ The result is an optional view, great for views that appear conditionally.

3. Multiple Views: buildBlock

For multiple view expressions:

// Original
Text("Title")
Image(systemName: "star")
Button("Action") { }

// Transformed
ViewBuilder.buildBlock(
    Text("Title"),
    Image(systemName: "star"),
    Button("Action") { }
)

➡️ The result is a TupleView, which explains SwiftUI’s 10-view limit per container, it’s tied to buildBlock overloads.

4. Combining Constructs

These transformations can also be mixed:

VStack {
    Text("Header")
    if isLoading {
        ProgressView()
    } else {
        ContentView()
    }
    Text("Footer")
}

The compiler does something like:

let conditional = isLoading
    ? ViewBuilder.buildEither(first: ProgressView())
    : ViewBuilder.buildEither(second: ContentView())

ViewBuilder.buildBlock(
    Text("Header"),
    conditional,
    Text("Footer")
)

➡️ Resulting in a TupleView<(Text, _ConditionalContent, Text)>.

The Loop Exception: Why ForEach Is Special

Many devs wonder why they can’t use a for loop inside a ViewBuilder:

// ❌ Won’t compile
@ViewBuilder
var content: some View {
    for item in items {
        Text(item.name)
    }
}

Instead, SwiftUI provides:

// ✅ Works
ForEach(items, id: \.self) { item in
    Text(item.name)
}

Why Not buildArray?

It may seem logical for SwiftUI to support buildArray like other builders, but there are deep reasons why it doesn’t.

Let’s imagine what it might look like:

extension ViewBuilder {
    static func buildArray<Element: View>(_ elements: [Element]) -> some View {
        VStack {
            ForEach(elements.indices, id: \.self) { index in
                elements[index]
            }
        }
    }
}

So why doesn’t SwiftUI use this?

The Core Problems with buildArray

  1. Immediate Evaluation
// All views are created up front
@ViewBuilder
var content: some View {
    for user in users {
        UserRowView(user: user)
    }
}

This would be transformed into:

ViewBuilder.buildArray(
    users.map { UserRowView(user: $0) }
)

➡️ All views are evaluated immediately, which breaks SwiftUI’s lazy rendering.

  1. No Identity Tracking
let views = users.map { UserRowView(user: $0) }
// SwiftUI can’t tell which view maps to which user.
// Result: No smooth animations, poor diffing, lost state

Why ForEach Solves It

Apple solved these problems by designing ForEach as a specialized view that integrates with SwiftUI’s rendering engine:

struct ForEach<Data, ID, Content>: View 
where Data: RandomAccessCollection, ID: Hashable, Content: View {
    let data: Data
    let id: KeyPath<Data.Element, ID>
    let content: (Data.Element) -> Content
}

Internally, it uses lazy rendering, identity tracking, diffing, and recycling to ensure performance and correctness, something a simple array-based builder couldn’t handle.

Conclusion

What feels like SwiftUI “magic” is actually a well-crafted system built on ResultBuilder transformations. ViewBuilder handles the complexity of conditions, optionals, and multiple views, while ForEach takes care of performant rendering for collections.

Understanding how it all works gives you superpowers when debugging and building more scalable UI structures.

Happy building! 🧱