FlatList and virtualized lists

A FlatList only renders the rows near the viewport, so a target row further down may not exist yet - there is nothing to measure. For these, Guideway scrolls by index using the list’s scrollToIndex, then measures once the row renders.

Pass the list ref and the row index

Give useTourTarget both the list’s scrollRef and the row’s index.

import { useRef } from 'react';
import { FlatList, View, Text } from 'react-native';
import { useTourTarget } from 'guideway';

function Feed({ data }) {
  const listRef = useRef<FlatList>(null);

  return (
    <FlatList
      ref={listRef}
      data={data}
      getItemLayout={(_, index) => ({ length: ROW_H, offset: ROW_H * index, index })}
      renderItem={({ item, index }) => <Row item={item} index={index} listRef={listRef} />}
    />
  );
}

function Row({ item, index, listRef }) {
  // highlight, say, row 12 in a tour
  const ref = index === 12 ? useTourTarget('featured-row', { scrollRef: listRef, index }) : undefined;
  return (
    <View ref={ref}>
      <Text>{item.label}</Text>
    </View>
  );
}

When the featured-row step starts, Guideway calls scrollToIndex({ index: 12 }), waits for the row to render and settle, then highlights it.

Tip

Provide getItemLayout (or fixed-height rows) so scrollToIndex can jump reliably to off-screen rows without measuring them first.

For targets in a regular ScrollView, you only need scrollRef - see Auto-scroll.