LocalizedStringResource vs LocalizedStringKey vs String

Deciding how to pass around localized strings in Swift

I’ve recently been re-reviewing the strings catalog WWDC video as part of both a localization talk at iOSDevUK and researching a migration from the legacy NSLocalizedString.

In the video, I came across this statement from Apple:

LocalizedStringResource is the recommended type for representing and passing around localizable strings.

The implications here feel massive. Most strings in a localized app are strings that are displayed to the user and therefore require localization. Is Apple recommending that we should be replacing most of our use of String with LocalizedStringResource? And, for a change as big as this, I would like more details and clear benefits.

Apple doesn’t answer this. So I tried to answer this question myself and that research took me down a couple of unexpected paths which we will get into shortly.

Firstly though let's start with a simple UI component with a simple String input type. I'm trying to represent something typical here but simplified. If the string should always be localized, is there a better way of enforcing or indicating this expectation?

struct MyView: View {
  let input: String
  var body: some View {
    Text(input)
  }
}

// Somewhere else
let view = MyView(input: "some thing")

LocalizedStringKey

Before LocalizedStringResource (which became available in iOS 16) there was LocalizedStringKey. This type has been deeply integrated with SwiftUI from the beginning, implicitly being used as the default type in many components and modifiers:

Text(“a key”)
TextView("a key", text: $text)
Toggle("a key", isOn: $isOn)
SomeView().navigationTitle("a key")

These components each have equivalent StringProtocol pairs where a String can be passed in instead of a StringLocalizedKey but for literals as above StringLocalizedKey is the default type because of @_disfavoredOverload on the String initializer. (Note — don't do this in your code - Apple would prefer you didn't. See here.)

So let's update our UI component:

struct MyView: View {
  let input: LocalizedStringKey
  var body: some View {
    Text(input)
  }
}

// Somewhere else
let view = MyView(input: "a key")

This seems to work — “a key” is extracted during build-time into a string catalog (if you have one) and a look-up is done to find a translation at run time. It feels more type-safe than a string and works well with SwiftUI.

However, there are limitations here. To understand more, we have to delve into keys, default values, comments, and bundles.

Keys, Default Values and Comments

Apple is fond of showing how easy it is to localize:

Text(“I am localization ready”)

And it’s true, Apple made SwiftUI with localization top of mind. However, there are limitations to the approach of using the default language as the key in localization. Words used in different contexts can have different translations (e.g. the word “book” — see here) and translation processes work more accurately when the context is uniquely identified.

