[Android] - Can't access ShadowNode in FlatList with horizontal prop

[jpudysz]

Description

I've found a discrepancy between Android and iOS platforms.
When the horizontal prop is set, the ref returned during unmount has a nullable NativeState property which breaks ShadowNode cleanup required by Unistyles.

How I access the NativeState for FlatList components:

ref?.getScrollResponder?.()?.getNativeScrollRef?.()?.__internalInstanceHandle?.stateNode?.node

Link

and then in C++:

ShadowNode::Shared shadowNode = shadowNodeFromValue(rt, args[0]); // args[0] is jsi::Value with NativeState

Desired behaviour:
I should be able to access ShadowNode during cleanup to perform own cleanups as in any other component or without horizontal prop.

Steps to reproduce

1. Install the provided repro
2. Run the app on Android and open the debugger to view console.log output
3. You should see two logs:

   Mount
   NativeState: ✅
   

4. Tap the Reload button
5. Notice that NativeState is no longer present:

   Unmount
   NativeState: ❌
   

6. Run the app on iOS and open the debugger to view console.log output
7. Verify that NativeState is present in both the mount and unmount phases
8. Comment out the horizontal prop
9. Verify that NativeState is present in both the mount and unmount phases on both iOS and Android

React Native Version

0.79.2

Affected Platforms

Runtime - Android

Areas

Fabric - The New Renderer

Output of npx @react-native-community/cli info

System:
  OS: macOS 15.3.2
  CPU: (12) arm64 Apple M3 Pro
  Memory: 2.15 GB / 36.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 23.5.0
    path: /opt/homebrew/bin/node
  Yarn:
    version: 1.22.22
    path: /opt/homebrew/bin/yarn
  npm:
    version: 10.9.2
    path: /opt/homebrew/bin/npm
  Watchman:
    version: 2024.12.02.00
    path: /opt/homebrew/bin/watchman
Managers:
  CocoaPods:
    version: 1.16.2
    path: /opt/homebrew/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 24.4
      - iOS 18.4
      - macOS 15.4
      - tvOS 18.4
      - visionOS 2.4
      - watchOS 11.4
  Android SDK:
    API Levels:
      - "23"
      - "28"
      - "29"
      - "30"
      - "33"
      - "34"
      - "35"
    Build Tools:
      - 30.0.3
      - 34.0.0
      - 35.0.0
    System Images:
      - android-23 | ARM 64 v8a
      - android-24 | Google APIs ARM 64 v8a
      - android-26 | Google APIs ARM 64 v8a
      - android-28 | ARM 64 v8a
      - android-29 | ARM 64 v8a
      - android-30 | ARM 64 v8a
      - android-30 | Google APIs ARM 64 v8a
      - android-34 | Android TV ARM 64 v8a
      - android-34 | ARM 64 v8a
      - android-34 | Google APIs ARM 64 v8a
      - android-35 | Google APIs ARM 64 v8a
      - android-35 | Google Play ARM 64 v8a
    Android NDK: Not Found
IDEs:
  Android Studio: 2024.3 AI-243.25659.59.2432.13404313
  Xcode:
    version: 16.3/16E140
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.11
    path: /usr/bin/javac
  Ruby:
    version: 2.6.10
    path: /usr/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 18.0.0
    wanted: 18.0.0
  react:
    installed: 19.0.0
    wanted: 19.0.0
  react-native:
    installed: 0.79.2
    wanted: 0.79.2
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true

Stacktrace or Logs

No crash

MANDATORY Reproducer

https://github.com/jpudysz/react-native-horizontal-flatlist-repro

Screenshots and Videos

Android + horizontal prop

Android + no horizontal prop

iOS + horizontal prop

iOS + no horizontal prop

[cortinico]

When the horizontal prop is set, the ref returned during unmount has a nullable NativeState property which breaks ShadowNode cleanup required by Unistyles.

Can you elaborate more on the ShadowNode cleanup that is required by Unistyles?

Not all shadow nodes have a state. The thing you're facing here is that the AndroidHorizontalScrollContentViewShadowNode doesn't have a state:

react-native/packages/react-native/ReactCommon/react/renderer/components/scrollview/platform/android/react/renderer/components/scrollview/AndroidHorizontalScrollContentViewShadowNode.h

