Mastering SwiftUI’s ContentUnavailableView: Show Empty States with Ease

Introduction

SwiftUI introduces the ContentUnavailableView type, which lets developers present empty states, error states, or any other unavailable content in an app. This article shows how to use ContentUnavailableView to guide users through such scenarios.

Basic Usage

Start by displaying a simple ContentUnavailableView overlay when the product list is empty.

struct ContentView: View {
    let store: Store
    
    var body: some View {
        NavigationStack {
            List(store.products, id: \ .self) { product in
                Text(verbatim: product)
            }
            .navigationTitle("Products")
            .overlay {
                if store.products.isEmpty {
                    ContentUnavailableView(
                        "Connection issue",
                        systemImage: "circle"
                    )
                }
            }
        }
    }
}

The overlay shows ContentUnavailableView whenever the product list is empty, displaying a title and an optional system image.

Custom View

struct ContentView: View {
    let store: Store
    
    var body: some View {
        NavigationStack {
            List(store.products, id: \ .self) { product in
                Text(verbatim: product)
            }
            .navigationTitle("Products")
            .overlay {
                if store.products.isEmpty {
                    ContentUnavailableView {
                        Label("Connection issue", systemImage: "wifi.slash")
                    } description: {
                        Text("Check your internet connection")
                    } actions: {
                        Button("Refresh") {
                            store.fetch()
                        }
                    }
                }
            }
        }
    }
}

This variant uses a ViewBuilder closure to define the title, description text, and action button, allowing full customization of the view’s appearance and behavior.

Search Screen Usage

struct ContentView: View {
    @Bindable var store: Store
    
    var body: some View {
        NavigationStack {
            List(store.products, id: \ .self) { product in
                Text(verbatim: product)
            }
            .navigationTitle("Products")
            .overlay {
                if store.products.isEmpty {
                    ContentUnavailableView.search
                }
            }
            .searchable(text: $store.query)
        }
    }
}

When showing search results, the built‑in ContentUnavailableView.search can be used. The framework localizes it and automatically extracts the search bar’s text to display within the view.

Manual Query Provision

struct ContentView: View {
    @Bindable var store: Store
    
    var body: some View {
        NavigationStack {
            List(store.products, id: \ .self) { product in
                Text(verbatim: product)
            }
            .navigationTitle("Products")
            .overlay {
                if store.products.isEmpty {
                    ContentUnavailableView.search(text: store.query)
                }
            }
            .searchable(text: $store.query)
        }
    }
}

Developers can also call the search variant with a manual query string, passing the desired text directly to the view.

Runnable Demo

A complete, runnable demo requires a simple Store implementation. Below is a minimal SwiftUI example that demonstrates the basic use of ContentUnavailableView when the product list is empty.

import SwiftUI

struct Product: Identifiable {
    let id: UUID
    let name: String
}

class ProductStore: ObservableObject {
    @Published var products: [Product] = []
    
    func fetchProducts() {
        // Simulating product fetching
        DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
            self.products = [
                Product(id: UUID(), name: "iPhone"),
                Product(id: UUID(), name: "iPad")
            ]
        }
    }
}

struct ContentView: View {
    @StateObject var store = ProductStore()
    
    var body: some View {
        NavigationView {
            List(store.products) { product in
                Text(product.name)
            }
            .navigationTitle("Products")
            .overlay {
                if store.products.isEmpty {
                    ContentUnavailableView(
                        "No Products",
                        systemImage: "exclamationmark.triangle"
                    )
                }
            }
            .onAppear {
                store.fetchProducts()
            }
        }
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}

This code defines a Product struct, a mock ProductStore service, and uses ContentUnavailableView to show a “No Products” message until the simulated fetch populates the list.

Conclusion

We have learned how to employ SwiftUI’s ContentUnavailableView to present user‑friendly empty states, customize its appearance with titles, descriptions, and actions, and integrate it with search functionality, providing a powerful tool for handling unavailable content in iOS apps.