List
A container that presents rows of data arranged in a single column, optionally providing the ability to select one or more members.
Declaration
import { List } from 'swiftui-react-native';nonisolated struct List<SelectionValue, Content> where SelectionValue : Hashable, Content : ViewInitializers
15 SwiftUI initializers back <List>. The props you pass pick one.
<List
childrenPath?: undefined
>
children?: ReactNode
</List>nonisolated init(@ContentBuilder content: () -> Content)childrenReactNodeContent. Strings become
Text; React Native views are laid out by Yoga and placed by SwiftUI.Swift
content: () -> ContentchildrenPathundefined
Also takes the common view props: modifiers, style and testID.
Overview
In its simplest form, a List creates its contents statically, as shown in
the following example:
var body: some View {
List {
Text("A List Item")
Text("A Second List Item")
Text("A Third List Item")
}
}More commonly, you create lists dynamically from an underlying collection
of data. The following example shows how to create a simple list from an
array of an Ocean type which conforms to
doc://com.apple.documentation/documentation/Swift/Identifiable:
struct Ocean: Identifiable {
let name: String
let id = UUID()
}
private var oceans = [
Ocean(name: "Pacific"),
Ocean(name: "Atlantic"),
Ocean(name: "Indian"),
Ocean(name: "Southern"),
Ocean(name: "Arctic")
]
var body: some View {
List(oceans) { ocean in
Text(ocean.name)
}
}Supporting selection in lists
To make members of a list selectable, provide a binding to a selection
variable. Binding to a single instance of the list data's Identifiable.ID
type creates a single-selection list. Binding to a
doc://com.apple.documentation/documentation/Swift/Set
with a type that matches the list data's Identifiable.ID type creates a
list that supports multiple selections. The following example shows how to add
multiselect to the previous example:
struct Ocean: Identifiable, Hashable {
let name: String
let id = UUID()
}
private var oceans = [
Ocean(name: "Pacific"),
Ocean(name: "Atlantic"),
Ocean(name: "Indian"),
Ocean(name: "Southern"),
Ocean(name: "Arctic")
]
@State private var multiSelection = Set<UUID>()
var body: some View {
NavigationStack {
List(oceans, selection: $multiSelection) { ocean in
Text(ocean.name)
}
.navigationTitle("Oceans")
.toolbar { EditButton() }
}
Text("\(multiSelection.count) selections")
}When people make a single selection by tapping or clicking, the selected
cell changes its appearance to indicate the selection. To enable multiple
selections with tap gestures, put the list into edit mode by either
modifying the EnvironmentValues.editMode value, or adding an
EditButton to your app's interface. When you put the list into edit
mode, the list shows a circle next to each list item. The circle contains
a checkmark when the user selects the associated item. The example above
uses an Edit button, which changes its title to Done while in edit mode:
People can make multiple selections without needing to enter edit mode on devices that have a keyboard and mouse or trackpad, like Mac and iPad.
Refreshing the list content
To make the content of the list refreshable using the standard refresh
control, use the View.refreshable(action:) modifier.
The following example shows how to add a standard refresh control to a list.
When the user drags the top of the list downward, SwiftUI reveals the refresh
control and executes the specified action. Use an await expression
inside the action closure to refresh your data. The refresh indicator remains
visible for the duration of the awaited operation.
struct Ocean: Identifiable, Hashable {
let name: String
let id = UUID()
let stats: [String: String]
}
@Observable class OceanStore {
var oceans: [Ocean] = [
Ocean(name: "Atlantic", stats: [:]),
Ocean(name: "Indian", stats: [:]),
Ocean(name: "Pacific", stats: [:])
]
func loadStats() async {
// Load statistics asynchronously.
}
}
@State private var store: OceanStore = OceanStore()
var body: some View {
NavigationStack {
List(store.oceans) { ocean in
HStack {
Text(ocean.name)
// A custom view that shows statistics.
StatsSummary(stats: ocean.stats)
}
}
.refreshable {
await store.loadStats()
}
.navigationTitle("Oceans")
}
}Supporting multidimensional lists
To create two-dimensional lists, group items inside Section instances.
The following example creates sections named after the world's oceans,
each of which has Text views named for major seas attached to those
oceans. The example also allows for selection of a single list item,
identified by the id of the example's Sea type.
struct ContentView: View {
struct Sea: Hashable, Identifiable {
let name: String
let id = UUID()
}
struct OceanRegion: Identifiable {
let name: String
let seas: [Sea]
let id = UUID()
}
private let oceanRegions: [OceanRegion] = [
OceanRegion(name: "Pacific",
seas: [Sea(name: "Australasian Mediterranean"),
Sea(name: "Philippine"),
Sea(name: "Coral"),
Sea(name: "South China")]),
OceanRegion(name: "Atlantic",
seas: [Sea(name: "American Mediterranean"),
Sea(name: "Sargasso"),
Sea(name: "Caribbean")]),
OceanRegion(name: "Indian",
seas: [Sea(name: "Bay of Bengal")]),
OceanRegion(name: "Southern",
seas: [Sea(name: "Weddell")]),
OceanRegion(name: "Arctic",
seas: [Sea(name: "Greenland")])
]
@State private var singleSelection: UUID?
var body: some View {
NavigationStack {
List(selection: $singleSelection) {
ForEach(oceanRegions) { region in
Section(header: Text("Major \(region.name) Ocean Seas")) {
ForEach(region.seas) { sea in
Text(sea.name)
}
}
}
}
.navigationTitle("Oceans and Seas")
}
}
}Because this example uses single selection, people can make selections outside of edit mode on all platforms.
Creating hierarchical lists
You can also create a hierarchical list of arbitrary depth by providing
tree-structured data and a children parameter that provides a key path to
get the child nodes at any level. The following example uses a deeply-nested
collection of a custom FileItem type to simulate the contents of a
file system. The list created from this data uses collapsing cells to allow
the user to navigate the tree structure.
struct ContentView: View {
struct FileItem: Hashable, Identifiable, CustomStringConvertible {
var id: Self { self }
var name: String
var children: [FileItem]? = nil
var description: String {
switch children {
case nil:
return "๐ \(name)"
case .some(let children):
return children.isEmpty ? "๐ \(name)" : "๐ \(name)"
}
}
}
let fileHierarchyData: [FileItem] = [
FileItem(name: "users", children:
[FileItem(name: "user1234", children:
[FileItem(name: "Photos", children:
[FileItem(name: "photo001.jpg"),
FileItem(name: "photo002.jpg")]),
FileItem(name: "Movies", children:
[FileItem(name: "movie001.mp4")]),
FileItem(name: "Documents", children: [])
]),
FileItem(name: "newuser", children:
[FileItem(name: "Documents", children: [])
])
]),
FileItem(name: "private", children: nil)
]
var body: some View {
List(fileHierarchyData, children: \.children) { item in
Text(item.description)
}
}
}Styling lists
SwiftUI chooses a display style for a list based on the platform and the
view type in which it appears. Use the View.listStyle(_:) modifier to
apply a different ListStyle to all lists within a view. For example,
adding .listStyle(.plain) to the example shown in the
"Creating Multidimensional Lists" topic applies the
ListStyle.plain style, the following screenshot shows:
From Appleโs SwiftUI documentation. Code samples there are Swift.
Relationships
Conforms to
- View
See also
More in Lists and collections.