Swift `@resultBuilder` — a comprehensive guide (2025)

A practical, copy‑pasteable handbook to designing, implementing, and using result builders to create expressive DSLs.

0) TL;DR

@resultBuilder lets you turn a multi‑statement closure into a single value at compile time.
You write a builder type (struct/enum/class) with static build… methods. The compiler rewrites statements (if, loops, etc.) into calls to those methods.
Common methods: buildBlock or buildPartialBlock(first:/accumulated:next:), plus buildExpression, buildEither, buildIf/buildOptional, buildArray, buildLimitedAvailability, and optionally buildFinalResult.
Use it to build SwiftUI‑style APIs for HTML, SQL, Auto Layout, navigation graphs, app menus, regexes, charts…
Keep builders small and composable to avoid type‑checking slow‑downs.

1) What is a result builder?

A result builder is a type annotated with @resultBuilder. When used to decorate a function/var/subscript parameter or return value, Swift rewrites the closure’s statements into calls on your builder’s static methods, producing one final value.

High‑level mental model

Each statement in the closure becomes a component.
Control flow (if/else, loops) becomes calls to specific builder methods.
The builder then combines those components into a final result.

The transformation happens at compile time; there’s no runtime reflection or magic.

2) Where can I use `@resultBuilder`?

You can attach a result builder to:

Function/initializer parameters
Computed properties
Subscripts

@resultBuilder
enum StringListBuilder {
    static func buildExpression(_ expr: String) -> [String] { [expr] }
    static func buildBlock(_ parts: [String]...) -> [String] { parts.flatMap { $0 } }
}

func makeCSV(@StringListBuilder _ content: () -> [String]) -> String {
    content().joined(separator: ",")
}

let csv = makeCSV {
    "apples"
    "bananas"
    "cherries"
}
// → "apples,bananas,cherries"

You can also return builder‑decorated content from computed properties:

struct Page {
    @StringListBuilder var keywords: [String] {
        "swift"; "result builders"; "dsl"
    }
}

3) The builder methods — a quick reference

You don’t need all of these. Implement only what your DSL needs.

Statements in your closure    →    Methods you implement
───────────────────────────         ──────────────────────────────
A sequence of statements           → buildBlock(_:)   (or buildPartialBlock)
Single `if` (no else)              → buildIf(_:) or buildOptional(_:)  // either spelling works
`if` / `if-else` / `switch`        → buildEither(first:) / buildEither(second:)
`for` loops / multiple elements    → buildArray(_:)   // receives [Component]
#available checks                  → buildLimitedAvailability(_:)
Coerce per-statement values        → buildExpression(_:)  // e.g. Int → [Int]
Convert final component type       → buildFinalResult(_:) // optional
Modern, scalable statement chain   → buildPartialBlock(first:) + buildPartialBlock(accumulated:next:)

Minimal “just works” set

For many builders:

buildExpression(_:) → wraps a single element into your component type.
buildBlock(_:) or the two buildPartialBlock methods → concatenates components.
Optionally add buildEither / buildIf and buildArray to support if and for.

4) Classic vs modern concatenation

Historically, builders used buildBlock(_:) with several overloads or a variadic parameter:

static func buildBlock(_ parts: [Node]...) -> [Node] { parts.flatMap { $0 } }

Modern builders prefer buildPartialBlock(first:) and buildPartialBlock(accumulated:next:), which scale better with many statements and produce clearer type errors:

static func buildPartialBlock(first: [Node]) -> [Node] { first }
static func buildPartialBlock(accumulated: [Node], next: [Node]) -> [Node] { accumulated + next }

You can provide either approach; many Apple builders ship with buildPartialBlock now.

5) Worked example: a tiny HTML DSL

Let’s build tags and text nodes and render them to a String:

struct Node { let raw: String }
extension Node { static func text(_ s: String) -> Node { .init(raw: s) } }

@resultBuilder
enum HTMLBuilder {
    static func buildExpression(_ n: Node) -> [Node] { [n] }

    // Allow string literals directly
    static func buildExpression(_ s: String) -> [Node] { [ .text(s) ] }

    // Concatenate statements
    static func buildPartialBlock(first: [Node]) -> [Node] { first }
    static func buildPartialBlock(accumulated: [Node], next: [Node]) -> [Node] { accumulated + next }

    // Conditionals & loops
    static func buildEither(first c: [Node]) -> [Node] { c }
    static func buildEither(second c: [Node]) -> [Node] { c }
    static func buildIf(_ c: [Node]?) -> [Node] { c ?? [] }
    static func buildArray(_ batches: [[Node]]) -> [Node] { batches.flatMap { $0 } }
}

struct Tag {
    let name: String
    @HTMLBuilder var children: [Node]

    init(_ name: String, @HTMLBuilder @autoclosure children: () -> [Node]) { // autoclosure optional
        self.name = name
        self.children = children()
    }

