Chapter 2: Going Beyond the Single Component with Lists and Scroll Views
In this chapter, we'll learn how to display lists in SwiftUI. List
views are like UITableViews
in UIKit but are significantly simpler to use. For example, no storyboards or prototype cells are required, and we do not need to remember how many rows or columns we created. Furthermore, SwiftUI's lists are modular so that you can build more significant apps from smaller components.
This chapter will also discuss new and exciting features introduced in WWDC 2021, such as lists with editable text and searchable lists. By the end of this chapter, you will understand how to display lists of static or dynamic items, add or remove items from lists, edit lists, add sections to List
views, and much more.
In this chapter, we'll be covering the following recipes:
- Using scroll views
- Creating a list of static items
- Using custom rows in a list
- Adding rows to a list
- Deleting rows from a list
- Creating an editable List view
- Moving the rows in a List view
- Adding sections to a list
- Creating editable Collections
- Creating Searchable lists
Technical requirements
The code in this chapter is based on Xcode 13 and iOS 15.
You can find the code for this book in this book's GitHub repository: https://github.com/PacktPublishing/SwiftUI-Cookbook-2nd-Edition/tree/main/Chapter02-Lists-and-ScrollViews.
Using scroll views
You can use SwiftUI scroll views when the content to be displayed cannot fit in its container. Scroll views create scrolling content where users can use gestures to bring new content into the section of the screen where it can be viewed. Scroll views are vertical by default but can be made to scroll horizontally or vertically.
In this recipe, we will learn how to use horizontal and vertical scroll views.
Getting ready
Let's start by creating a SwiftUI project called WeScroll
.
Optional: If you don't have it yet, download the San Francisco Symbols (SF Symbols) app here: https://developer.apple.com/sf-symbols/.
As we mentioned in Chapter 1, Using the Basic SwiftUI Views and Controls, SF Symbols is a set of over 3,200 symbols provided by Apple.
How to do it…
Let's learn how scroll views work by implementing horizontal and vertical scroll views that display SF symbols for alphabet characters A - P. Here are the steps:
- Add an array variable to our
ContentView
struct that contains the lettersa
top
:let letters = ["a","b","c","d","e","f","g","h", "i","j","k","l","m","n","o","p"]
- Replace the original text view with a
VStack
, aScrollView
, and aForEach
struct:var body: some View { VStack{ ScrollView { ForEach(self.letters, id: \.self){ letter in Image(systemName: letter) .font(.largeTitle) .foregroundColor(Color.yellow) .frame(width: 50, height: 50) .background(Color.blue) .symbolVariant(.circle.fill) } } .frame(width:50, height:200) ScrollView(.horizontal, showsIndicators: false) { HStack{ ForEach(self.letters, id: \.self){ name in Image(systemName: name) .font(.largeTitle) .foregroundColor(Color.yellow) .frame(width: 50, height: 50) .background(Color.blue) .symbolVariant(.circle.fill) } } } } }
- Run/resume the Xcode preview from the canvas window. It should look as follows:
How it works…
By default, scroll views display items vertically. Therefore, our first scroll view displays its content along the vertical axis without requiring us to specify the axis.
In this recipe, we also introduce the ForEach
structure, which computes views on-demand based on an underlying collection of identified data. In this case, the ForEach
structure iterates over a static array of alphabet characters and displays the SF Symbols
of the said characters.
We provided two arguments to the ForEach
structure: the collection we want to iterate over and an id
. This id
helps us distinguish between the items in the collection and should be unique. Using \.self
as id
, we indicated that the alphabet characters we are using are unique and will not be repeated in this List
. We used unique items because SwiftUI expects each row to be uniquely identifiable and will not run as expected otherwise.
You can use the ForEach
structure without specifying the id
argument if your collection conforms to the Identifiable
protocol.
Moving on to the second scroll view, it uses two arguments: axis
and showIndicators
. The .horizontal
axis's enum
indicates we want the content to scroll horizontally, while the .showIdicators: false
argument prevents the scrollbar indicator from appearing in the view.
See also
Apple's documentation on scroll views: https://developer.apple.com/documentation/swiftui/scrollview
Creating a list of static items
List
views are like scroll views in that they are used to display a collection of items. However, List
views are better for dealing with larger datasets because they do not load the entirety of the datasets in memory.
In this recipe, we will create an app the uses static lists to display sample weather data for various cities.
Getting ready
Let's start by creating a new SwiftUI app called StaticList
.
How to do it…
We'll create a struct
to hold weather information and an array of several cities' weather data. We'll then use a List
view to display all the content. The steps are as follows:
- Open the
ContentView.swift
file and add theWeatherInfo
struct right above theContentView
struct:struct WeatherInfo: Identifiable { var id = UUID() var image: String var temp: Int var city: String }
- Add the
weatherData
property to theContentView
struct.weatherData
contains an array ofWeatherInfo
items:let weatherData: [WeatherInfo] = [ WeatherInfo(image: "snow", temp: 5, city:"New York"), WeatherInfo(image: "cloud", temp:5, city:"Kansas City"), WeatherInfo(image: "sun.max", temp: 80, city:"San Francisco"), WeatherInfo(image: "snow", temp: 5, city:"Chicago"), WeatherInfo(image: "cloud.rain", temp: 49, city:"Washington DC"), WeatherInfo(image: "cloud.heavyrain", temp: 60, city:"Seattle"), WeatherInfo(image: "sun.min", temp: 75, city:"Baltimore"), WeatherInfo(image: "sun.dust", temp: 65, city:"Austin"), WeatherInfo(image: "sunset", temp: 78, city:"Houston"), WeatherInfo(image: "moon", temp: 80, city:"Boston"), WeatherInfo(image: "moon.circle", temp: 45, city:"denver"), WeatherInfo(image: "cloud.snow", temp: 8, city:"Philadelphia"), WeatherInfo(image: "cloud.hail", temp: 5, city:"Memphis"), WeatherInfo(image: "cloud.sleet", temp:5, city:"Nashville"), WeatherInfo(image: "sun.max", temp: 80, city:"San Francisco"), WeatherInfo(image: "cloud.sun", temp: 5, city:"Atlanta"), WeatherInfo(image: "wind", temp: 88, city:"Las Vegas"), WeatherInfo(image: "cloud.rain", temp: 60, city:"Phoenix"), ]
- Add the
List
view to theContentView
body and use theForEach
structure to iterate over ourweatherData
collection. Add some font and padding modifiers to improve the styling too:List { ForEach(self.weatherData){ weather in HStack { Image(systemName: weather.image) .frame(width: 50, alignment: .leading) Text("\(weather.temp)°F") .frame(width: 80, alignment: .leading) Text(weather.city) } .font(.system(size: 25)) .padding() } }
The resulting preview should look as follows:
How it works…
First, we created the WeatherInfo
struct, which contains properties we'd like to use, such as images, temperature (temperate
), and city
. Notice that the WeatherInfo
struct implements the Identifiable
protocol. Making the struct conform to the Identifiable
protocol allows us to use the data in a ForEach
structure without specifying an id
parameter. To conform to the Identifiable
protocol, we added a unique property to our struct called id
, a property whose value is generated by the UUID()
function.
The basic form of a static list is composed of a List
view and some other views, as shown here:
List { Text("Element one") Text("Element two") }
In this recipe, we went a step further and used the ForEach
struct to iterate through an array of identifiable elements stored in the weatherData
variable. We wanted to display the data in each list item horizontally, so we displayed the contents in an HStack
. Our image, temperature, and city are displayed using image and text views.
The weather image names are SF Symbol variants, so using them with an Image
view systemName
parameter displays the corresponding SF Symbol. You can read more about SF Symbols in Chapter 1, Using the Basic SwiftUI Views and Controls.
Using custom rows in a list
The number of lines of code required to display items in a List
view row could vary from one to several lines of code. Repeating the code several times or in several places increases the chance of an error occurring and potentially becomes very cumbersome to maintain. One change would require updating the code in several different locations or files.
A custom list row can be used to solve this problem. This custom row can be written once and used in several places, thereby improving maintainability and encouraging reuse.
Let's find out how to create custom list rows.
Getting ready
Let's start by creating a new SwiftUI app named CustomRows
.
How to do it…
We will reorganize the code in our static lists to make it more modular. We'll create a separate file to hold the WeatherInfo
struct, a separate SwiftUI file for the custom view, WeatherRow
, and finally, we'll implement the components in the ContentView.swift
file. The steps are as follows:
- Create a new Swift file called
WeatherInfo
by going to File | New | File | Swift File (or by using the Command () + N keys). - Create a
WeatherInfo
struct within the newly created file:struct WeatherInfo: Identifiable { var id = UUID() var image: String var temp: Int var city: String }
- Also, add a
weatherData
variable that holds an array ofWeatherInfo
:let weatherData: [WeatherInfo] = [ WeatherInfo(image: "snow", temp: 5, city:"New York"), WeatherInfo(image: "cloud", temp:5, city:"Kansas City"), WeatherInfo(image: "sun.max", temp: 80, city:"San Francisco"), WeatherInfo(image: "snow", temp: 5, city:"Chicago"), WeatherInfo(image: "cloud.rain", temp: 49, city:"Washington DC"), WeatherInfo(image: "cloud.heavyrain", temp: 60, city:"Seattle"), WeatherInfo(image: "sun.min", temp: 75, city:"Baltimore"), WeatherInfo(image: "sun.dust", temp: 65, city:"Austin"), WeatherInfo(image: "sunset", temp: 78, city:"Houston"), WeatherInfo(image: "moon", temp: 80, city:"Boston"), WeatherInfo(image: "moon.circle", temp: 45, city:"denver"), WeatherInfo(image: "cloud.snow", temp: 8, city:"Philadelphia"), WeatherInfo(image: "cloud.hail", temp: 5, city:"Memphis"), WeatherInfo(image: "cloud.sleet", temp:5, city:"Nashville"), WeatherInfo(image: "sun.max", temp: 80, city:"San Francisco"), WeatherInfo(image: "cloud.sun", temp: 5, city:"Atlanta"), WeatherInfo(image: "wind", temp: 88, city:"Las Vegas"), WeatherInfo(image: "cloud.rain", temp: 60, city:"Phoenix"), ]
- Create a new SwiftUI file by selecting File | New | File | SwiftUI View from the Xcode menu or by using the Command () + N key combination. Name the file
WeatherRow
. - Add the following weather row design to our new SwiftUI view:
struct WeatherRow: View { var weather: WeatherInfo var body: some View { HStack { Image(systemName: weather.image) .frame(width: 50, alignment: .leading) Text("\(weather.temp)°F") .frame(width: 80, alignment: .leading) Text(weather.city) } .font(.system(size: 25)) .padding() } }
- To preview or update the row design, add a sample
WeatherInfo
instance to theWeatherRow_Previews
function:struct WeatherRow_Previews: PreviewProvider { static var previews: some View { WeatherRow(weather: WeatherInfo(image: "snow", temp: 5, city:"New York")) } }
The resulting
WeatherRow.swift
canvas preview should look as follows: - Open the
ContentView.swift
file and create a list to display data using theWeatherRow
component:struct ContentView: View { var body: some View { List{ ForEach(weatherData){weather in WeatherRow(weather: weather) } } } }
Run the app on a device or run a live preview to scroll through and test the app's functionality.
How it works…
WeatherInfo.swift
is the model file containing a blueprint of what we want each instance of our weatherInfo
struct to contain. We also instantiated an array of the WeatherInfo
struct, weatherData
, that can be used in other parts of the project previewing and testing areas as we build.
The WeatherRow
SwiftUI file is our focus for this recipe. By using this file, we can extract the design of a list row into a separate file and reuse the design in other sections of our project. We added a weather property to our WeatherRow
that will hold the WeatherInfo
arguments that are passed to our WeatherRow
view.
As in the previous recipe, we want the content of each row to be displayed horizontally next to each other, so we enclosed the components related to our weather variable in an HStack
.
Important Note
The weatherData
array is only necessary during development and should be removed before deployment if such data is obtained at runtime through API calls.
Adding rows to a list
The most common actions users might want to be able to perform on a list include adding, editing, or deleting items.
In this recipe, we'll go over the process of implementing those actions on a SwiftUI list.
Getting ready
Create a new SwiftUI project and call it ListRowAdd.
How to do it…
Let's create a list with a button at the top that can be used to add new rows to the list. The steps are as follows:
- Create a state variable in the
ContentView
struct that holds an array of numbers:@State var numbers = [1,2,3,4]
- Add a
NavigationView
struct and aList
view to theContentView
struct's body:NavigationView{ List{ ForEach(self.numbers, id:\.self){ number in Text("\(number)") } } }
- Add a
.navigationBarTitle
modifier to the list with a title:.navigationBarTitle("Number List", displayMode: .inline)
- Add a
navigationBarItems
modifier to the list with a function to trigger an element being added to the row:.navigationBarItems(trailing: Button("Add", action: addItemToRow))
- Implement the
addItemToRow
function and place it immediately after thebody
view's closing brace:private func addItemToRow() { self.numbers.append(Int.random(in: 5 ..< 100)) }
You can now run the preview and click the Add button to add new items to the list.
How it works…
Our state variable, numbers
, holds an array of numbers. We made it a state variable so that the view that's created by our ForEach
struct gets updated each time a new number is added to the array.
The .navigationBarTitle
("Number List," displayMode: .inline
) modifier adds a title to the top of the list and within the standard bounds of the navigation bar. The display mode is optional, so you could remove it to display the title more prominently. Other display modes include automatic
, to inherit from the previous navigation item, and large
, to display the title within an expanded navigation bar.
The .navigationbartItems(…)
modifier adds a button to the trailing end of the navigation section. The button calls the addItemToRow
function when clicked.
Finally, the addItemToRow
function generates a random number between 0-99 and appends it to the numbers
array. The view gets automatically updated since the numbers variable is a state variable and a change in its state triggers a view refresh.
Important Note
In our list's ForEach
struct, we used \.self
as our id
parameter. However, we may end up with duplicate numbers in our list as we generate more items. Identifiers should be unique, so using values that could be duplicated may lead to unexpected behaviors. Remember to ONLY use unique identifiers for apps meant to be deployed to users.
Deleting rows from a list
So far, we've learned how to add new rows to a list. Now, let's find out how to use a swipe motion to delete items one at a time.
Getting ready
Create a new SwiftUI app called ListRowDelete
.
How to do it…
We will create a list of items and use the list view's onDelete
modifier to delete rows. The steps are as follows:
- Add a
state
variable to theContentView
struct calledcountries
and initialize it with an array of country names:@State var countries = ["USA", "Canada", "England", "Cameroon", "South Africa", "Mexico" , "Japan", "South Korea"]
- Within the body variable, add a
navigationView
and aList
view that displays our array of countries. Also, include theonDelete
modifier at the end of theForEach
structure:NavigationView{ List { ForEach(countries, id: \.self) { country in Text(country) } .onDelete(perform: self.deleteItem) } .navigationBarTitle("Countries", displayMode: .inline) }
- Below the body variable's closing brace, add the
deleteItem
function:private func deleteItem(at indexSet: IndexSet){ self.countries.remove(atOffsets: indexSet) }
Run the canvas preview and swipe right to left on a list row. The Delete button will appear and can be clicked to delete an item from the list.
How it works…
In this recipe, we introduced the .onDelete
modifier, whose perform
parameter takes a function that will be executed when clicked. In this case, deleting an item triggers the execution of our deleteItem
function.
The deleteItem
function takes a single parameter, IndexSet
, which is the index of the row to be deleted. The onDelete
modifier automatically passes the index of the item to be deleted.
There's more…
Deleting an item from a List
view can also be performed by embedding the list navigation view and adding an EditButton
component.
Creating an editable List view
Adding an edit button to a List
view is very similar to adding a delete button, as seen in the previous recipe. An edit button offers the user the option to quickly delete items by clicking a minus sign to the left of each list row.
Getting ready
Create a new SwiftUI project named ListRowEdit
.
How to do it…
The steps for adding an edit button to a List
view are similar to the steps we used when adding a delete button. The process is as follows:
- Replace the
ContentView
struct with the following content from theDeleteRowFromList
app:struct ContentView: View { @State var countries = ["USA", "Canada", "England", "Cameroon", "South Africa", "Mexico" , "Japan", "South Korea"] var body: some View { NavigationView{ List { ForEach(countries, id: \.self) { country in Text(country) } .onDelete(perform: self.deleteItem) } .navigationBarTitle("Countries", displayMode: .inline) } } private func deleteItem(at indexSet: IndexSet){ self.countries.remove(atOffsets: indexSet) } }
- Add a
.navigationBarItems(training: EditButton())
modifier to theList
view, just below the.navigationBarTitle
modifier. - Run the preview and click on the Edit button at the top-right corner of the emulated device's screen. A minus (-) sign in a red circle will appear to the left of each list item, as shown in the following preview:
Click on the circle to the left of any list item to delete it.
How it works…
The .navigationBarItems(trailing: EditButton())
modifier adds an Edit button to the top-right corner of the display. Once clicked, it triggers the appearance of a minus sign to the left of each item in the modified List. Clicking on the minus sign executes the function in our .onDelete
modifier and deletes the related item from the row.
There's more…
To display the Edit button on the left-hand side of the navigation bar, change the modifier to .navigationBarItems(leading: EditButton())
.
Moving the rows in a List view
In this recipe, we'll create an app that implements a List
view that allows users to move and reorganize rows.
Getting ready
Create a new SwiftUI project named MovingListRows
.
How to do it…
To make the List
view rows movable, we'll add a modifier to the List
view's ForEach
struct, and then we'll embed the List
view in a navigation view that displays a title and an edit button. The steps are as follows:
- Add a
@State
variable to theContentView
struct that holds an array of countries:@State var countries = ["USA", "Canada", "England", "Cameroon", "South Africa", "Mexico" , "Japan", "South Korea"]
- Replace the body variable's text view with a
NavigationView
, aList
, and modifiers for navigating. Also, notice that the.on Move
modifier is applied to theForEach
struct:NavigationView{ List { ForEach(countries, id: \.self) { country in Text(country) } .on Move(perform: moveRow) } .navigationBarTitle("Countries", displayMode: .inline) .navigationBarItems(trailing: EditButton()) }
- Now, let's add the function that gets called when we try to move a row. The
moveRow
function should be located directly below the closing brace of the body view:private func moveRow(source: IndexSet, destination: Int){ countries.move(fromOffsets: source, toOffset: destination) }
Let's run our application in the canvas or a simulator and click on the edit button. If everything was done right, the preview should look as follows. Now, click and drag on the hamburger menu symbol at the right of each country to move it to a new location:
How it works…
To move list rows, you need to wrap the list in a NavigationView
, add the .on Move(perform:)
modifier to the ForEach
struct, and add a .navigationBarItems(..)
modifier to the list. The on Move
modifier calls the moveRow
function when clicked, while .navigationBarItem
displays the button that starts the "move mode," where list row items become movable.
The moveRow(source: IndexSet, destination: Int)
function takes two parameters, source
and IndexSet
, which represent the current index of the item to be moved and its destination index, respectively.
Adding sections to a list
In this recipe, we will create an app that implements a static list with sections. The app will display a list of countries grouped by continent.
Getting ready
Let's start by creating a new SwiftUI app in Xcode named ListWithSections
.
How to do it…
We will add a Section
view to our List
to separate groups of items by section titles. Proceed as follows:
- (Optional) Open the
ContentView.swift
file and replace theText
view with aNavigationView
. Wrapping theList
in aNavigationView
allows us to add a title and navigation items to the view:NavigationView{ }
- Add a list and section to
NavigationView
(or body view if you skipped optional Step 1). Also, add alistStyle
andnavigationBarTitle
modifier:List { Section(header: Text("North America")){ Text("USA") Text("Canada") Text("Mexico") Text("Panama") Text("Anguilla") } } .listStyle(.grouped) .navigationBarTitle("Continents and Countries", displayMode: .inline)
- Below the initial
Section
, add more sections representing countries in various continents:List { … Section(header: Text("Africa")){ Text("Nigeria") Text("Ghana") Text("Kenya") Text("Senegal") } Section(header: Text("Europe")){ Text("Spain") Text("France") Text("Sweden") Text("Finland") Text("UK") } }
Looking at the preview, you can see the continents where each country is located by reading the section titles.
How it works…
SwiftUI's Section
views are used to separate items into groups. In this recipe, we used Section
views to visually group countries by their continents. A Section
view can be used with a header, as shown in this recipe, or without a header, as follows:
Section { Text("Spain") Text("France") Text("Sweden") Text("Finland") Text("UK") }
You can change section styles by using the listStyle()
modifier with the .grouped
style.
Creating editable Collections
Editing lists has always been possible in SwiftUI but before WWDC 2021 and SwiftUI 3, doing so was very inefficient because SwiftUI did not support binding to Collections. Let's use bindings on a collection and discuss how and why it works better now.
Getting ready
Create a new SwiftUI project and name it EditableListsFields
.
How to do it…
Let's create a simple to-do list app with a few editable items. The steps are as follows:
- Add a
TodoItem
struct below theimport
SwiftUI line:struct TodoItem: Identifiable { let id = UUID() var title: String init(_ someTitle:String){ title = someTitle } }
- In our
ContentView
struct, let's add a collection ofTodoItem
instances:@State var todos = [ TodoItem("Eat"), TodoItem("Sleep"), TodoItem("Code") ]
- Replace the
Text
view in the body with aList
and aTextField
view that displays the collection oftodo
items:var body: some View { List($todos) { $todo in TextField("Number", text: $todo.title) } }
Run the preview in canvas. You should be able to edit the text in each row, as shown in the following screenshot:
Click on any of the other rows and edit it to your heart's content.
How it works…
Let's start by looking at how editable lists were handled before SwiftUI 3. Before SwiftUI 3, the code for an editable list of items would use list indices to create bindings to a collection, as follows:
List(0..<todos.count) { index in TextField("Todo", text: $todos[index].title) }
Not only was such code slow, but editing a single item caused SwiftUI to re-render the entire List
of elements, leading to flickering and slow UI updates.
With SwiftUI 3, we can pass a binding to a collection of elements, and SwiftUI will internally handle binding to the current element specified in the closure. Since the whole of our collection conforms to the Identifiable
protocol, each of our list items can be uniquely identified by its id
parameter; therefore, adding or removing items from the list does not change list item indices and does not cause the entire list to be re-rendered.
Using Searchable lists
List
views can hold from one to an uncountable number of items. As the number of items in a list increases, it is usually helpful to provide users with the ability to search through the list for a specific item without having to scroll through the whole list.
In this recipe, we'll introduce the .searchable()
modifier and discuss how it can be used to search through items in a list.
Getting ready
Create a new SwiftUI project and name it SearchableLists
.
The searchable modifier is only available in iOS 15+. In your build settings, make sure that your iOS Deployment Target is set to iOS 15. Use the following steps to change the deployment target:
- From the navigation pane, select the project's name (SearchableLists).
- Select Build settings.
- Under Deployment, select iOS Deployment Target.
- Select iOS 15.0 from the popup menu.
These steps are shown in the following screenshot:
How to do it…
Let's create an app to search through possible messages between a parent and their child. The steps are as follows:
- Before the
ContentView
struct's body, add aState
variable to hold the search text and sample messages:@State private var searchText="" let messages = [ "Dad, can you lend me money?", "Nada. Does money grow on trees?", "What is money made out of?", "Paper", "Where does paper come from?", "Huh.....", ]
- Add a
NavigationView
, aList
to display the search results, anavigationBarTitle
modifier, and a.searchable
modifier:var body: some View { NavigationView { List{ ForEach(searchResults, id: \.self){ msg in Text(msg) } } .searchable(text: $searchText) .navigationBarTitle("Order number") } }
- Below the
body
variable, add thesearchResults
computed property, which returns an array of elements representing the result of the search:var searchResults: [String] { if searchText.isEmpty { return messages }else{ return messages.filter{ $0.lowercased().contains (searchText.lowercased())} } }
Run the app in canvas mode. The resulting live preview should look as follows:
Now, type something within the search field and watch how the content is filtered to match the result of the search text that was entered.
How it works…
The searchText
state variable holds the value that's being searched for and is passed as an argument to the .searchable
modifier. Each time the value of searchText
changes, the computed property, searchResults
, gets calculated. Finally, the value of searchResults
is used in the ForEach
struct to display a filtered list of items based on the search text.
There's more…
You can provide autocomplete information by adding a closure to the .searchable
modifier, as shown here:
.searchable(text: $searchText){ ForEach(searchResults, id: \.self) { result in ' Text((result)).searchCompletion(result) } }
The autocomplete feature provides the user with possible suggestions that match the search string they've entered so far. Clicking on one of the suggestions auto-fills the rest of the search text area and displays the results from the search.