Lists & Navigation

Basic List

List is a container that displays rows of data in a scrollable, platform-styled layout. It provides built-in separation, insets, and swipe behavior.

struct FruitList: View {
    let fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
    
    var body: some View {
        List(fruits, id: \.self) { fruit in
            Text(fruit)
        }
    }
}

List with Identifiable Data

For custom types, conform to Identifiable or provide an id key path:

struct Fruit: Identifiable {
    let id = UUID()
    let name: String
    let color: Color
}

struct FruitList: View {
    let fruits = [
        Fruit(name: "Apple", color: .red),
        Fruit(name: "Banana", color: .yellow),
        Fruit(name: "Cherry", color: .red)
    ]
    
    var body: some View {
        List(fruits) { fruit in
            HStack {
                Circle()
                    .fill(fruit.color)
                    .frame(width: 20, height: 20)
                Text(fruit.name)
            }
        }
    }
}

ForEach for Repeated Views

ForEach generates views from a collection. It works inside List, VStack, or any container:

VStack {
    ForEach(0..<5) { index in
        Text("Row \(index)")
    }
}

// With identifiable data
ForEach(fruits) { fruit in
    Text(fruit.name)
}

ForEach is not a view itself -- it generates content within a parent container. It requires stable identifiers to correctly track items across updates.

List with Sections

Organize content into sections with headers and footers:

List {
    Section("Fruits") {
        ForEach(fruits) { fruit in
            Text(fruit.name)
        }
    }
    Section("Vegetables") {
        ForEach(vegetables) { veg in
            Text(veg.name)
        }
    }
}
.listStyle(.insetGrouped)

List Styles

List { /* content */ }
    .listStyle(.plain)           // minimal separators
    .listStyle(.insetGrouped)   // grouped with insets (default on iOS)
    .listStyle(.inset)          // inset without grouping
    .listStyle(.grouped)        // full-width grouped
    .listStyle(.sidebar)        // for sidebar navigation

Dynamic deletion

struct EditableList: View {
    @State private var items = ["Item 1", "Item 2", "Item 3"]
    
    var body: some View {
        List {
            ForEach(items, id: \.self) { item in
                Text(item)
            }
            .onDelete(perform: deleteItems)
        }
        .toolbar {
            EditButton()
        }
    }
    
    func deleteItems(at offsets: IndexSet) {
        items.remove(atOffsets: offsets)
    }
}

List Row Actions

List {
    ForEach(messages) { message in
        Text(message.text)
            .swipeActions(edge: .trailing) {
                Button(role: .destructive) {
                    delete(message)
                } label: {
                    Label("Delete", systemImage: "trash")
                }
                Button {
                    archive(message)
                } label: {
                    Label("Archive", systemImage: "archivebox")
                }
                .tint(.blue)
            }
            .swipeActions(edge: .leading) {
                Button {
                    toggleRead(message)
                } label: {
                    Label(
                        message.isRead ? "Unread" : "Read",
                        systemImage: message.isRead ? "envelope.open" : "envelope"
                    )
                }
                .tint(.orange)
            }
    }
}

Swipe Actions

The .swipeActions modifier adds trailing or leading actions when the user swipes on a row:

List(tasks) { task in
    Text(task.title)
        .swipeActions(edge: .trailing) {
            Button(role: .destructive) {
                delete(task)
            } label: {
                Label("Delete", systemImage: "trash")
            }
            .tint(.red)
            
            Button {
                pin(task)
            } label: {
                Label("Pin", systemImage: "pin")
            }
            .tint(.orange)
        }
        .swipeActions(edge: .leading) {
            Button {
                complete(task)
            } label: {
                Label("Done", systemImage: "checkmark")
            }
            .tint(.green)
        }
}

• .trailing is the default swipe direction (left to right)
• .leading requires an explicit right-to-left swipe
• .tint() sets the background color of the swipe button
• role: .destructive applies standard destructive styling

Searchable Modifier

Add a search bar to filter list content:

struct SearchableList: View {
    let items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
    @State private var searchText = ""
    
    var filteredItems: [String] {
        if searchText.isEmpty {
            return items
        }
        return items.filter { $0.localizedCaseInsensitiveContains(searchText) }
    }
    
