Refresable List#

Marks a scrollable view as refreshable, enabling the user to pull down to trigger an asynchronous data reload.

Type#

1refreshable?: () => Promise<void>

Overview#

Use the refreshable modifier on scrollable views—such as <List>—to implement pull-to-refresh functionality. When the user pulls down past the top of the view, the framework executes the asynchronous handler defined by refreshable.

Inside the handler, you can perform any asynchronous operations (e.g., fetching network data or updating local state), and once the operation completes, the refresh control will automatically dismiss.

This behavior closely mirrors SwiftUI’s refreshable modifier.

Usage Example#

1<List
2  navigationTitle="Refreshable List"
3  navigationBarTitleDisplayMode="inline"
4  refreshable={refresh}
5/>

Full Example#

1function Example() {
2  const [data, setData] = useState(generateRandomList)
3
4  function generateRandomList() {
5    const data: number[] = []
6    const count = Math.ceil(Math.random() * 100 + 10)
7
8    for (let i = 0; i < count; i++) {
9      const num = Math.ceil(Math.random() * 1000)
10      data.push(num)
11    }
12
13    return data
14  }
15
16  async function refresh() {
17    return new Promise<void>(resolve => {
18      setTimeout(() => {
19        setData(generateRandomList())
20        resolve()
21      }, 2000)
22    })
23  }
24
25  return <NavigationStack>
26    <List
27      navigationTitle="Refreshable List"
28      navigationBarTitleDisplayMode="inline"
29      refreshable={refresh}
30    >
31      <Section header={
32        <Text textCase={null}>Pull down to refresh</Text>
33      }>
34        {data.map(item =>
35          <Text>Number: {item}</Text>
36        )}
37      </Section>
38    </List>
39  </NavigationStack>
40}

Behavior Notes#

• The refreshable function must return a Promise<void>. The refresh control remains visible until the promise resolves.

• Use await inside the refresh function to perform async tasks:

  1refreshable={async () => {
  2  const result = await fetchData()
  3  updateState(result)
  4}}

• This modifier is only effective on scrollable containers, such as <List>.

• You should update the relevant state inside the handler to reflect new data.

• Avoid long-running or blocking tasks without feedback; always resolve the promise in a timely manner to dismiss the refresh spinner.

Best Practices#

• Keep refresh logic short and efficient.

• Always resolve the promise to ensure the UI doesn’t hang.

• If needed, use a short delay to simulate refresh animations during development:

  1await new Promise(resolve => setTimeout(resolve, 1000))