Sticky header list

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/sticky-header-list.json

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated match your Expo SDK. Files land in components/goodui-native/sticky-header-list.

Usage

import { Text, View } from "react-native";
import { StickyHeaderList, type StickySection } from "@/components/goodui-native/sticky-header-list/sticky-header-list";

type Contact = { id: string; name: string };

export function Contacts({ sections }: { sections: StickySection<Contact>[] }) {
  return (
    <StickyHeaderList
      accessibilityLabel="Contacts"
      sections={sections}
      keyExtractor={(c) => c.id}
      itemHeight={56}
      style={{ flex: 1 }}
      renderItem={({ item }) => (
        <View style={{ paddingHorizontal: 16 }}>
          <Text>{item.name}</Text>
        </View>
      )}
    />
  );
}

When to use

Examples

<StickyHeaderList
  sections={contacts}
  indexLetters={"ABCDEFGHIJKLMNOPQRSTUVWXYZ#".split("")}
  keyExtractor={(c) => c.id}
  ListHeaderComponent={<SearchBar placeholder="Search contacts" />}
  renderItem={({ item }) => <ContactRow contact={item} />}
/>

<StickyHeaderList
  sections={days}
  showIndex={false}
  keyExtractor={(t) => t.id}
  renderItem={({ item }) => <TransactionRow txn={item} />}
/>

API reference

Motion and haptics

• •Each header's stuck look is interpolated from the scroll position on the UI thread over 12 pt: the title scales to 0.8 from its leading edge and the stuck surface with its hairline fades in; scrolling back reverses it.
• •On the web the stuck surface turns translucent over a backdrop blur, so rows scrolling under it frost.
• •Index: touching it springs a 56 pt letter bubble out beside the finger (snappy), which follows the finger and fades away on release; the list jumps without animation, like the system contacts list.
• •Reduced motion: the bubble fades in without scaling; the stuck transition is tied to scrolling and stays.

• •Haptic: select for each letter the finger crosses on the index and for each keyboard or screen reader step (haptic={false} silences it)

• •Built on SectionList (virtualized) with getItemLayout from the fixed heights, so jumps to any section are exact and instant.
• •The scroll handler and every header animation run on the UI thread; React state changes only when the index letter changes.

Accessibility

• •Section headers have the header role, so screen readers can move by heading.
• •The index is one adjustable element named 'Section index' whose value is the current letter; increment and decrement move to the next and previous section that exists, and the letter is announced.
• •On the web the index is a focusable slider with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext; arrow keys move between sections.
• •The large letter bubble is decorative and hidden from screen readers.

Notes for AI

Related