    var body: some View {
        NavigationStack {
            List(filteredItems, id: \.self) { item in
                Text(item)
            }
            .searchable(text: $searchText, prompt: "Search fruits")
            .navigationTitle("Fruits")
        }
    }
}

Advanced Search with Suggestions

.searchable(
    text: $searchText,
    placement: .navigationBarDrawer(displayMode: .always),
    prompt: "Search"
) {
    // Search suggestions appear when search field is active
    ForEach(suggestions, id: \.self) { suggestion in
        Text(suggestion)
            .searchCompletion(suggestion)
    }
}

Pull-to-Refresh

List(items) { item in
    Text(item.name)
}
.refreshable {
    await loadItems()
}

The refreshable modifier adds pull-to-refresh and works with both sync and async functions.

Search with Async Filtering

.searchable(text: $searchText)
.task(id: searchText) {
    // Debounced search
    try? await Task.sleep(for: .milliseconds(300))
    results = await searchService.search(query: searchText)
}

List Insets and Separators

List {
    ForEach(items) { item in
        Text(item.name)
    }
    .listRowSeparator(.hidden)       // hide separators
    .listRowSeparatorTint(.blue)     // color separators
    .listRowInsets(.init(top: 8, leading: 20, bottom: 8, trailing: 20))
}

NavigationStack

NavigationStack is the modern navigation container that manages a stack of views. It replaces NavigationView (deprecated).

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List(contacts) { contact in
                NavigationLink(contact.name) {
                    ContactDetail(contact: contact)
                }
            }
            .navigationTitle("Contacts")
        }
    }
}

NavigationLink

NavigationLink pushes a destination view when tapped:

// Basic navigation
NavigationLink("Go to Settings") {
    SettingsView()
}

// With custom label
NavigationLink {
    DetailView(item: item)
} label: {
    HStack {
        Image(systemName: "person.circle")
        Text(item.name)
        Spacer()
        Image(systemName: "chevron.right")
            .foregroundColor(.secondary)
    }
}

// Programmatic navigation (iOS 16+)
@State private var selectedContact: Contact?

NavigationStack {
    List(contacts) { contact in
        Button(contact.name) {
            selectedContact = contact
        }
    }
    .navigationDestination(item: $selectedContact) { contact in
        ContactDetail(contact: contact)
    }
}

NavigationPath

For managing navigation state programmatically:

struct AppNavigation: View {
    @State private var path = NavigationPath()
    
    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: Route.self) { route in
                    switch route {
                    case .settings:
                        SettingsView()
                    case .profile(let id):
                        ProfileView(userId: id)
                    case .detail(let item):
                        DetailView(item: item)
                    }
                }
                .toolbar {
                    Button("Settings") {
                        path.append(Route.settings)
                    }
                }
        }
    }
}

enum Route: Hashable {
    case settings
    case profile(String)
    case detail(String)
}

NavigationPath automatically encodes/decodes for state restoration.

Navigation Title and Toolbar

List(items) { item in
    Text(item.name)
}
.navigationTitle("My Items")
.navigationBarTitleDisplayMode(.inline)  // or .automatic, .large
.toolbar {
    ToolbarItem(placement: .navigationBarTrailing) {
        Button("Add") { addItem() }
    }
    ToolbarItem(placement: .navigationBarLeading) {
        EditButton()
    }
}

Sheets and Full Screen Covers

struct ContentView: View {
    @State private var showingSheet = false
    @State private var showingFullScreen = false
    
    var body: some View {
        VStack {
            Button("Show Sheet") { showingSheet = true }
            Button("Full Screen") { showingFullScreen = true }
        }
        .sheet(isPresented: $showingSheet) {
            SheetView()
        }
        .fullScreenCover(isPresented: $showingFullScreen) {
            FullScreenView()
        }
    }
}

Sheet with Item

.sheet(item: $selectedItem) { item in
    ItemDetail(item: item)
}

The item-based sheet automatically dismisses when the item becomes nil.

Navigation with Deep Linking

struct ContentView: View {
    @State private var path = NavigationPath()
    
    var body: some View {
        NavigationStack(path: $path) {
            // ... root view
        }
        .onOpenURL { url in
            // Handle deep link
            if let route = DeepLinkParser.parse(url) {
                path.append(route)
            }
        }
    }
}