Lines 17 to 20 in 14a2132

	class AndroidHorizontalScrollContentViewShadowNode final
	: public ConcreteViewShadowNode<
	AndroidHorizontalScrollContentViewShadowNodeComponentName,
	ViewProps> {

For ShadowNodes that don't have a state, we initialize it to null:

react-native/packages/react-native/ReactCommon/react/renderer/core/ConcreteComponentDescriptor.h

Lines 140 to 167 in 14a2132

	virtual State::Shared createInitialState(
	const Props::Shared& props,
	const ShadowNodeFamily::Shared& family) const override {
	if (std::is_same<ConcreteStateData, StateData>::value) {
	// Default case: Returning `null` for nodes that don't use `State`.
	return nullptr;
	}
	return std::make_shared<ConcreteState>(
	std::make_shared<const ConcreteStateData>(
	ConcreteShadowNode::initialStateData(props, family, *this)),
	family);
	}
	virtual State::Shared createState(
	const ShadowNodeFamily& family,
	const StateData::Shared& data) const override {
	if (std::is_same<ConcreteStateData, StateData>::value) {
	// Default case: Returning `null` for nodes that don't use `State`.
	return nullptr;
	}
	react_native_assert(data && "Provided `data` is nullptr.");
	return std::make_shared<const ConcreteState>(
	std::static_pointer_cast<const ConcreteStateData>(data),
	*family.getMostRecentState());
	}

In general you should not rely on internals of Fabric. I'd like to understand more what you're attempting to do as, even if I were to add a state to the AndroidHorizontalScrollContentViewShadowNode, I don't think that would be the right fix. We'll just attach an unnecessary state to a node that doesn't need it at all.

[jpudysz]

Can you elaborate more on the ShadowNode cleanup that is required by Unistyles?

Sure! In short, on the C++ side, I maintain a mapping between each ShadowNode (specifically, its ShadowNodeFamily) and the StyleSheet styles (UnistyleData) generated by Unistyles. The mapping looks like this:

std::unordered_map<const ShadowNodeFamily*, std::vector<std::shared_ptr<UnistyleData>>>

This allows me to track exactly which styles are attached to which components.

Whenever a component mounts, I register a new entry; when it unmounts, I remove it. If I don’t receive unmount information, it results in a dangling pointer and potentially dangerous state.

This std::unordered_map is essential for selective updates. For example, when a change occurs (like a color scheme update), I can efficiently identify and recalculate only the affected styles, then update the corresponding ShadowNodes from C++.

If you’re interested in a deeper explanation, you can check it out here.

Not all shadow nodes have a state

To clarify, I don’t actually need or manipulate the NativeState directly, nor do I do anything unsafe with it. However, the Android FlatList component with the horizontal prop is the only case that breaks the following pattern:

1. To obtain the NativeState, I use the function mentioned above (link).
   My approach was inspired by the React Native Animated API (reference).

2. With access to the hidden NativeState, I can forward it to C++ and retrieve the ShadowNode:

ShadowNode::Shared shadowNodeWrapper = shadowNodeFromValue(rt, args[0]);

This works for every other React Native component, except for Android FlatList with the horizontal prop. Retrieving a shared_ptr to the ShadowNode is necessary for Unistyles, but it’s always used in a non-owning way.

In general you should not rely on internals of Fabric

I completely agree!
Ideally, there would be a public API to retrieve the NativeState or directly access the ShadowNode, something like:

<View ref={ref => ref.getShadowNode()} />

Unfortunately, this isn’t currently possible. Despite this, my approach enables me to offer the React Native community unique functionality that extends the base StyleSheet API.

I’ve attached a reproduction, but to give you a broader context, here’s an example:

Suppose we have a FlatList with the horizontal prop and a style:

import React from 'react'
import { Text } from 'react-native'
import { StyleSheet } from 'react-native-unistyles'
import { FlatList } from 'react-native'

export default function HomeScreen() {
    return (
        <FlatList
            horizontal
            style={styles.list}
            data={[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}
            renderItem={({ item }) => (
                <Text style={styles.text}>
                    {item}
                </Text>
            )}
        />
    )
}

const styles = StyleSheet.create(theme => ({
    list: {
        backgroundColor: theme.colors.backgroundColor
    },
    text: {
        color: theme.colors.typography
    }
}))

The only difference from the standard React Native StyleSheet is that I provide a function to access the current theme. The FlatList now depends on the theme, and in the background, I connect the FlatList ref (ShadowNode) with styles.list (I'm also using NativeState to extract the shared_ptr from my style).

Because we use Unistyles, I can toggle the theme, and the FlatList will update its background color without a re-render.

Screen.Recording.2025-06-20.at.16.51.43.mov

However, on Android, there is a different behavior. Initially it looks like everything is ok:

Screen.Recording.2025-06-20.at.17.09.08.mov

But when you toggle horizontal prop based on state:

import React from 'react'
+import { Text, Button } from 'react-native'
import { StyleSheet } from 'react-native-unistyles'
import { FlatList } from 'react-native'

export default function HomeScreen() {
+ const [isHorizontal, setIsHorizontal] = React.useState(true)
    return (
+   <React.Fragment>
        <FlatList
            horizontal
            style={styles.list}
            data={[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}
            renderItem={({ item }) => (
                <Text style={styles.text}>
                    {item}
                </Text>
            )}
        />
+      <Button title={isHorizontal ? 'Vertical' : 'Horizontal'} onPress={() => setIsHorizontal(!isHorizontal)} />
+   </React.Fragment>
    )
}

const styles = StyleSheet.create(theme => ({
    list: {
        backgroundColor: theme.colors.backgroundColor
    },
    text: {
        color: theme.colors.typography
    }
}))

Screen.Recording.2025-06-20.at.17.12.30.mov

There’s no NativeState that was there before toggling the horizontal prop.
It crashes here.

I could discourage users from using FlatList with the horizontal prop, but to me, this seems like a regression, since all other components work reliably. Even the corresponding iOS implementation behaves as expected.

Keep in mind, I’ve spent the past year testing all these internals to make selective updates possible. Sometimes, I encounter issues that are hard to discover in typical apps.

I hope this explanation clarifies things. Please let me know if you need any more details!

[cortinico]

I hope this explanation clarifies things. Please let me know if you need any more details!

Thank you for the thorough explanation @jpudysz, really appreciate.

As I was mentioning above, the issue is beyond FlatList on Android with horizontal: it seems like your mechanism would break for any 3p component that doesn't have a native state. Have you tried unistyle with other components that don't have a state by any chance?

[jpudysz]

This mechanism is currently enabled only for React Native components.
Third-party views must still re-render for now, but I am exploring possibilities in this area.

[cortinico]

This mechanism is currently enabled only for React Native components.

Ah ok I was missing this bit, thanks for clarifying.