React Native Patterns

Overview

Patterns for building maintainable React Native components. Covers touch interactions (Pressable), list rendering (FlashList), modal patterns (bottom sheets), accessibility, navigation, and RN-specific requirements that differ from web React.

For React web patterns (hooks, context, composition), see the react-patterns skill.

Workflows

Building an interactive screen:

1. • Set up SafeAreaView or apply safe area insets
2. • Use Pressable for all interactive elements (44pt minimum)
3. • Add haptic feedback on primary actions
4. • Use FlashList for lists, ScrollView for fixed content
5. • Implement bottom sheet for detail/modal views
6. • Add accessibility labels to all interactive elements
7. • Test on device for touch targets and scroll performance

Guidance

Pressable (not TouchableOpacity)

Pressable is the standard touch component. TouchableOpacity is deprecated.

Key principles:

• •44pt minimum touch target on all interactive elements
• •Use hitSlop to expand touch area beyond visual bounds: hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
• •Style feedback via style function: style={({ pressed }) => [pressed && { opacity: 0.7 }]}
• •Or use NativeWind: className="active:opacity-70"
• •Add haptics on press for primary actions: onPress={() => { Haptics.impactAsync(); doAction(); }}

Text-Only Strings Rule

React Native requires all visible text to be wrapped in <Text>:

✅ <View><Text>Hello</Text></View>
❌ <View>Hello</View>  // Crashes at runtime

This applies to conditional renders, string interpolation, and JSX expressions. Always wrap strings in Text.

ScrollView Patterns

Two className targets:

• •className — outer container (flex, background)
• •contentContainerClassName — inner content (padding, gap, alignment)

Use ScrollView for screens with fixed, non-dynamic content. Use FlashList for dynamic lists.

showsVerticalScrollIndicator={false} for cleaner visual when custom scroll indicators are used.

FlashList Patterns

High-performance list rendering:

• •estimatedItemSize is required — estimate average item height in points
• •renderItem receives { item, index } — keep render function pure
• •keyExtractor — use unique string ID from data
• •contentContainerClassName — NativeWind styling for inner content
• •ItemSeparatorComponent — consistent spacing between items
• •ListEmptyComponent — graceful empty state

Bottom Sheet as Modal

@gorhom/bottom-sheet replaces web modal dialogs:

• •Define snapPoints array: ['25%', '50%', '90%']
• •Use BottomSheetModal with BottomSheetModalProvider for imperative control
• •BottomSheetScrollView for scrollable sheet content
• •BottomSheetBackdrop for press-to-dismiss overlay
• •Present: bottomSheetRef.current?.present()
• •Dismiss: bottomSheetRef.current?.dismiss()

expo-image Patterns

Use for all image display:

• •Remote images: source={{ uri: 'https://...' }}
• •Local images: source={require('../assets/image.png')}
• •Blurhash placeholder: placeholder="LKO2?U%2Tw=w]~RBVZRi}" for loading state
• •contentFit="cover" for card thumbnails, "contain" for full images
• •transition={300} for smooth fade-in on load

Accessibility

Required accessibility props for interactive elements:

Guidelines:

• •All Pressable elements need accessibilityLabel
• •Images need accessibilityLabel describing content
• •Use accessibilityRole="header" for screen titles
• •Toggle/checkbox: set accessibilityState={{ checked: isChecked }}
• •Disabled elements: accessibilityState={{ disabled: true }}

Chat-Forward Component Patterns

Demos use a chat-forward interface where the conversation thread is the primary UI.

Chat Screen Layout

Three zones:

• •Header: Minimal — title, back nav, optional status. Uses safe area top inset.
• •Message stream: FlashList or inverted ScrollView for the conversation. Agent and user messages alternate. Rich content is embedded within agent message components.
• •Input bar: Text input pinned to bottom. Uses KeyboardAvoidingView (iOS) or android:windowSoftInputMode="adjustResize". Safe area bottom inset for home indicator. Optional quick-action chips above the text field.

Message Bubble

Agent and user bubbles have distinct styling (alignment, color, shape):

• •Agent bubble: Left-aligned, neutral background, can contain child components (cards, summaries, action buttons)
• •User bubble: Right-aligned, accent background, text only
• •Bubbles animate in with FadeInDown.duration(300) on append

Inline Rich Card

Compact data card rendered as a child of an agent message bubble:

• •Photo thumbnail (expo-image) + title + key metric + status badge
• •Tappable — opens bottom sheet with full detail
• •For card sets: horizontal ScrollView within the message, or vertical stack
• •Stagger animation: FadeInDown.delay(index * 50).duration(300)

Summary Card

Running totals/status that updates as the conversation progresses:

• •Shows aggregated state: Keep ($X), Sell ($Y), Donate ($Z), Progress (N%)
• •Can be rendered as a sticky element above the input bar for persistent visibility
• •Content crossfades on update (150ms timing)

Prompt Card

Agent suggestion with embedded action buttons:

• •Text prompt + 1-3 action buttons inline
• •Buttons are Pressable with 44pt targets, haptic on press
• •After tap, the prompt card updates to show the confirmed action
• •E.g., "Want me to find pickup options?" → [Yes] [Not now]

Comparison View

Before/after or side-by-side content within a message:

• •Two expo-image instances with labels (Before / After)
• •Optional delta annotation (e.g., "New scratch detected")

Timeline View

Chronological event list rendered inline within an agent message:

• •Compact: date + title + icon per event
• •Expandable: tap to show detail (inline expand or bottom sheet)
• •Vertical line connector between events

Notification Message

Proactive agent alert that appears as a new message in the thread:

• •Distinctive styling (icon + emphasis color) to differentiate from regular agent messages
• •Can contain inline action buttons
• •E.g., "Storm season starts in 6 weeks. Your basement still shows moisture risk."

Navigation from Components

Use Expo Router's useRouter() hook:

• •router.push('/path') — navigate forward (adds to stack)
• •router.replace('/path') — replace current screen
• •router.back() — go back
• •router.canGoBack() — check if back navigation possible
• •Pass params: router.push({ pathname: '/detail/[id]', params: { id: '123' } })

Best Practices

• •Always use Pressable over TouchableOpacity or TouchableHighlight
• •Enforce 44pt minimum touch targets — use hitSlop when visual is smaller
• •Wrap every visible string in <Text> — no bare strings in JSX
• •Use expo-image for all images (never RN Image)
• •Add accessibilityLabel to every interactive element
• •Use FlashList with estimatedItemSize for any list with >10 items
• •Use contentContainerClassName for ScrollView/FlashList inner styling
• •Add haptic feedback sparingly — primary actions only
• •Test touch targets on real device (simulator touch is imprecise)

Anti-Patterns

• •Using TouchableOpacity (deprecated — use Pressable)
• •Touch targets smaller than 44pt without hitSlop compensation
• •Bare strings without <Text> wrapper (runtime crash)
• •Using RN Image instead of expo-image (no caching, no blurhash)
• •Forgetting estimatedItemSize on FlashList
• •Using FlatList for large datasets (FlashList is faster)
• •Missing accessibilityLabel on interactive elements
• •Using Alert.alert() for complex choices (use bottom sheet instead)
• •Padding on className of ScrollView (use contentContainerClassName)
• •Inline anonymous functions in FlashList renderItem (causes re-renders — extract component)