{"id":9736,"date":"2025-05-30T15:25:00","date_gmt":"2025-05-30T12:25:00","guid":{"rendered":"https:\/\/handoli.com\/index.php\/2025\/05\/30\/tips-and-tricks-for-when-using-swiftuis-viewbuilder\/"},"modified":"2025-05-30T15:25:00","modified_gmt":"2025-05-30T12:25:00","slug":"tips-and-tricks-for-when-using-swiftuis-viewbuilder","status":"publish","type":"post","link":"https:\/\/handoli.com\/index.php\/2025\/05\/30\/tips-and-tricks-for-when-using-swiftuis-viewbuilder\/","title":{"rendered":"Tips and tricks for when using SwiftUI\u2019s ViewBuilder"},"content":{"rendered":"

SwiftUI\u2019s ViewBuilder<\/code> type is a key part of the library\u2019s overall API design, in that it\u2019s what enables multiple view expressions to be declared within a given scope (such as a body<\/code> property implementation, or a closure passed to containers such as HStack<\/code> or VStack<\/code>) without requiring any manual grouping or wrapping at each call site.<\/p>\n

For example, within the following VStack<\/code>, we can simply place each subview within the closure we pass to it, and ViewBuilder<\/code> will take care of collecting those views and building<\/em> them into the final content that then gets rendered within the stack:<\/p>\n

VStack<\/span> {\n    Image<\/span>(systemName: \"star\"<\/span>)\n    Text<\/span>(\"Hello, world!\"<\/span>)\n}<\/code><\/pre>\n
What\u2019s interesting about ViewBuilder<\/code> is that it\u2019s completely possible to use SwiftUI for a significant amount of time before even discovering that it exists. After all, we don\u2019t have to reference it explicitly in most situations, as SwiftUI\u2019s various closures and protocols have already been annotated with the corresponding @ViewBuilder<\/code> attribute out of the box.<\/p>\n
For example, the View<\/code> protocol that we use every time we want to define a custom view uses ViewBuilder<\/code> implicitly, since the definition for the body<\/code> property requirement looks like this:<\/p>\n
@MainActor @preconcurrency public protocol<\/span> View {\n    associatedtype<\/span> Body : View<\/span>\n\n    @ViewBuilder<\/span> @MainActor @preconcurrency var<\/span> body: Self<\/span>.Body<\/span> { get<\/span> }\n}<\/code><\/pre>\n
That\u2019s what makes it possible to use things like control flow within our view body<\/code> implementations, even when each branch within such a flow returns different types, and even when we don\u2019t explicitly mark our property with @ViewBuilder<\/code> ourselves:<\/p>\n
struct<\/span> RootView: View<\/span> {\n    @State private var<\/span> user: User<\/span>?\n\n    var<\/span> body: some<\/span> View<\/span> {\n        if let<\/span> user {\n            HomeView<\/span>(user: user)\n        } else<\/span> {\n            LoginView<\/span>(user: $user<\/span>)\n        }\n    }\n}<\/code><\/pre>\n
\n
The way our views automatically get annotated with @ViewBuilder<\/code> works the same way as why we don\u2019t have to manually mark our views as @MainActor<\/code> to run them on the main thread \u2014 our custom view types automatically inherit those attributes from the View<\/code> protocol declaration.<\/p>\n<\/blockquote>\n
But there are<\/em> situations in which using ViewBuilder<\/code> directly can be incredibly useful \u2014 so let\u2019s go ahead and explore a few such examples, along with some tips and tricks that can be good to keep in mind when writing that kind of code.<\/p>\n
Custom containers<\/h2>\n
Any property, function, or closure can be marked with the @ViewBuilder<\/code> attribute, which opts that code into getting the same \u201cDSL-like\u201d<\/a><\/em> capabilities as SwiftUI\u2019s built-in APIs. For example, let\u2019s say that we\u2019re building a custom Container<\/code> view, which renders a header<\/code> on top of a content<\/code> view, while also applying some default styling to those two components:<\/p>\n
struct<\/span> Container<Header: View<\/span>, Content: View<\/span>>: View<\/span> {\n    var<\/span> header: Header<\/span>\n    var<\/span> content: Content<\/span>\n\n    var<\/span> body: some<\/span> View<\/span> {\n        VStack<\/span>(spacing: 0<\/span>) {\n            header\n                .frame<\/span>(maxWidth: .infinity<\/span>)\n                .padding<\/span>()\n                .foregroundStyle<\/span>(.white<\/span>)\n                .background<\/span>(Color<\/span>.blue<\/span>)\n\n            ScrollView<\/span> {\n                content.padding<\/span>()\n            }\n        }\n    }\n}<\/code><\/pre>\n
As our Container<\/code> view is currently defined, we\u2019re limited to using just a single view for both the header<\/code> and content<\/code> properties, and we\u2019d pass them just like we\u2019d pass any other Swift initializer values \u2014 for example like this:<\/p>\n
Container<\/span>(header: Text<\/span>(\"Welcome\"<\/span>), content: ContentView<\/span>())<\/code><\/pre>\n
Now, let\u2019s go ahead and mark both header<\/code> and content<\/code> with the @ViewBuilder<\/code> attribute, to see how that affects our view\u2019s API:<\/p>\n
struct<\/span> Container<Header: View<\/span>, Content: View<\/span>>: View<\/span> {\n    @ViewBuilder<\/span> var<\/span> header: Header<\/span>\n    @ViewBuilder<\/span> var<\/span> content: Content<\/span>\n\n    var<\/span> body: some<\/span> View<\/span> {\n        ...\n    }\n}<\/code><\/pre>\n
What\u2019s interesting is that, even though we haven\u2019t redefined either of the above properties as being closures (they still both just store a single view value), their values must now be passed<\/em> as closures when we initialize our Container<\/code> view. ViewBuilder<\/code> will then take any closure that we passed, and apply its view building logic to it, resulting in a single output view, which is then stored within each property.<\/p>\n
What that means is that we\u2019re now able to use the same SwiftUI syntax as when interacting with the library\u2019s built-in APIs when defining either our header<\/code> or content<\/code>. Let\u2019s use that new capability to update our RootView<\/code> from before to use our new Container<\/code> implementation, as we\u2019re now able to use an if<\/code> statement with separate view branches to declare our view\u2019s content<\/code>:<\/p>\n
struct<\/span> RootView: View<\/span> {\n    @State private var<\/span> user: User<\/span>?\n\n    var<\/span> body: some<\/span> View<\/span> {\n        Container<\/span>(header: {\n            Text<\/span>(\"Welcome\"<\/span>)\n        }, content: {\n            if let<\/span> user {\n                HomeView<\/span>(user: user)\n            } else<\/span> {\n                LoginView<\/span>(user: $user<\/span>)\n            }\n        })\n    }\n}<\/code><\/pre>\n
Neat! Next, let\u2019s take a look at how we might handle situations when we want to omit a specific component from a custom container view.<\/p>\n
Making view builder properties optional<\/h2>\n
For example, let\u2019s say that we want to make our Container<\/code> view\u2019s header<\/code> optional. One way to get that done would be to write an extension on Container<\/code> with a generic constraint on SwiftUI\u2019s EmptyView<\/code> type, which allows us to then pass that type\u2019s initializer as a closure when calling our view\u2019s member-wise initializer:<\/p>\n
extension<\/span> Container<\/span> where<\/span> Header<\/span> == EmptyView<\/span> {\n    init<\/span>(@ViewBuilder<\/span> content: () -> Content<\/span>) {\n        self<\/span>.init<\/span>(header: EmptyView<\/span>.init<\/span>, content: content)\n    }\n}<\/code><\/pre>\n
Note that we have to use a closure for our content<\/code> property above, rather than just a Content<\/code> value. That\u2019s because the automatic conversion from view builder closure to single view value that we utilized before only works for stored properties, not for function arguments. Our closure doesn\u2019t need to be @escaping<\/code>, though, since SwiftUI will still evaluate it directly and automatically convert it into a single view, just like when using our view\u2019s member-wise initializer.<\/p>\n
With the above in place, we could now update our RootView<\/code> to no longer use a header, which in turn enables us to use trailing closure syntax to achieve a call site that looks exactly like when using SwiftUI\u2019s built in containers (like HStack<\/code> or VStack<\/code>):<\/p>\n
struct<\/span> RootView: View<\/span> {\n    @State private var<\/span> user: User<\/span>?\n\n    var<\/span> body: some<\/span> View<\/span> {\n        Container<\/span> {\n            if let<\/span> user {\n                HomeView<\/span>(user: user)\n            } else<\/span> {\n                LoginView<\/span>(user: $user<\/span>)\n            }\n        }\n    }\n}<\/code><\/pre>\n
While the above works great, there\u2019s an alternative approach that we can take if we don\u2019t want to define a constrained Container<\/code> extension, but rather just use a custom initializer with default argument values instead.<\/p>\n
What\u2019s cool about using ViewBuilder<\/code> is that, unlike when accepting separate view values directly, the compiler will automatically infer the concrete types for Header<\/code> and Content<\/code> if we use default arguments for their corresponding values.<\/p>\n
So, if we specify EmptyView.init<\/code> as the default value for our header<\/code> property argument, then we can achieve the exact same result as when using the extension-based approach, while also giving us the option to keep adding more default values and convenience APIs in the future \u2014 all without having to define multiple extensions:<\/p>\n
struct<\/span> Container<Header: View<\/span>, Content: View<\/span>>: View<\/span> {\n    var<\/span> header: Header<\/span>\n    var<\/span> content: Content<\/span>\n\n    init<\/span>(@ViewBuilder<\/span> header: () -> Header<\/span> = EmptyView<\/span>.init<\/span>,\n         @ViewBuilder<\/span> content: () -> Content<\/span>) {\n        self<\/span>.header<\/span> = header<\/span>()\n        self<\/span>.content<\/span> = content<\/span>()\n    }\n\n    var<\/span> body: some<\/span> View<\/span> {\n        ...\n    }\n}<\/code><\/pre>\n
Note that we no longer need to add the @ViewBuilder<\/code> attribute to our properties, since we now perform the closure-to-view conversion ourselves (by simply calling those closures within our view\u2019s initializer).<\/p>\n
An alternative approach would\u2019ve been to instead store references to our closures within the header<\/code> and content<\/code> properties, and to then call those closures within our view\u2019s body<\/code>. Doing so wouldn\u2019t make much of a difference in this particular case (besides requiring those closures to be @escaping<\/code>, which most of SwiftUI\u2019s own view builder closures aren\u2019t), however, in some situations, taking that approach can significantly hurt performance \u2014 since we\u2019ll end up re-evaluating those closures every time our view\u2019s body<\/code> gets re-evaluated. So, when possible, resolving each view builder closure up-front gives us the most predictable and consistent results.<\/p>\n
Handling multiple view expressions<\/h2>\n
Just like when using SwiftUI\u2019s built-in containers, it\u2019s also now possible to place multiple view expressions within either our header<\/code> or content<\/code> closures. For example, if we bring back the header within our RootView<\/code>, we might use this capability to add a NavigationLink<\/code> below our welcome text \u2014 like this:<\/p>\n
struct<\/span> RootView: View<\/span> {\n    ...\n\n    var<\/span> body: some<\/span> View<\/span> {\n        Container<\/span>(header: {\n            Text<\/span>(\"Welcome\"<\/span>)\n            NavigationLink<\/span>(\"Info\"<\/span>) {\n                InfoView<\/span>()\n            }\n        }, content: {\n            ...\n        })\n    }\n}<\/code><\/pre>\n
However, call sites like the one above might not always produce the result we\u2019d expect, since when processed by ViewBuilder<\/code>, multiple view expressions will essentially be treated the same way as if they were added to a SwiftUI Group<\/code> \u2014 in that they\u2019ll each be independently styled, sized, and positioned according to the current context.<\/p>\n
So, in the above example, we\u2019re not actually adding a combined header<\/em> to our view, but rather two separate headers<\/em> \u2014 each with its own layout within the enclosing VStack<\/code>, and each with its own set of modifiers applied to it.<\/p>\n
To resolve that, it might be a good idea to wrap both our header<\/code> and content<\/code> views within explicit containers, so that their layout will always be predictable, even when multiple view expressions are used at a specific call site:<\/p>\n
struct<\/span> Container<Header: View<\/span>, Content: View<\/span>>: View<\/span> {\n    ...\n\n    var<\/span> body: some<\/span> View<\/span> {\n        VStack<\/span>(spacing: 0<\/span>) {\n            VStack<\/span> { header }\n                .frame<\/span>(maxWidth: .infinity<\/span>)\n                .padding<\/span>()\n                .foregroundStyle<\/span>(.white<\/span>)\n                .background<\/span>(Color<\/span>.blue<\/span>)\n\n            ScrollView<\/span> {\n                VStack<\/span> { content }\n                    .padding<\/span>()\n            }\n        }\n    }\n}<\/code><\/pre>\n
Whether to take the above approach (and enforce a specific layout within the container in question), or leave it up to each call site to define its own layout, will likely come down to a combination of personal\/team preference and the specific container (and layout behaviors) that we\u2019re implementing.<\/p>\n
There are cases, though, where it\u2019s arguably best to add an explicit container at the call site, in order to make our code more clear and easier to maintain. For example, here we\u2019re using @ViewBuilder<\/code> as a sort of code organization tool, in that we\u2019re applying it to private functions that we\u2019re using to build separate parts of our view \u2014 which in general is a really great way to structure increasingly complex SwiftUI view implementations, rather than allowing our body<\/code> properties to grow too large in scope:<\/p>\n
struct<\/span> RootView: View<\/span> {\n    @State private var<\/span> user: User<\/span>?\n\n    var<\/span> body: some<\/span> View<\/span> {\n        Container<\/span>(header: header, content: content)\n    }\n}\n\nprivate extension<\/span> RootView<\/span> {\n    @ViewBuilder func<\/span> header() -> some<\/span> View<\/span> {\n        Text<\/span>(\"Welcome\"<\/span>)\n        NavigationLink<\/span>(\"Info\"<\/span>) {\n            InfoView<\/span>()\n        }\n    }\n\n    @ViewBuilder func<\/span> content() -> some<\/span> View<\/span> {\n        if let<\/span> user {\n            HomeView<\/span>(user: user)\n        } else<\/span> {\n            LoginView<\/span>(user: $user<\/span>)\n        }\n    }\n}<\/code><\/pre>\n
However, while our above code is now very neatly organized, the semantics of our new header<\/code> function are arguably a bit odd \u2014 since it doesn\u2019t really return a header<\/em>, but rather multiple view expressions that will be built into a header<\/em>. It might be a nitpicky detail in the grand scheme of things, but aiming to write code to be as clear as possible does often really help when it comes to future maintainability.<\/p>\n
A rule of thumb that can be good to follow is that a function or computed property should never return multiple root view expressions (since that gives us an implicit group, just like before). Instead, it would arguably be better if our header<\/code> function didn\u2019t actually use ViewBuilder<\/code>, but rather just returned an explicit VStack<\/code> which in turn contains our header view\u2019s content. That way, it\u2019ll become crystal clear how our header will be rendered, even if we end up changing how our Container<\/code> view works in the future:<\/p>\n
private extension<\/span> RootView<\/span> {\n    func<\/span> header() -> some<\/span> View<\/span> {\n        VStack<\/span>(spacing: 20<\/span>) {\n            Text<\/span>(\"Welcome\"<\/span>)\n            NavigationLink<\/span>(\"Info\"<\/span>) {\n                InfoView<\/span>()\n            }\n        }\n    }\n\n    @ViewBuilder func<\/span> content() -> some<\/span> View<\/span> {\n        if let<\/span> user {\n            HomeView<\/span>(user: user)\n        } else<\/span> {\n            LoginView<\/span>(user: $user<\/span>)\n        }\n    }\n}<\/code><\/pre>\n
We still want to keep using @ViewBuilder<\/code> for our content<\/code> function, though, since it returns just a single (albeit conditional) root view expression.<\/p>\n
Conclusion<\/h2>\n
SwiftUI\u2019s ViewBuilder<\/code> is a really powerful tool, and the fact that we can opt our own code into using it gives us a lot of flexibility when it comes to how we want to structure and reuse our UI code. By adopting it within our own custom containers, we can really craft APIs that feel right at home alongside SwiftUI\u2019s own features, which in turn should help us improve the consistency and clarity of the UI code that we write.<\/p>\n
I hope you enjoyed this article. If you have any questions, comments, or feedback, then feel free to reach out via either Mastodon<\/a> or Bluesky<\/a>.<\/p>\n
Thanks for reading!<\/p>","protected":false},"excerpt":{"rendered":"
SwiftUI\u2019s ViewBuilder type is a key part of the library\u2019s overall API design, in that it\u2019s what enables multiple view expressions to be declared within a given scope (such as a body property implementation, or a closure passed to containers such as HStack or VStack) without requiring any manual grouping or wrapping at each call […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rop_custom_images_group":[],"rop_custom_messages_group":[],"rop_publish_now":"initial","rop_publish_now_accounts":[],"rop_publish_now_history":[],"rop_publish_now_status":"pending","footnotes":""},"categories":[1,15],"tags":[],"class_list":["post-9736","post","type-post","status-publish","format-standard","hentry","category-explore","category-world"],"_links":{"self":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts\/9736","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/comments?post=9736"}],"version-history":[{"count":0,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts\/9736\/revisions"}],"wp:attachment":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/media?parent=9736"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/categories?post=9736"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/tags?post=9736"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}