    func render() -> String {
        "<\(name)>\(children.map(\.raw).joined())</\(name)>"
    }
}

func div(@HTMLBuilder _ content: () -> [Node]) -> Node { .init(raw: Tag("div", children: content()).render()) }
func span(_ text: String) -> Node { .init(raw: "<span>\(text)</span>") }

// Usage
let isAdmin = true
let items = ["Home", "Docs", "Pricing"]
let page = Tag("section", children: {
    div {
        "Welcome "
        if isAdmin { span("(Admin)") }
    }
    for item in items { span(item) }
})

print(page.render())
// <section><div>Welcome <span>(Admin)</span></div><span>Home</span><span>Docs</span><span>Pricing</span></section>

Notes

buildExpression lets us accept both Node and String as statements.
buildIf enables single‑branch if without else.
buildArray powers for loops by flattening an Node.

6) Worked example: Auto Layout constraint builder (UIKit)

A result builder can clean up a list of optional constraints:

@resultBuilder
enum ConstraintBuilder {
    static func buildExpression(_ c: NSLayoutConstraint) -> [NSLayoutConstraint] { [c] }
    static func buildBlock(_ parts: [NSLayoutConstraint]...) -> [NSLayoutConstraint] { parts.flatMap { $0 } }
    static func buildEither(first c: [NSLayoutConstraint]) -> [NSLayoutConstraint] { c }
    static func buildEither(second c: [NSLayoutConstraint]) -> [NSLayoutConstraint] { c }
    static func buildOptional(_ c: [NSLayoutConstraint]?) -> [NSLayoutConstraint] { c ?? [] }
    static func buildArray(_ batches: [[NSLayoutConstraint]]) -> [NSLayoutConstraint] { batches.flatMap { $0 } }
}

func constraints(@ConstraintBuilder _ content: () -> [NSLayoutConstraint]) -> [NSLayoutConstraint] { content() }

// Usage
let alignTop = true
let cs = constraints {
    view.leadingAnchor.constraint(equalTo: container.leadingAnchor)
    view.trailingAnchor.constraint(equalTo: container.trailingAnchor)
    if alignTop {
        view.topAnchor.constraint(equalTo: container.topAnchor)
    }
}
NSLayoutConstraint.activate(cs)

7) Worked example: Query builder → SQL string

Showcases buildFinalResult to convert an array of clauses into a string:

@resultBuilder
enum SQLBuilder {
    typealias Component = [String]

    static func buildExpression(_ s: String) -> Component { [s] }
    static func buildPartialBlock(first: Component) -> Component { first }
    static func buildPartialBlock(accumulated: Component, next: Component) -> Component { accumulated + next }
    static func buildArray(_ chunks: [Component]) -> Component { chunks.flatMap { $0 } }
    static func buildEither(first c: Component) -> Component { c }
    static func buildEither(second c: Component) -> Component { c }

    // Final conversion to your API’s “real” type
    static func buildFinalResult(_ component: Component) -> String {
        component.joined(separator: " ")
    }
}

func SELECT(@SQLBuilder _ content: () -> String) -> String { content() }

let adults = SELECT {
    "SELECT name, age"
    "FROM users"
    "WHERE age >= 18"
}
// → "SELECT name, age FROM users WHERE age >= 18"

8) Control flow mapping (with code)

`if` / `else`

static func buildEither<T, F>(first: T) -> Either<T, F> { .left(T) }
static func buildEither<T, F>(second: F) -> Either<T, F> { .right(F) }
// Also provide buildIf(_:) *or* buildOptional(_:) for single-branch `if`.

Loops (`for`)

static func buildArray(_ components: [[Component]]) -> [Component] { components.flatMap { $0 } }

Availability (`if #available`)

static func buildLimitedAvailability(_ component: Component) -> Component { component }

You don’t call these yourself; the compiler lowers each construct to the appropriate method calls.

9) API design patterns

Slot‑based containers: Accept multiple builder closures (header, content, footer).
Composable decorators: Return a builder from extensions to conditionally apply transformations.
Typed DSLs: Use generics to preserve static guarantees (e.g., valid HTML nesting, SQL injection‑safe literals).
Erased DSLs: If you must mix heterogeneous types, provide overloads of buildExpression or (sparingly) type‑erase in buildFinalResult.

10) Advanced techniques

Overload buildExpression to accept rich statements: allow Int, domain types, or even closures that you invoke lazily.
@autoclosure parameters: You can accept autoclosures in initializers/functions that forward into builder‑decorated storage.
@escaping builders: If you store the closure for later, mark the parameter @escaping and consider capture lists to avoid cycles.
Custom Component type: Define a lightweight internal component (e.g., enum Clause { case select(String) ... }) and convert in buildFinalResult.
Partial vs final result: buildPartialBlock can use a different accumulator type from your final result; buildFinalResult maps it.
Testing DSLs: Make final results equatable (e.g., arrays/structs) so you can snapshot or assert on structure.

