Fetching Data: Loading, Error and Empty States

Up to now, Trailhead’s data has lived on the phone. The next feature, a catalog of trails near you, comes from a server. On a laptop with office Wi-Fi, a request is a formality. On a phone at a trailhead with one bar of signal, it’s the slowest and least reliable thing your app does: requests take seconds, fail halfway, or never come back. Designing for that is most of the work.

Four states, one value

Every screen that loads data has at least four states the user can see: loading, error, empty (it loaded, and there’s nothing), and success. Model them as one value, so impossible combinations can’t happen:

export type Trail = { id: string; name: string; lengthKm: number; difficulty: 'easy' | 'moderate' | 'hard' };

export type Load<T> =
  | { status: 'loading' }
  | { status: 'error'; message: string }
  | { status: 'success'; data: T };

Empty isn’t a separate status; it’s success with zero items, and the screen decides how to show it.

Fetching with cleanup

import { useCallback, useEffect, useState } from 'react';
import { ActivityIndicator, FlatList, Pressable, Text, View } from 'react-native';
import type { Load, Trail } from '../../lib/types';

const API = process.env.EXPO_PUBLIC_API_URL;

async function getTrails(signal: AbortSignal): Promise<Trail[]> {
  const res = await fetch(`${API}/trails?near=current`, { signal });
  if (!res.ok) throw new Error(`Server responded ${res.status}`);
  return res.json();
}

export default function Explore() {
  const [state, setState] = useState<Load<Trail[]>>({ status: 'loading' });
  const [attempt, setAttempt] = useState(0);
  const retry = useCallback(() => setAttempt((n) => n + 1), []);

  useEffect(() => {
    const controller = new AbortController();
    setState({ status: 'loading' });
    getTrails(controller.signal)
      .then((data) => setState({ status: 'success', data }))
      .catch(() => {
        if (controller.signal.aborted) return;
        setState({ status: 'error', message: 'Could not load trails. Check your connection and try again.' });
      });
    return () => controller.abort();
  }, [attempt]);

  if (state.status === 'loading') return <ActivityIndicator style={{ flex: 1 }} size="large" />;

  if (state.status === 'error') {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center', gap: 12, padding: 24 }}>
        <Text style={{ textAlign: 'center' }}>{state.message}</Text>
        <Pressable onPress={retry} accessibilityRole="button"><Text>Try again</Text></Pressable>
      </View>
    );
  }

  return (
    <FlatList
      data={state.data}
      keyExtractor={(t) => t.id}
      renderItem={({ item }) => <Text style={{ padding: 16 }}>{item.name} · {item.lengthKm} km</Text>}
      ListEmptyComponent={<Text style={{ padding: 24 }}>No trails within 50 km. Try a wider search.</Text>}
    />
  );
}

Three details carry the weight. res.ok is checked by hand, because fetch treats a 500 as a successful delivery of bad news. The AbortController cancels the request in the cleanup, so leaving the screen (or retrying) never lets a stale response overwrite a fresh one. And the error message tells the user what to do, rather than printing TypeError: Network request failed.

EXPO_PUBLIC_API_URL comes from a .env file. Variables prefixed with EXPO_PUBLIC_ are inlined into the JavaScript bundle, which also means they’re readable by anyone who unpacks your app. Put URLs there, never secret keys.

Pull to refresh and slow networks

Users expect to drag a list down to reload it. FlatList supports that with two props:

<FlatList
  // …
  refreshing={refreshing}
  onRefresh={async () => {
    setRefreshing(true);
    try { setState({ status: 'success', data: await getTrails(new AbortController().signal) }); }
    catch { /* keep the old list and show a short "Couldn't refresh" message */ }
    finally { setRefreshing(false); }
  }}
/>

A refresh keeps the old list visible while it loads, which is friendlier than the full-screen spinner of the first load. If the refresh fails, keep the old data and show a short message, instead of replacing a perfectly good list with an error screen.

Flaky networks also argue for automatic retries with a growing delay between attempts (1 s, 2 s, 4 s), so a brief signal drop recovers by itself. Only retry what can succeed later: a timeout or a 503 might, but a 404 or a 401 won’t, so failing fast is kinder. You’ll write that helper in the exercise.

Offline is a normal state, not an error

For a hiking app, no signal is the expected condition for hours at a time. Treat it that way. Show the last list you loaded, with a quiet banner saying when it was updated, instead of an error screen. Let users keep logging hikes, save them on the device, and send them when the connection returns. The community package @react-native-community/netinfo tells you whether the device is connected and notifies you when that changes, which is the moment to retry queued work.

None of that needs to be clever on day one. What matters is the decision: for each screen, what does the user see with no network? Write the answer down before writing the fetch, and design the empty, error and offline states with the same care as the happy path.

When to use a data library

The code above is fine for one screen. Across a real app you’d repeat it everywhere, and you’d still lack caching (revisit a screen and see data instantly), request deduplication, background refetching and retries. TanStack Query handles all of that with useQuery, and its docs include the small React Native setup that refetches when the app returns to the foreground. Learn the manual version first so you know what the library is doing, then use the library in production.

Next: data that has to survive without any network at all, stored on the device.