@ViewBuilder: what is it, result builder for View in SwiftUI

What is @ViewBuilder in SwiftUI?

@ViewBuilder is an annotation that implements the result builder pattern (SE-0289), which allows SwiftUI to compose multiple Views into a single composition using declarative syntax. It automatically wraps multiple expressions, conditional constructs, and optional values into their corresponding types: TupleView, ConditionalContent, OptionalContent.

Before result builders, developers had to manually wrap elements in VStack or HStack, and use ternary operators or factory methods for conditional logic. @ViewBuilder made SwiftUI syntax concise and readable, allowing you to write code that looks like regular Swift with if/else and loops.

According to Swift Evolution SE-0289, result builders are a general mechanism not tied to SwiftUI. @ViewBuilder is one implementation of this mechanism, alongside @StringBuilder for string construction and library implementations for other DSLs. In SwiftUI, @ViewBuilder is used not only for body but also for closure parameters of containers (VStack, HStack, ZStack, List).

Difference from the Imperative Approach

In imperative UIKit, you explicitly create a UIView, configure its properties, and add it to the hierarchy via addSubview. In SwiftUI with @ViewBuilder, you declaratively describe which Views should be displayed, and SwiftUI handles the creation, updating, and removal of elements based on state changes.

How @ViewBuilder Works: Result Builder

Result builder is a Swift mechanism that transforms a sequence of expressions into a single composite value through static methods buildBlock, buildOptional, buildEither, and others. When the compiler sees the @ViewBuilder annotation, it automatically applies these methods to the code block during compilation.

@resultBuilder
struct ViewBuilder {
    static func buildBlock<C0, C1>(_ c0: C0, _ c1: C1) -> TupleView<(C0, C1)>
    static func buildIf<C>(_ c: C?) -> C?
    static func buildEither<T, F>(first: T) -> ConditionalContent<T, F>
    static func buildEither<T, F>(second: F) -> ConditionalContent<T, F>
}

buildBlock accepts 1 to 10 expressions and returns a TupleView. Each arity (number of expressions) has its own buildBlock overload: from buildBlock to buildBlock. This is why the number of elements in a single @ViewBuilder block is limited to 10.

buildEither (first/second) handles if/else constructs. Each branch is passed to the corresponding method, and the result is wrapped in ConditionalContent — a type that hides the specific branch types and provides a unified interface for SwiftUI.

Implicit @ViewBuilder Behavior

In SwiftUI, the body property is already implicitly annotated with @ViewBuilder — you don't see this annotation in code, but the compiler applies it automatically. However, for custom properties that return multiple Views, or for closure parameters, the annotation must be specified explicitly.

@ViewBuilder Limitations and How to Work Around Them

Limitation 1 — 10 elements in a block. This is the most well-known limitation of @ViewBuilder. If you need to display more than 10 elements at the same level, the compiler will produce an error. Workarounds include Group, ForEach, List, or breaking into subcomponents. Group does not add visual nesting, but each Group counts as one element.

struct ManyElementsView: View {
    var body: some View {
        Group {
            Text("1"); Text("2"); Text("3")
            Text("4"); Text("5"); Text("6")
            Text("7"); Text("8"); Text("9")
        }
        Group {
            Text("10"); Text("11"); Text("12")
        }
    }
}

Limitation 2 — lack of support for certain constructs. @ViewBuilder does not support do/catch, guard, for-in (without ForEach), and other control flow constructs. For loops, use ForEach with identifiable data. For error handling, use separate Views that accept Result or optional values.

Limitation 3 — debugging complexity. When errors occur in @ViewBuilder, the compiler produces verbose messages where it's hard to find the root cause. Typical issues: type mismatches in if/else branches, exceeding the 10-element limit, or missing required buildBlock overloads.

@ViewBuilder Usage Patterns

Pattern 1: conditional display via if/else. The most common use case for @ViewBuilder. It allows showing different Views based on state without using ternary operators or factory methods.

struct StatusView: View {
    var status: LoadStatus

    @ViewBuilder
    var body: some View {
        switch status {
        case .loading:
            ProgressView("Loading...")
        case .loaded(let data):
            DataView(data: data)
        case .error(let message):
            ErrorView(message: message)
        }
    }
}

Pattern 2: @ViewBuilder in function and initializer parameters. Used to create reusable containers that accept child Views via a closure. This is the standard pattern for libraries and UI components.

struct SectionCard<Content: View>: View {
    let title: String
    @ViewBuilder let content: Content

    var body: some View {
        VStack(alignment: .leading) {
            Text(title).font(.headline)
            content
        }
        .padding()
        .background(Color.gray.opacity(0.1))
        .cornerRadius(12)
    }
}

Pattern 3: composition with ForEach. @ViewBuilder works correctly with ForEach, allowing dynamic generation of elements from a data array. Each ForEach element counts as one expression in the @ViewBuilder context.

Creating a Custom ViewBuilder for Reusable Components

Custom ViewBuilder is a user-defined function or property annotated with @ViewBuilder that returns some View. Such functions allow encapsulating complex display logic and reusing it across different parts of the application.

struct FormRow<Content: View>: View {
    let label: String
    @ViewBuilder let content: Content

    var body: some View {
        HStack {
            Text(label)
                .frame(width: 120, alignment: .trailing)
            content
        }
    }
}

// Usage:
FormRow(label: "Name") {
    TextField("Enter name", text: $name)
}

FormRow(label: "Gender") {
    Picker("Select", selection: $gender) {
        Text("Male").tag(Gender.male)
        Text("Female").tag(Gender.female)
    }
}

Important rule: a custom function with @ViewBuilder must return some View, not a concrete type or the View protocol. Only an opaque type allows hiding the concrete implementation while preserving composition flexibility.

Performance: custom @ViewBuilder functions add no overhead compared to direct body code. The compiler inlines calls and optimizes the resulting code. Breaking body into @ViewBuilder functions improves readability without sacrificing performance.