11) Interop notes with SwiftUI

SwiftUI’s @ViewBuilder is “just” a result builder specialized for views. You’ll see methods like buildIf(_:), buildEither, buildArray, and buildLimitedAvailability(_:) to support if, switch, loops, and availability checks. Many Apple frameworks now ship builders using buildPartialBlock instead of large buildBlock overload sets.

12) Pitfalls & best practices

Prefer buildPartialBlock for long lists of statements; it scales and yields better errors.
Avoid heavy work inside the closure—precompute outside and pass the result in; keep the builder focused on structure, not computation.
Stability of identity: If your DSL represents stateful elements (like UI views), be mindful of how conditional branches change structure.
Explicit return inside builder closures can change how type inference happens. Stick to plain statements where possible for the most ergonomic diagnostics.
Compilation time: Deeply nested, generic builders can slow type‑checking. Extract helpers, split blocks, or simplify generic interactions.

13) Recipe box (more ideas to try)

Menu builder that composes UIMenu/CommandMenu items conditionally.
Navigation graph builder emitting a typed graph structure, then a router from it.
Markdown builder turning nested elements into a string or attributed text.
Regex builder (simplified) producing Regex or NSRegularExpression with guarantees.
Feature‑flagged layout: one DSL that composes SwiftUI or UIKit depending on platform via availability.

14) Reference template — start here

Copy, rename, and adapt to your domain:

@resultBuilder
public enum Builder<Component> {
    public static func buildExpression(_ expr: Component) -> [Component] { [expr] }
    public static func buildPartialBlock(first: [Component]) -> [Component] { first }
    public static func buildPartialBlock(accumulated: [Component], next: [Component]) -> [Component] { accumulated + next }
    public static func buildEither(first c: [Component]) -> [Component] { c }
    public static func buildEither(second c: [Component]) -> [Component] { c }
    public static func buildIf(_ c: [Component]?) -> [Component] { c ?? [] }
    public static func buildArray(_ batches: [[Component]]) -> [Component] { batches.flatMap { $0 } }
    public static func buildLimitedAvailability(_ c: [Component]) -> [Component] { c }
    // Optional: map accumulator → real API type
    public static func buildFinalResult(_ c: [Component]) -> [Component] { c }
}

15) FAQ

Q: buildIf or buildOptional? Either works; choose one spelling and be consistent. Many Apple builders ship buildIf, while older examples show buildOptional.

Q: Do I still need buildBlock? No. Prefer the two buildPartialBlock methods unless you need backward compatibility with very old toolchains.

Q: Can a builder’s component type differ from the final result? Yes; use buildFinalResult for the conversion.

Q: How do switch statements work? The compiler lowers them to a series of buildEither(first:)/buildEither(second:) calls.

Q: Are result builders runtime‑expensive? No; they’re a compile‑time rewrite. Any overhead comes from the code you write and from compile‑time type‑checking, not from the builder mechanism itself.

Closing thought

Result builders are a lightweight way to make domain code read like the domain. Start with a tiny builder that only supports statements you need, then add conditionals, loops, and conversions as the DSL grows.

Swift "@resultBuilder" — A Comprehensive Guide With Many Examples (2025)

Contents

Swift `@resultBuilder` — a comprehensive guide (2025)

0) TL;DR

1) What is a result builder?

2) Where can I use `@resultBuilder`?

3) The builder methods — a quick reference

Minimal “just works” set

4) Classic vs modern concatenation

5) Worked example: a tiny HTML DSL

6) Worked example: Auto Layout constraint builder (UIKit)

7) Worked example: Query builder → SQL string

8) Control flow mapping (with code)

`if` / `else`

Loops (`for`)

Availability (`if #available`)

9) API design patterns

10) Advanced techniques

11) Interop notes with SwiftUI

12) Pitfalls & best practices

13) Recipe box (more ideas to try)

14) Reference template — start here

15) FAQ

Closing thought

Navigation menu

Swift "@resultBuilder" — A Comprehensive Guide With Many Examples (2025)

Swift @resultBuilder — a comprehensive guide (2025)

0) TL;DR

1) What is a result builder?

2) Where can I use @resultBuilder?

3) The builder methods — a quick reference

Minimal “just works” set

4) Classic vs modern concatenation

5) Worked example: a tiny HTML DSL

6) Worked example: Auto Layout constraint builder (UIKit)

7) Worked example: Query builder → SQL string

8) Control flow mapping (with code)

if / else

Loops (for)

Availability (if #available)

9) API design patterns

10) Advanced techniques

11) Interop notes with SwiftUI

12) Pitfalls & best practices

13) Recipe box (more ideas to try)

14) Reference template — start here

15) FAQ

Closing thought

Navigation menu

Search

Swift `@resultBuilder` — a comprehensive guide (2025)

2) Where can I use `@resultBuilder`?

`if` / `else`

Loops (`for`)

Availability (`if #available`)