Thus, it is common to create a keying format along the lines of [flow].[screen].[element].[usage] (example: login.password_entry.password.label for a login flow's password label). A comment can also be added to help give the translator additional context:

Text(“login.password_entry_password.label”, comment: “a short label for the password data entry field”)

In this case, we would have to add the default language value of the key in the strings catalog directly after this string is extracted. Unfortunately, this requires context-switching while coding, something I’d rather avoid.

It’s also important to note that if we added a comment to our UI component above, the comment would be completely ignored by the extraction process which is not immediately apparent:

struct MyView: View {
  let input: LocalizedStringKey
  var body: some View {
    Text(input, comment: "this is not picked up by extraction")
  }
}

Bundle

Bundle is one of the optional parameters of Text - the default is .main . Why do we need a bundle? In all but simple code bases, the preferred approach is to separate code into modules - preferably using Swift Package Manager. Each module has its own string catalog (and bundle) - we use the.module bundle. String extraction, export/import, and run-time lookup all work accordingly.

In the case of our UI component above, we will have a problem. If the calling code is a module (that is not the main target) and the component is in yet another module — the run-time localization lookup will fail. The process needs to know which bundle so simply passing a key isn’t enough.

Strings that are already localized

A common example here is backend strings that in most applications are translated before being sent to the app. Trying to pass in a String from a backend model into a component that requires a LocalizedStringKey will force an error. Other than creating dual initializers for the component, the solution would :

MyView(input: LocalizedStringKey(stringLiteral: myBackendString))

However, it should be noted that the run-time localization look-up will still be attempted even though the string is already localized which probably would not cause issues, but it’s worth noting. I could not find a way of avoiding this.

LocalizedStringKey — Summary

✅ SwiftUI integration
✅ Stronger typing than String
❌ Doesn’t allow in-line default value
❌ Comment and table disconnected from key and sometimes ignored
❌ Module boundary issues
❌ Awkward for backend strings (require conversion, will still do look-up)

LocalizedStringResource

So now let’s look at what Apple seems to recommend. LocalizedStringResource has been available since iOS 16 and in many ways solves the limitations of LocalizedStringKey but grouping the key, the default value, the bundle, and the comment into one.

struct MyView: View {
  let input: LocalizedStringResource
  var body: some View {
    Text(input)
  }
}

// Somewhere else or some other module
let localizedStringResource = LocalizedStringResource(
    "login.password_entry_password.label",
    defaultValue: "Password",
    comment: "a short label for the password data entry field",
    bundle: .atURL(Bundle.module.bundleURL)
)
let view = MyView(input: localizedStringResource)

This grouping of all important localization information into one type seems to solve all previous issues around modularization, having to context switch to add default language directly in the catalog and comments being ignored.

It’s also safe like LocalizedStringKey - you can't accidentally pass in a non-localized String.

However, it also doesn’t handle already-localized backend strings well and there are some additional concerns to think about:

SwiftUI Support

LocalizedStringResource is supported in SwiftUI but it's somewhat limited and for some components, an extra step is required either using Text or String(localized:) as an intermediate:

Text(myLocalizedStringResource)
Toggle(String(localized: myLocalizedStringResource), isOn: $isOn)
SomeView().navigationTitle(Text(myLocalizedStringResource))

Deferred lookup and language choice

There’s a broader story for LocalizedStringResource and that's the need to be able to pass in localized strings into a separate process that may not be running in the same locale context as the main app. App intents are a good example of this and there's explicit reference to this in the documentation.

This feels like a somewhat niche usage but it also has an implication when used more broadly that doesn’t appear to be documented by Apple.

To understand this better, we need to look at how language choice is made by iOS for a specific app. Essentially it compares the app languages available to the preferred languages as shown below:

You can see the result of this in the settings for the app (which can then be overidden by the user). In this case, the app language would be French as this is the first language on the preferred list that is also supported by the app, and this is what is generally used for language look-up at runtime.

However, LocalizedStringResource appears to operate differently. It appears to use the current locale as a substitute for language. In most simpler cases this does not make a difference - e.g. the user has only French in their preferred language choice. But in the case above the current locale of the user in the app is es_US not French. It will fail that look-up and so default to English.

Current locale is not the same as preferred language.

And unless you manually inject Bundle.main.preferredLocalizations into the locale of LocalizedStringResource, it will also ignore any app-level manually overridden language choice. This feels problematic.

(And note — to test this out use a real device not the simulator.)

LocalizedStringResource — Summary

✅ Stronger typing than String
✅ Handles in-line default values
✅ Comment and table grouped with key
✅ Modular code
❌ Not fully integrated with SwiftUI
❌ Awkward for backend strings (require conversion, will still do look-up)
❌ Sometimes language look-up doesn’t match the general approach

String with String(localized:)

Considering the limitations of LocalizedStringKey and LocalizedStringResource we could continue to use String using String(localized:) directly before calling the UI Component. This string initializer is a replacement for the legacy NSLocalizedString.

Our example would be:

struct MyView: View {
  let input: LocalizedStringKey
  var body: some View {
    Text(input)
   }
}

// Somewhere else or some other module
let string = String(
    localized: "login.password_entry_password.label",
    defaultValue: "Password",
    comment: "a short label for the password data entry field",
    bundle: .module
)
let view = MyView(input: string)

This approach removes all the limitations — integrates well with SwiftUI, works cleanly with modularization, comments, in-line default values, and has a consistent language look-up.

The one downside is — of course — this approach isn’t as perhaps as safe as we want. Strings that have not been localized can be passed in and the compiler will not catch it.

String + String(localized:) — Summary

❌ Does not ensure localization
✅ Integrated with SwiftUI
✅ Handles in-line default values
✅ Comment and table grouped with key
✅ Modular code
✅ Backend strings
✅ Language look-up

Conclusion

In this article, I’ve tried to give you reasons for each choice so you can make your own decision. You may well have a simpler app that does not use modules and LocalizedStringKey will work for you. Or maybe you like the power of LocalizedStringResourceand its type-safety and aren't concerned about its limitations.

I’m overall concerned, however, with Apple’s recommendation made without full context. Both modularization and the need for consistent language look-up would make it difficult for me to recommend anything other than continuing to use String in the majority of cases. Would be great to have a version of LocalizedStringResource that would do language look-up consistently.

I have a caveat though. For every app codebase I’ve looked at, there always seems to be a unique approach to localization. Would love to hear your thoughts.

iOS Localization: LocalizedStringResource vs LocalizedStringKey vs String was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

WWDC 2023 introduced us to the new iOS-17@Observable property wrapper along with a cleaned-up @State that now supersedes the previous @State @ObservedObject, @StateObject. This is fantastic — it’s always been a source of confusion for those starting on SwiftUI and a source of bugs (with various recommendations on what to use and when).

All this feels like it’s gone and we are left with the simple choice of @Environment, @State, and @Bindable with clean usage (in order: app-wide, view-wide, and binding to a parent). Love it!

Let’s take a quick look at how this works. You’ll notice that tapping the button triggers a screen refresh to display the new value of myString. You also no longer need @Published. Fantastic!

import SwiftUI
import Observation

@Observable
class Model {
    var myString: String = "Hello"
}

struct ContentView: View {
    @State var model: Model

    var body: some View {
        VStack {
            Text("myString: \(model.myString)")
            Button("Hit me") {
                model.myString = "new"                
            }
        }
    }
}

Macros appear to be the driver — so is this simply a string replacement of the old approach? Well, by digging deeper and using the new “expand macro” option in Xcode we can start to see what is going on:

Well, this is different! Digging further we see that Observable is a protocol in the Observation framework — which is brand new. We had to import this framework so perhaps this isn’t a shock. The previous ObservableObject was actually part of Combine and this one looks similar. Additionally, the new @Model also uses this.

There is a hint in the WWDC video Discover Observation in SwiftUI — WWDC23 — Videos — Apple Developer which suggests something more. In the video, it discusses the observability of arrays which leads me to ponder the existing issue of nested objects in observables which has a variety of solutions and perhaps even the suggestion of an anti-pattern.

Here’s an example of where the previous approach didn’t work. Tapping the button here would not have the intended effect of triggering a view refresh as the Model object itself never changed (only an object being referenced by the Model). The array of references itself remains unchanged and therefore a change event is never triggered.

import Combine
import SwiftUI

class Model: ObservableObject {
    @Published var str = "Outer"
    @Published var innerModels: [InnerModel] = [InnerModel(), InnerModel(), InnerModel()]
}

class InnerModel {
    @Published var str = "inner"
}

struct ContentView: View {
    @ObservedObject var model: Model
    var body: some View {
        VStack {
            List(model.array, id: \.id) { element in
                Text(element.str)
            }
            Button("Hit me") {
                model.innerModels[1].str = "KABOOM"
            }
        }
        .padding()
    }
}

There is a solution to the above — switch the inner model to using structs and the problem is solved but value semantics may not be desired.

The hint in the WWDC that the new approach works for arrays too suggests that this problem has been solved. Let’s take a look:

import SwiftUI
import Observation

@Observable class Model {
    var innerModels: [InnerModel] = [InnerModel(), InnerModel(), InnerModel()]
}

@Observable class InnerModel: Identifiable {
    var str = "inner"
}

struct ContentView: View {
    @State var model = Model()

    var body: some View {
        VStack {
            List($model.innerModels, id: \.id) { element in
                Text(element.str.wrappedValue)
            }
            Button("Hit me") {
                model.innerModels[1].str = "KABOOM"
            }
        }
    }
}

And you’ll discover that it has!! This is great — allows us to think a lot less about code “plumbing” — it just works!! (Caveat — still early days in testing this!)

So what is the secret sauce?

The driver behind the Observation framework is the ability to detect a change in the properties contained in a closure of a new function called withObservationTracking.

For example:

func testObservation() {
    withObservationTracking {
        print(model.inner[1].str)
    } onChange: {
        print("Schedule renderer.")
    }
}

The onChange closure is only called when specifically model.inner[1].str has changed. Changing other properties on the model or other objects in the array or even other properties on model.inner[1]does nothing. That is magical! And could this be useful outside the explicit SwiftUI usage?

Please refer to the Observation Framework documentation for more details.

Side note, now that we don’t need @Published — everything automatically updates — perhaps there are cases where you don’t want a property to trigger updates. The new ObservationIgnored can be used for particular properties that should not be observed:

@Observable
class Model {
    @ObservationIgnored var myString: String = "Hello"
    var innerModels: [InnerModel] = [InnerModel(), InnerModel(), InnerModel()]
}

For those of us lucky enough to be able to target iOS 17 in our projects — happy coding! For the rest of us, the specific iOS 17 target means we’ll have to wait to use this magic.

iOS 17 @Observable and the Observation Framework was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

Having just revisited this navigation for SwiftUI 3 here (which updated the original approach for SwiftUI 1 here), Apple has since rethought navigation with the new NavigationStack as part of the latest SwiftUI 4 release. This is great news… and covers most of my previous suggestions!

Previously, NavigationView required explicitly defining navigation “edges” and the use of multiple flags which could lead to confusion. The new approach uses a stack creating a non-UI representation of the existing navigation and works beautifully with our previous programmatic approach without many changes.

This approach initially started with a review of a multiscreen onboarding flow with SwiftUI. As with all multiscreen data entry flows, they often represent an interesting problem of how to decouple data, view, and navigation logic.

So, what makes a great multiscreen data entry flow? Here’s what I came up with. For want of a less grand term, I’ll call it my “screen flow manifesto.” I use the “screen” here rather than view because we are explicitly referring to whole-screen navigation.

1. Screens should have no “parent” knowledge nor be responsible for navigating in or out.
2. Individual view models for every screen.
3. Overall flow control logic is separate from UI implementation and is testable without UI.
4. Flexible and allow for branching to different screens in the flow.
5. As simple as possible but composable and scalable.

Navigation Requirement

So onboarding may be simple, perhaps two or three screens asking the user some simple personal information. A “next” button would move the user forward in the flow.

However, what’s usually more typical is a more complex flow with branching. Maybe the user isn’t ready to share all those details yet or perhaps more details are needed depending on previous responses. So, maybe this is more representative:

Initial Implementation

As mentioned previously, we will be using NavigationStack. This can be bound (2-way binding) to a navigation path. In our first implementation with just a 3-screen flow, we are going to useNavigationPath() which is a type-erased sequence. We will add the navigation path to a navigation-focused view model and pass this around (more later).

Within NavigationStack we define a root view (in our case a VStack with text and a button). This also contains navigation destination modifiers that trigger the actual navigation. Any appending to the navigation path will point SwiftUI to the appropriate new view for the new screen based on the type and execute a push animation.

In this implementation, we use a view model called FlowVM that controls the navigation flow (different from screen view models). This view model contains the navigation path allowing us to trigger the actual navigation outside of the views (manifesto points 1 and 3).

In our example, adding an integer to the navigation path will push aContentView2 to the stack, and adding a string to the path will push a ContentView3. Now simple manipulation of only the navigation path (which is a sequence) will directly affect navigation giving us full programmatic control. Here lies the beauty (and covers manifesto point 4)!

1. Push: Append a particular type.
2. Back to root: Reinitialize the navigation path.
3. Back 1 screen: Remove the last value.

We can also go back to multiple screens withremoveLast(x).

You’ll also note we no longer need to useNavigationLink at all. NavigationLink is still an available option in SwiftUI 4 but its main use is in view-to-view navigation — something we want to avoid here!

View Models and Binding

On to manifesto point 2 — separate view models for each screen. Usage and implementation of view models may differ here and I’ve heard concerns about the overuse of the MVVM design pattern in SwiftUI. It certainly isn’t a term used in anything official from Apple.

What I want is a non-UI representation of the view so I can cleanly encapsulate non-UI logic, unit test it without the view, and of course, easily bind to the view (both ways). It also should be specific to the view so the view can be moved around and is not dependent on anything external (i.e., composable — manifesto point 5). It is the interface of the view to the rest of the application. I call this a view model.

Within SwiftUIObservableObject (which is actually part of Combine) makes for a good view model that enables two-way view binding. The newer approach with @StateObject creates a stable view model which is lazily loaded only when needed.

Note also that in this version of a view model, UI events are also passed into the view model from the view, and any view-specific logic (e.g., network calls) may be triggered from there (usually calling down to an API layer for example).

We also have the flow view model (FlowVM) to manage the screen-to-screen navigation. It does not know the views and is designed to be testable. It itself may require API calls to determine the path to follow. Note this is similar to a “coordinator” but to me is considered a model of the navigation and therefore I’ve used the term “view model.”

Each screen then also has individual view models as well. These screen view models handle the UI events and screen logic. Ultimately (upon completion of all screen logic after a “next” tap for example), we pass the control back from the screen view models to the flow view model to ultimately decide on where to navigate.

For completion, eventing back from the screen view models back “up” to the flow view model, we can use a variety of techniques. Delegates and call-backs are all valid implementations but I like to use Combine’s PassthroughSubject passing back a reference to the screen view model itself.

So the screen view model and the view would like something like this:

And wired in the flow view model to listen to the completion events as follows using a sink and storing that in a subscription. You’ll notice the factory function to create the screen view model is handled here which also added the event listening. This factory function is called by the flow view in screen view initialization.

The sink calls a method directly to handle any logic (and navigation) and stores the subscription in a set attached to the view model (which can be used for all subscriptions).

Bringing It Together

In our first implementation of the navigation stack, we used NavigationPath and rather non-sensical types (integers and strings) to drive the navigation. As each screen is now represented with a view model we can actually drive the navigation by adding the view models themselves to the path.

We could add the view models directly to NavigationPath and create multiple navigation destination modifiers for each view model type. However, this type erased sequence offers only limited inquiry capability (for example — cannot easily inquire on what screen is currently shown).

Instead, we can bind the navigation stack to a simple enum array that contains an associated value of the view model. Now the path is an array we have maximum control and introspection of its current state. The only requirement here is that the array is Hashable, which in turn requires the view models to be Hashable. A little extra work here, but straightforward.

Check out the repo for full code. This also includes examples of backward navigation (including back to root or screen two, etc) and Hashable conformance.

The “maximum control” also allows us to handle some interesting situations that I don’t recall being able to do in UIKit. You can change a previous screen to be something else entirely (navigationPath[0] = ... ) and now the back button goes to a different screen. Or weirdly removing a screen previous screen deeper in the stack (e.g. navigationPath.removeFirst() ). This will programmatically navigate backward with the first screen removed from the stack. Perhaps the last one is non-sensical but I like the way SwiftUI worked as I expected even in these odd situations. Well done Apple!

Testing

A big part of our design is to improve testability and allow for unit tests of the navigation flow independent of the UI (manifesto point 3). Now with view models, this is easily done. Here’s an example:

We are able to trigger a “next” button tap and then check the navigation logic has been triggered — all without actual UI.

Note though this is obviously a simple implementation. If the view models had API calls, we would have to think about some injection to mock those out. In addition, this is obviously not a UI test.

We may also want to add some UI tests (perhaps using snapshot testing) — but this is beyond the scope of this article.

And Finally…

I hope this has made sense! After 4 versions, this iteration of SwiftUI’s push navigation is the approach we’ve been looking for. This should now have answered most of the concerns of the community at large (as well as my previous suggestions here).

Any improvements? Right now, there is no obvious path to creating custom push navigation. An additional larger thought is to create a single, converged navigation API for both push and modal navigation. Apple — your clock starts now! 😁

The full code can be found at https://github.com/nickm01/NavigationFlow. Enjoy!

Flow Navigation With SwiftUI 4 was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

How to implement screen flow navigation effectively in your code bases

[Note for implementation with SwiftUI 4 and NavigationStack see here]

This is a revisit of a previous couple of articles on creating a decoupled navigation flow (part 1 and part 2) which related to the original SwiftUI 1.0. Times have changed and SwiftUI (3.0), NavigationView, and my own perspective are now different (and simpler!) so thought it was worthwhile re-evaluating.

I’ve recently been reviewing my multiscreen onboarding flow with SwiftUI. As with all multiscreen data entry flows, they often represent an interesting problem of how to decouple data, view, and navigation logic.

So, what makes a great multiscreen data entry flow? Here’s what I came up with. For want of a less grand term, I’ll call it my “screen flow manifesto.” I use the “screen” here rather than view because we are explicitly referring to whole-screen navigation.

1. Screens should have no “parent” knowledge nor be responsible for navigating in or out.
2. Individual view models for every screen.
3. Overall flow control logic is separate from UI implementation and is testable without UI.
4. Flexible and allow for branching to different screens in the flow.
5. As simple as possible but composable and scalable.

Navigation

So onboarding may be simple, perhaps two or three screens asking the user some simple personal information. A “next” button would move the user forward in the flow.

However, what's usually more typical is a more complex flow with branching. Maybe the user isn’t ready to share all those details yet or perhaps more details are needed depending on previous responses. So, maybe this is more representative:

Obviously, any solution would need to handle any combination of the above and, as per manifesto point 1 to do so outside of the screens themselves. It should also be noted that we probably want to do some data look up at the end of each screen’s entry as we don’t want the view itself to control navigation (manifesto point 3).

As we are in the world of SwiftUI, I propose using the power of @ViewBuilder. This is the “meat” inside the SwiftUI view’s body. ViewBuilders are a powerful way of generating complex generic types — which is what is behind the declarative nature of SwiftUI (but is beyond the scope of this article).

So what could that look like? Well, a good start is SwiftUI’s equivalent of UINavigationController which is NavigationView. In this, we add a ViewBuilder equivalent of a tree structure to represent the navigation nodes and edges:

OK, so this really is pseudocode. Full disclosure — it ain’t that simple 😀.

This is still “declarative,” in the sense that it’s predefined rather than completely programmatic but dynamic where the paths are driven by programming logic. You still require each navigation “edge” to be defined up-front. If your flows are completely dynamic with no particular set paths, then perhaps this isn’t the approach for you.

With that said, let’s try and get a close implementation of this approach. Using the embedded types we can create a good declarative definition of the branching flow diagram from above. It satisfies manifesto point 1 and perhaps point 5. So, let’s see if we can implement something like this.

NavigationView pairs with NavigationLink to give us the ability to do “traditional” push navigation. There are a few variations of use, but I honed in on the fully-programmatic variation:

NavigationLink(destination: Destination, isActive: Binding<Bool>) { Label }

After some experimentation here (and frustration with the lack of documentation), here is a list of considerations for using NavigationLink:

1. Needs to be embedded in a grouping such as a VStack.
2. The Label is typically Text if we want a simple active link to control navigation. However, in our case, we do not want the view of external programmatic control of navigation so we use EmptyView.
3. You can easily go wrong with the binding. If you want external control of navigation (and we do), using the newer@StateObject (rather than @ObservedObject — see below) with flags for each navigation works nicely.
4. I disliked the order. To me, the trigger for navigation reads better if it’s before the destination.

This resulted in an improved encapsulation of NavigationLink:

This encapsulates some of the complexity of NavigationLink usage. We can pass in a bound flag to allow us to externally control navigation. The plumbing work of needing to use VStack and EmptyView is done for us. It also makes use of @ViewBuilder to make a variation of NavigationLink that reads better.

Let’s see it in action for a simple three-screen flow. We’ve introduced an observable object to encapsulate the navigation flags (more to follow). Here’s the code:

Screens 1 and 2 both contain three types: AText to display the screen name, the Button for the next action, and a Flow for the navigation. We store the flow state for each navigation and internal functions perform the actual navigation (didTapNext1 etc).

This works but perhaps is overkill if the next buttons themselves directly do the navigation. Other forms of NavigationLink can fill that role just as well perhaps. However, as part of manifesto part 3, we want our navigation to be controlled externally from views.

It should be noted that navigation should be activated based on the currently active screen — setting navigateTo3 to true when the user is on screen 3 will cause some “odd” results (it does navigate but instantly, without animation).

Backward navigation to a previous screen (including root) can be achieved by setting the flag that originally moved the user away from this destination screen to false. In the case above for programmatically going back to screen 1 from screen 2, by setting navigateTo2 = false.

Note: A new feature in iOS 15 allows you to use @Environment(\.dismiss). However, this simply goes back one screen and does not allow for a larger backward jump (or pop to root). Using the activation flags allows for more complete control.

View Models and Binding

On to manifesto point 2 — separate view models for each screen. Usage and implementation of view models may differ here and I’ve heard concerns about the overuse of the MVVM design pattern in SwiftUI. It certainly isn’t a term used in anything official from Apple.

What I want is a non-UI representation of the view so I can cleanly encapsulate non-UI logic, unit test it without the view, and of course, easily bind to the view (both ways). It also should be specific to the View so the View can be moved around and is not dependent on anything external (i.e., composable — manifesto point 5). It is the interface of the view to the rest of the application. I call this a view model.

Within SwiftUIObservableObject (which is actually part of Combine) makes for a good view model that enables two-way view binding. Using @ObservedObject in the View itself, however, can be problematic and cause unnecessary view model recreation. The newer approach with @StateObject creates a stable view model which is lazily loaded only when needed. This is a large and important improvement on the old approach where a workaround was used.

Note also that in this version of a view model, UI events are also passed into the view model from the view, and any view-specific logic (e.g., network calls) may be triggered from there (usually calling down to an API layer for example).

To model this out, we have a flow view model (FlowVM) to manage the screen-to-screen navigation. It does not know the views and is designed to be testable. It itself may require API calls to determine the path to follow. This is similar to a “coordinator” but to me is considered a model of the navigation and therefore I’ve used the term “view model.”

Each screen then also has individual view models as well. These screen view models handle the UI events and screen logic. Ultimately (upon completion of all screen logic after a “next” tap for example), we pass the control back from the screen view models to the flow view model to ultimately decide on where to navigate.

For completion, eventing back from the screen view models back “up” to the flow view model, we can use a variety of techniques. Delegates and call-backs are all valid implementations but I like to use Combine’s PassthroughSubject passing back a reference to the screen view model itself.

So the screen view model and the view would like something like this:

And wired in the flow view model to listen to the completion events as follows using a sink and storing that in a subscription. You’ll notice the factory function to create the screen view model is handled here which also added the event listening. This factory function is called by the flow view in screen view initialization.

The sink calls a method directly to handle any logic (which, in this case, is just simply setting the navigate flag) and stores the subscription in aSet attached to the vm (which can be used for all subscriptions).

Bringing It Together

Let’s see how that looks in totality, after adding in our five-screen branched flow. You’ll notice there is a separate navigation flag for each navigation edge. You will also note that the screen 3 view model would require two didTap() functions and two PassthroughSubjects to handle the branched logic.

Check out the repo for full code. This also includes examples of backward navigation (including back to root or screen two, etc).

Testing

A big part of our design is to improve testability and allow for unit tests of the navigation flow independent of the UI (manifesto point 3). Now with view models, this is easily done. Here’s an example:

We are able to trigger a “next” button tap and then check the navigation logic has been triggered — all without actual UI.

Note though this is obviously a simple implementation. If the view models had API calls, we would have to think about some injection to mock those out. In addition, this is obviously not a UI test.

We may also want to add some UI tests (perhaps using snapshot testing) — but this is beyond the scope of this article.

And Finally…

I hope this has made sense! It’s definitely been a journey trying to make sense of how to use navigation, and I’m happy to share. The navigation has improved recently, and I do hope Apple continues to improve it. Here are some suggestions:

1. There are too many ways to make mistakes with navigation when it’s beyond the simple case — and too little documentation. For example, using @ObservedObject, using the wrong activation flag at the wrong time, etc. I see this in the number of posts and custom libraries out there.
2. Allow navigation in a way that not every navigation edge has to be specified and handled from the correct screen, but rather just a way of declaring the navigation to a screen from any screen.
3. Create a simpler API for backward navigation (pop to root, etc).
4. Rather than UIKit being more flexible (e.g., custom push navigation animations, etc.), make SwiftUI navigation at least as flexible… and, perhaps, even better.

The full code can be found at https://github.com/nickm01/NavigationFlow/tree/swiftui3.

Flow Navigation With SwiftUI (Revisited) was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

[Note this was been reworked for SwiftUI release 3 — see update]

In part 1, we looked at the navigation structure needed to support a multi-screen data entry flow with branching which typical to but not limited to a user onboarding flow. We partially succeeded in satisfying our “screen flow manifesto” and in this final part we look to completing that with introduction of ViewModels.

As part of point 2 of the manifesto our goal is to have isolated ViewModels for each screen in the flow. SwiftUI works very cleanly with ViewModels giving us 2-way binding with OberservableObject. Overall though, how do we want to structure the generation and usage of ViewModels? There are many ways to implement the MVVM design pattern, but for this case I like to think in these terms:

1. ViewModel acts as a simple non-UI data interface to the View. Generally contains only limited business logic — e.g. simple validation etc.
2. We have a single model (“the Model”) as our overall data store which is persistent across screens.
3. ViewModels can be generated from the Model and can also update the Model.
4. Because this is data entry which means updating data, ViewModels and the Model are more naturally as classes rather than structs.
5. We will use our FlowController to orchestrate where necessary.

So visually this could look like:

So a screen with it’s paired ViewModel would generically look like this:

class Screen1VM: ObservableObject {
    @Published var detail1 = ""
    @Published var detail2 = ""
}

struct Screen1: View {
    @ObservedObject var vm: Screen1VM
    let didTapNext: () -> ()

    var body: some View {
        VStack(alignment: .center) {
            Text("Please enter details")
            TextField("Detail1", text: $vm.detail1)
                .textFieldStyle(RoundedBorderTextFieldStyle())
            TextField("Detail2", text: $vm.detail2)
                .textFieldStyle(RoundedBorderTextFieldStyle())                 
            Button(
                action: { self.didTapNext() },
                label: { Text("Next") }
            )
        }
    }
}

All well and good but how to we generate the ViewModel and pass the ViewModel back through the Controller to potentially update the main Model? Both actions can be handled by the FlowControllerView delegating to the FlowController.

Firstly, we update the can pass the ViewMode through the didTapNext function so the above becomes:

struct Screen1: View {
    @ObservedObject var vm: Screen1VM
    let didTapNext: (Screen1VM) -> ()

    var body: some View {
            ...
            Button(
                action: { self.didTapNext(self.vm) },
                label: { Text("Next") }
            )
            ...

FlowControllerView and it’s delegate now need to accept a screen-specific didTapNext and a new function to generate the ViewModel.

protocol FlowControllerViewDelegate: class {
    ...
    func didTapNext(vm: Screen1VM)
    ...
}

struct FlowControllerView: View {
    ...
    var body: some View {
        NavigationView {
            VStack() {
                Screen1Phone(
                    vm: self.delegate.make(),
                    didTapNext: self.delegate.didTapNext
                )
                Flow(state: navigateTo2) {
                    ...
                }
           ...

The 2 new delegate functions are implemented by FlowController. These ultimately require the overall, persistent Model which is owned by the FlowController. This would look like:

class Model {
    var detail1: String?
    var detail2: String?
    var detail3: String?
    ...

    func make() -> Screen1VM {
        return Screen1PhoneVM()
    }

    ...

    func update(with vm: Screen1PhoneVM) {
        detail1 = vm.detail1
        detail2 = vm.detail2
    }

    ...
}

class FlowController {
    ...

    let model: Model

    ...

    init() {
        self.model = Model()
        ...
    }

    func didTapNext(vm: Screen1VM) {
        // Network call to send verification number, then...           
        model.update(with: vm)
        view?.navigate(to: .screen2)
    }

    ...

    func make() -> Screen1VM {
        return model.make()
    }

    ...

}

FlowController now simply orchestrates the initialization of the ViewModel, any once the user has entered the screen details, any necessary network calls, the updating of the Model and moving the navigation foward. However, it is not directly responsibility for any of these actions. The Model generates and updates itself from the ViewModel.

This may seem like overkill for this simple example, but in the real world organizing and scaling this complexity can challenging and this helps to keep responsibilities clear (point 5 in our manifesto). Note also the ViewModel of a screen often needs defaults in its generation, which can be easily handled by the make() function of the Model.

Validation is beyond the scope of this article, but typically there would be different levels required. Simple validation (such as all fields must be completed) could be handled directly by the logic in the ViewModel and disabled(Bool) added to the screen view’s Button referencing the ViewModel. More complex validation (such as backend calls) would be orchestrated by the FlowController.

Another important and interesting note is that normally in SwiftUI all views within the hierarchy are instantiated upfront. For us that correlates to all screens and their corresponding ViewModels are initalized at the beginning. If we have some screen’s ViewModels relying on previous screen’s ViewModels this will cause us problems. Luckily there is a fix with a LazyView discussed in detail here (thank you!), but I do hope that lazy instantiation is more formally handled in the next version of SwiftUI especially in the case of screen navigation.

So going back to our overall screen flow, lets make it a bit more specific. Something like this:

In screen 1, the user enters a phone number, enters the SMS verification number in screen 2, then personal details in 3 and can either skip to the end or decide to add work email on screen 4. Some screens require data from previous screens. The implementation can be found here https://github.com/nickm01/NavigationFlow/tree/part2 (this is the part2 branch on the same repo as part 1).

With the help of lazy computed screens, you’ll notice that the final FlowControllerView implementation is pretty close to our original part 1 pseudo-code:

var body: some View {
    NavigationView {
        VStack() {
            screen1Phone
            Flow(state: navigateTo2) {
                screen2Verification
                Flow(state: navigateTo3) {
                    screen3NameEmail
                    Flow(state: navigateTo4) {
                        screen4CompanyInfo
                        Flow(state: navigateToFinalFrom4) {
                            screen5Final
                        }
                    }
                    Flow(state: navigateToFinalFrom3) {
                        screen5Final
                    }
                }
            }
        }
    }
}

And lastly a note on unit testing as per point 3 of the manifesto. With the introduction of an injectable view protocol, FlowController can now be unit tested and as it itself has no reference to SwiftUI is independant of actual UI implementation. Navigation, ViewModels and Model orchestration can be independantly tested.

Hope you enjoyed this journey. Would love to hear any feedback.

Flow with SwiftUI and MVVM — Part 2: ViewModels was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.

[Note this article relates to SwiftUI 1.0. It has been reworked for SwiftUI 3 and separately for SwiftUI 4.]

I’ve recently been looking at the creation of a multi-screen onboarding flow for my next app and challenging myself to use SwiftUI completely. As with all multi-screen data entry flows, they often represent an interesting problem of how to separate out data, view and navigation logic. I thought SwiftUI’s declarative nature and lean towards ViewModels would be a great opportunity but navigation does have it’s challenges in SwiftUI as we’ll see.

Before we start let’s ask the question: What make’s a great multi-screen data entry flow? Here’s what I came up with. For want of a less grand term, I’ll call it my “screen flow manifesto”:

1. Screens should have no “parent” knowledge nor be responsible for navigating in or out.
2. Individual ViewModels for every screen.
3. Overall flow control logic is separate to UI implementation and is testable without UI.
4. Flexible and allow for branching to different screens in the flow.
5. As simple as possible but scalable.

SwiftUI’s ObservableObject and @ObservedObject pair seem to work well for ViewModels giving us the 2-way binding that has previously been missing in UIKit. There are a lot of approaches to ViewModels but I like to think of them as a pure data interface to the view which avoids any direct view access.

But ViewModel implementation will be discussed in part 2. In part 1 we will looking at setting up the main navigation flow.

Part 1 — Navigation

So an on-boarding may be simple, perhaps 2 or 3 screens asking the user some simple personal information. A “next” button would move the user forward in the flow.

However, whats usually more typical is a more complex flow with branching. Maybe the user isn’t ready to share all those details yet or perhaps the more details on needed depending on previous responses. So maybe this is more representative:

Obviously any solution would need to be handle any combination of the above and, as per manifesto point 1 to do so outside of the the screens themselves. It should also be noted that we probably want to do some data look up at the end of each screen’s entry so we don’t want the view itself to control navigation (manifesto point 3)

As we are in the world of SwiftUI, I propose using the power of @ViewBuilder. This is the “meat” inside the SwiftUI view’s body . ViewBuilders are a powerful way of generating complex generic types — which is what is behind the declarative nature of SwiftUI (but is beyond the scope of this article).

So what could that look like? Well a good start is SwiftUI’s equivalent of UINavigationController which is NavigationView. Into this we add a ViewBuilder equivalent of a tree structure to represent the navigation nodes and edges:

var body: some View {
    NavigationView {
        Screen1()
        Flow {
            Screen2()
            Flow {
                Screen3()
                Flow {
                    FinalScreen()
                }
                Flow {
                    Screen4()
                    Flow {
                        FinalScreen()
                    }
                }
            }
        }
    }
}

OK, so this really is pseudo code. Full disclosure — it ain’t that simple 😀.

But let’s try and get close. Using the imbedded types we can create a good declarative definition of the branching flow diagram from above. It satisfies manifesto point 1, point 2, and perhaps point 5. So let’s see if we can implement something like this.

NavigationView pairs with NavigationLink to give us the ability to do “traditional” push navigation. There are a few variations of use, but I honed into the fully-programmatic variation:

NavigationLink(destination: Destination, isActive: Binding<Bool>) { Label }

After some experimentation here (and frustration with lack of documentation), here are a list considerations of using NavigationLink:

1. Needs to be embedded in a grouping such as a VStack.
2. The Label is typically Text if we want a simple active link to control navigation. However, in our case do not want the view in direct control of navigation so we use EmptyView.
3. You can easily go wrong with the binding. If you want external control of navigation (and we do), using @State does not work as @State is often disconnected to its backing store when used externally.ObservableObject looks promising but after experimentation best controlled by use of one ObservableObject per NavigtaionLink. I had initially tried to use one ObservableObject for all links but this failed miserably.
4. I disliked the order. To me the trigger for navigation reads better if it’s before the destination.

The resulted an improved encapsulation of NavigationLink:

class FlowState: ObservableObject {
    @Published var next: Bool = false
}

struct Flow<Content>: View where Content: View {
    @ObservedObject var state: FlowState
    var content: Content
    var body: some View {
        NavigationLink(
            destination: VStack() { content },
            isActive: $state.next
        ) {
            EmptyView()
        }
    }

    init(state: FlowState, @ViewBuilder content: () -> Content) {
        self.state = state
        self.content = content()
    }
}

This encapsulates some of the complexity of NavigationLink usage. We can pass in a FlowState to allow us to externally control navigation. The plumbing work of needing to use VStack and EmptyView is done for us. It also makes use of @ViewBuilder to make a variation of NavigationLink that reads better.

Let’s see it in action in for a simple 2 screen flow.

private let navigateTo2 = FlowState()
private let navigateTo3 = FlowState()

var body: some View { 
    NavigationView {
        VStack() {
            Text("Screen 1")
            Button(
                action: { self.navigateTo2.next = true },
                label: { Text("Next") }
            )
            Flow(state: navigateTo2) {
                Text("Screen 2")
                Button(
                    action: { self.navigateTo3.next = true },
                    label: { Text("Next") }
                )
                Flow(state: navigateTo3) {
                    Text("Screen 3")
                }
            }
        }
    }
}

Screens 1 and 2 both contain 3 types: AText to display screen name, the Button for the next action and a Flow for the navigation. We store the flow state for each navigation and internal functions perform the actual navigation (didTapNext1 etc).

This works but perhaps is overkill if the next buttons themselves directly do the navigation. Other forms of NavigationLink can fill that role just as well perhaps. However, as part of manifesto part 3 we want our navigation to be controlled externally from views. Typically a “next” button press in an on-boarding flow will require a backend call to validate or save data in each step. To model this out, we could think in terms of a FlowController being in control of the navigation flow which has no knowledge of the views themselves.

It makes sense to have the FlowController own the FlowView and use delegation to event “next requests” back up. We can then wire up the next button taps from the screen views to the delegate functions. So a typical screen view may look something like this:

struct Screen: View {
    let title: String
    let didTapNext: () -> ()

    var body: some View {
        VStack() {
            Text(title)
            Button(
                action: { self.didTapNext() },
                label: { Text("Next") }
            )
        }
    }
}

And implemented something like this:

Screen(
    title: "Screen 1", 
    didTapNext: { self.modelDelegate.didTapNext(request: .screen2) }
)

Let’s see how that looks in totality with the additionally adding in our 5 screen branched flow. You’ll notice there is a separate NavigateTo case paired with a flow state observable for each every navigation edge. (For readability the Screen instantiation has been shortened — please see the repo for full code).

protocol FlowControllerViewDelegate: class {
    func didTapNext(request: NavigateTo)
}

class FlowController {
    var view: FlowControllerView?
    init() {
        self.view = FlowControllerView(delegate: self)
    }
}

extension FlowController: FlowControllerViewDelegate {
    func didTapNext(request: NavigateTo) {
        // In the real world, would do a switch here on NavigateTo,
        // followed by potentially some network calls
        // before finally...
        view?.navigate(to: request)
    }
}

enum NavigateTo {
    case screen1
    case screen2
    case screen3
    case screen4
    case finalFrom3
    case finalFrom4
}

struct FlowControllerView: View {
    weak var delegate: FlowControllerViewDelegate!
    private let navigateTo2 = FlowState()
    private let navigateTo3 = FlowState()
    private let navigateTo4 = FlowState()
    private let navigateToFinalFrom3 = FlowState()
    private let navigateToFinalFrom4 = FlowState()

    init(delegate: FlowControllerViewDelegate) {
        self.delegate = delegate
    }

    func navigate(to navigateTo: NavigateTo) {
        switch navigateTo {
        case .screen1: break
        case .screen2: navigateTo2.next = true
        case .screen3: navigateTo3.next = true
        case .screen4: navigateTo4.next = true
        case .finalFrom3: navigateToFinalFrom3 .next = true
        case .finalFrom4: navigateToFinalFrom4.next = true
        }
    }

    var body: some View {
        NavigationView {
            VStack() {
                Screen(title: "Screen 1", ...)
                Flow(state: navigateTo2) {
                    Screen(title: "Screen 2", ...)
                    Flow(state: navigateTo3) {
                        BranchedScreen(title: "Screen 3", ...)
                        Flow(state: navigateTo4) {
                            Screen(title: "Screen 4", ...)
                            Flow(state: navigateToFinalFrom4) {
                                FinalScreen()
                            }
                        }
                        Flow(state: navigateToFinalFrom3) {
                            FinalScreen()
                        }
                    }
                }
            }
        }
    }
}

struct Screen: View {
    let title: String
    let didTapNext: () -> ()

    var body: some View {
        VStack() {
            Text(title)
            Button(
                action: { self.didTapNext() },
                label: { Text("Next") }
            )
        }
    }
}

struct BranchedScreen: View {
    let title: String
    let didTapNextA: () -> ()
    let didTapNextB: () -> ()

    var body: some View {
        VStack(alignment: .center) {
            Text(title)
            Button(
                action: { self.didTapNextA() },
                label: { Text("Next-A") }
            )
            Button(
                action: { self.didTapNextB() },
                label: { Text("Next-B") }
            )
        }
    }
}

struct FinalScreen: View {
    var body: some View {
        VStack(alignment: .center) {
            Text("Final")
        }
    }
}

In part 2 to follow we look at adding in screen-based ViewModels and completing all our manifesto goals.

Full code can be found: https://github.com/nickm01/NavigationFlow

Flow with SwiftUI and MVVM was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.