[BUG] Clicking first item causes unexpected scroll/visual glitch when item moves to end of list

[blazejkustra]

Description

When clicking on the first visible item in a LegendList (which triggers a state update that moves the item to the end of the data array), there's unexpected visual behavior on both web and iOS platforms.

Expected Behavior

When an item is pressed and moved to the end of the list via state update, the list should update without any visual glitches or unexpected scroll position changes.

Actual Behavior

Clicking on the first item causes weird visual behavior - the list appears to jump or glitch when the item is moved to the end of the data array.

web:

web.mov

ios:

ios.MP4

Reproduction

import React, { useCallback, useState } from 'react';
import { View, StyleSheet, Text, Pressable } from 'react-native';
import { LegendList } from '@legendapp/list';

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

const initialData: Item[] = Array.from({ length: 50 }, (_, i) => ({
  id: String(i + 1),
  name: `Item ${i + 1}`,
}));

function MinimalReproduction() {
  const [data, setData] = useState(initialData);

  const handleScroll = useCallback(() => {
    // scroll handler
  }, []);

  const handleRefresh = useCallback(() => {
    // refresh handler
  }, []);

  const handleItemPress = useCallback((item: Item) => {
    setData((prev) => {
      const filtered = prev.filter((i) => i.id !== item.id);
      return [...filtered, item];
    });
  }, []);

  const renderItem = useCallback(
    ({ item }: { item: Item }) => (
      <Pressable style={styles.item} onPress={() => handleItemPress(item)}>
        <Text style={styles.itemText}>{item.name}</Text>
      </Pressable>
    ),
    [handleItemPress],
  );

  return (
    <View style={styles.container}>
      <LegendList
        contentContainerStyle={styles.contentContainer}
        ListHeaderComponent={<View style={styles.header} />}
        onScroll={handleScroll}
        scrollEventThrottle={16}
        keyboardDismissMode="on-drag"
        refreshing={false}
        onRefresh={handleRefresh}
        data={data}
        renderItem={renderItem}
        keyExtractor={(item: Item) => item.id}
        recycleItems
        maintainVisibleContentPosition
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  contentContainer: {
    padding: 16,
  },
  header: {
    height: 100,
  },
  item: {
    height: 50,
    marginBottom: 8,
    backgroundColor: '#eee',
    justifyContent: 'center',
    paddingHorizontal: 16,
  },
  itemText: {
    fontSize: 16,
  },
});

export default MinimalReproduction;

Steps to Reproduce

1. Render the component above
2. Click/tap on the first visible item in the list
3. Observe the visual glitch/jump as the item is moved to the end

Environment

• Platforms affected: Web, iOS (possibly android too)
• version: v2.0.19

[blazejkustra]

I'm also experiencing this crash when using the app (not minimal reproduction). I can't narrow it down though 😢

ScreenRecording_12-27-2025.21-13-20_1.MP4

[blazejkustra]

Same issue on 3.0.0-beta.15

[jmeistrich]

This is happening because of maintainVisibleContentPosition. In the latest beta you can safely remove that prop, and this should stop happening.

Before recent betas this prop did two things:

1. When items change size above the scroll area it keeps items in view in the same place
2. When the data changes it tries to keep the first item in the same place on screen

That #2 is causing the problem you're seeing here. In the latest beta I split the behavior into two different things, and changed the default so that #1 happens automatically and #2 does not. So if you just remove the prop then it should behave as you expect.

That said, it should not be blanking like that when doing the #2 behavior. So I will look into that.

[jmeistrich]

And that crash is happening when calling the onScroll prop from the throttling logic. Are you conditionally setting an onScroll prop?

[blazejkustra]

And that crash is happening when calling the onScroll prop from the throttling logic. Are you conditionally setting an onScroll prop?

I'm using useAnimatedScrollHandler from reanimated, maybe this is the reason 🤔 Thank you for the swift response @jmeistrich!

my custom hook with `useAnimatedScrollHandler`

import {
  clamp,
  useAnimatedScrollHandler,
  useSharedValue,
  withTiming,
  SharedValue,
} from 'react-native-reanimated';

const TOO_CLOSE_TO_TOP_DISTANCE = 10;
const TOO_CLOSE_TO_BOTTOM_DISTANCE = 10;
const ANIMATION_DURATION_IN_MS = 300;
const BUTTONS_DEFAULT_OFFSET = 0;
const BUTTONS_HIDDEN_OFFSET = 150;

type UseScrollAnimationResult = {
  buttonsOffset: SharedValue<number>;
  scrollHandler: ReturnType<typeof useAnimatedScrollHandler>;
};

/**
 * Hook that manages scroll-based animation for hiding/showing buttons.
 * Buttons hide when scrolling down and show when scrolling up.
 */
export default function useScrollAnimation(windowHeight: number): UseScrollAnimationResult {
  const scrollOffset = useSharedValue(0);
  const buttonsOffset = useSharedValue(BUTTONS_DEFAULT_OFFSET);

  const scrollHandler = useAnimatedScrollHandler(
    {
      onScroll: (event) => {
        const { contentOffset, layoutMeasurement, contentSize } = event;

        if (windowHeight > contentSize.height) {
          buttonsOffset.set(BUTTONS_DEFAULT_OFFSET);
          return;
        }

        const currentOffset = contentOffset.y;
        const isScrollingDown = currentOffset > scrollOffset.get();
        const distanceScrolled = currentOffset - scrollOffset.get();

        if (isScrollingDown && contentOffset.y > TOO_CLOSE_TO_TOP_DISTANCE) {
          buttonsOffset.set(
            clamp(
              buttonsOffset.get() + distanceScrolled,
              BUTTONS_DEFAULT_OFFSET,
              BUTTONS_HIDDEN_OFFSET,
            ),
          );
        } else if (
          !isScrollingDown &&
          distanceScrolled < 0 &&
          contentOffset.y + layoutMeasurement.height <
            contentSize.height - TOO_CLOSE_TO_BOTTOM_DISTANCE
        ) {
          buttonsOffset.set(
            withTiming(BUTTONS_DEFAULT_OFFSET, { duration: ANIMATION_DURATION_IN_MS }),
          );
        }

        scrollOffset.set(currentOffset);
      },
    },
    [windowHeight],
  );

  return {
    buttonsOffset,
    scrollHandler,
  };
}