Skip to content

refactor(list-item): improve layout system and remove implicit child composition #4930

Description

@ruben-rebelo

Refactor ListItem to improve Material Design 3 compliance, remove problematic children patterns, improve performance characteristics, and modernize the public API.

Problems

  • Current API relies heavily on children composition in ways that are difficult to optimize
  • Internal layout logic is tightly coupled to arbitrary child structures
  • MD3 behaviors and visuals are not fully aligned with current Material guidelines
  • Rendering performance can degrade in large lists or frequently updated screens
  • Type safety and discoverability of the API can be improved
  • The component has inconsistent behavior between platforms and edge cases

Focus Areas

  • Replace arbitrary child composition with explicit slots
  • Improve left/right accessory APIs
  • Standardize spacing and density
  • Improve multiline layout behavior
  • Improve virtualization friendliness

Proposed API Direction

Instead of:

<List.Item> <CustomContent /> </List.Item>

Prefer:

<List.Item title="Title" description="Description" left={...} right={...} />

Performance Opportunities

  • Improve rendering in FlatList usage
  • Memoize accessories
  • Reduce layout passes
  • Avoid child traversal

Activity

  1. adrcotfas commented on May 15, 2026

    @adrcotfas
    Collaborator

    Important

    See #4949 for more details

  2. adam-sajko commented on Aug 25, 2026

    @adam-sajko

    Looking at this from the #4976 side.

    The child composition is in List.Accordion, not in List.Item. List.Item props are $RemoveChildren<typeof TouchableRipple> and the only React.Children in the folder is the accordion one, which #5018 covers. title / description / left / right from Proposed API Direction are on main already too.

    The other points are real though. left and right are render props so the caller can't memoize them, that is #5042. There is no React.memo on List.Item either. And on the platform side, alignToTop runs off onTextLayout, which react-native-web doesn't implement, so multiline alignment only works on native. Spacing and multiline layout are in #5041.

    So is the composition part meant for the Accordion? Otherwise I would narrow this down to the memo and the web gap.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions