Repository navigation
feat: modernize List related components to the latest MD3 specs #4976
Description
The list specific components are spread out in the places mentioned below.
We need a refactoring to reuse the theme tokens, update to the latest specs(https://m3.material.io/components/lists) and simplify the implementation by reusing/composing subcomponents.
The specs mention draggable, swipeable and toggleable list items.
Given the complexity, this task can be split into multiple PRs.
Current State
List Accordion
MD3 spec: Lists (expand interaction)
Specs link: https://m3.material.io/components/lists/specs
Color tokens
- Description / supporting text:
onSurfaceVariant✅ - Title color when expanded: hardcoded to
primary; spec label text usesonSurfaceregardless of expand state - Left icon color when expanded: hardcoded to
primary; spec usesonSurfaceVariantfor leading icons - Container background:
theme.colors.background; should besurface - No selected state colors (
primaryContainerbg /onPrimaryContainertext/icon) ❌
Spacing / sizing
paddingVertical: 8(container) +marginVertical: 6(row) = 14dp each side; spec 1-line item is 56dp total height, requiring 16dp top/bottom padding ❌paddingRight: 24trailing ✅- Content
paddingLeft: 16✅ - Title and description use hardcoded
fontSize: 16/fontSize: 14; should usetheme.fonts.bodyLarge/theme.fonts.bodyMedium
Behavior
- Expand/collapse toggling via press ✅
- Controlled and uncontrolled modes ✅
- No expand/collapse animation; children appear and disappear instantly
- Chevron direction reversal is the only visual feedback for expanded state; no container highlight or shape change
- No multi-select or single-select mode
Notes
- Should be renamed to align with MD3 terminology (e.g., expandable list item) after the audit
- Animations and selected state are the most impactful missing features
List Accordion Group
MD3 spec: Lists (expand interaction – single-expand group)
Specs link: https://m3.material.io/components/lists/specs
Color tokens
No color logic of its own – delegates to List.Accordion. ✅
Spacing / sizing
No sizing logic of its own. ✅
Behavior
- At most one accordion expanded at a time (single-expand) ✅
- Controlled and uncontrolled modes ✅
- No direct MD3 equivalent; the constraint is implied by MD3 single-select list behavior ✅
Notes
- Pure context provider; no rendering of its own
- No issues beyond what is inherited from
List.Accordion
List Item
MD3 spec: Lists
Specs link: https://m3.material.io/components/lists/specs
Color tokens
- Title:
onSurface✅ - Description / supporting text:
onSurfaceVariant✅ - Leading and trailing icon color passed as
onSurfaceVariant✅ - No container background set (inherits from parent) – acceptable since list items sit on
surface✅ - No selected state: spec defines
primaryContainerbg /onPrimaryContainerlabel+icon for selected items
Spacing / sizing
paddingVertical: 8(container) +marginVertical: 6(row) = 14dp each side; spec 1-line is 56dp requiring 16dp padding each side ❌paddingRight: 24trailing ✅- Content
paddingLeft: 16✅ - Title uses hardcoded
fontSize: 16; should usetheme.fonts.bodyLarge - Description uses hardcoded
fontSize: 14; should usetheme.fonts.bodyMedium
Behavior
- State layers via
TouchableRipple✅ - Left and right render-prop slots ✅
- No overline text slot (spec anatomy includes overline above label)
- No trailing text slot
- No selected state prop
- No multi-action support (multiple independent trailing actions)
Notes
- The
left/rightrender-prop API is flexible but predates the MD3 slot model (leading / content / trailing); a typed slot API would be more aligned and enable correct padding calculations
List Section
MD3 spec: Lists (section grouping / subheader)
Specs link: https://m3.material.io/components/lists/specs
Color tokens
No color logic; delegates to ListSubheader. See ListSubheader for token review.
Spacing / sizing
marginVertical: 8on the section container – MD3 does not prescribe margin between sections; acceptable as a layout aid
Behavior
- Groups list items under an optional subheader ✅
- No MD3-specific behavior beyond grouping
Notes
- No functional issues; purely a layout container
ListSubheaderis not audited separately; its token usage should be verified against the MD3 subheader spec
Activity
adam-sajko commentedon Aug 25, 2026
Taking this one.
Related to this issue, not closing it, quite a lot is left after they land.
I think two things in the audit are off. Trailing inset is 16dp, not 24, Compose fixed the same thing in 1f11909. And vertical padding is not flat 16dp, with typescale applied it is 16 / 14 / 12 for one, two and three lines, so 56 / 72 / 88. The 14dp there today is already correct for two lines, the real bug is title and description never used the typescale at all.
Just one caveat on the three line tier: it needs
onTextLayout, which react-native-web doesn't implement, so it only works on native. That's pre-existing,alignToTopalready did nothing on web before.Left after those three: overline and trailing text slots, multi and single select mode, multi-action trailing,
ListSubheadertokens, MD3 rename and drag/swipe/toggle.Left a note on #4930 too, most of it is either
List.Accordionor spacing, so it overlaps with this one.