Skip to content

Button - Composition over Configuration #83762

Closed
18 of 18 issues completed
Closed

Description

@mountiny

Thread here https://expensify.slack.com/archives/C08CZDJFJ77/p1772185682696469

Problem

The Button component currently has 53 props, mixing concerns across three domains:

  • Text configuration (5 props): text, textStyles, textHoverStyles, primaryTextNumberOfLines, secondLineText
  • Icon configuration (8 props): icon, iconRight, iconFill, iconHoverFill, iconStyles, iconRightStyles, iconWrapperStyles, shouldShowRightIcon
  • Button behavior/styling (35+ props): sizes, variants, events, layout, keyboard, state

This makes it difficult to extend. For example, in the Domain Control project, we need to place a DotIndicator next to the button text in ButtonWithDropdownMenu for RBR. The dot must appear on the left side of the text, requiring two icons with different fill styles — impossible today without adding yet more props.

Proposal

Apply the Compound Component pattern (composition over configuration). Extract text and icon responsibilities into sub-components:

// New interface
<Button onPress={handlePress} success>
  <Button.Icon src={Expensicons.Plus} />
  <Button.Text>Create expense</Button.Text>
  <Button.Icon src={Expensicons.DownArrow} />
</Button>

// With DotIndicator (the motivating use case)
<Button onPress={handlePress} success>
  <Button.Icon src={Expensicons.DotIndicator} fill={theme.danger} />
  <Button.Text>Submit</Button.Text>
  <Button.Icon src={Expensicons.DownArrow} />
</Button>

Button keeps its own props (styling, events, state, accessibility) but delegates content layout to children.

Benefits

  1. Extensibility without prop explosion — new content arrangements (multiple icons, indicators, badges) require zero new Button props
  2. Fewer unnecessary re-renders — individual sub-components can be memoized independently; today, any prop change triggers a full Button re-render
  3. Clearer API — the JSX tree visually communicates what the button contains
  4. Easier code review — changes to icon or text behavior are scoped to their sub-component

Migration Strategy

The migration must be incremental to avoid regressions across the ~45 files (72 instances) that use Button today:

  1. Phase 1 — Build the compound components alongside the existing props API. The old props-based rendering continues to work unchanged. Introduce Button.Icon, Button.Text (and potentially Button.SecondaryText) as sub-components.
  2. Phase 2 — Deprecate old text/icon props. Mark the 13 text/icon props as @deprecated in TypeScript. Add an ESLint rule (or no-restricted-syntax config) that warns on the deprecated props to guide contributors toward the new API.
  3. Phase 3 — Incremental file-by-file migration. Each PR migrates a handful of files. This can be distributed across contributors.
  4. Phase 4 — Remove deprecated props once all usages are migrated.

Scope

Issue OwnerCurrent Issue Owner: @mallenexpensify
Issue OwnerCurrent Issue Owner: @mallenexpensify

Activity

  1. war-in commented on Mar 2, 2026

    @war-in
    Contributor

    Hi! Draft PR is prepared and being reviewed by @dariusz-biela and @adhorodyski, thank you both!

    I'm currently involved in React Native upgrade and Domain control projects, so I handed this task to @Guccio163, who'll take care of it. That way, we won't block it on me and we can iterate faster

  2. melvin-bot commented on Mar 6, 2026

    @melvin-bot

    @ZhenjaHorbach Uh oh! This issue is overdue by 2 days. Don't forget to update your issues!

  3. 165 remaining items

  4. MelvinBot commented on Aug 18, 2026

    @MelvinBot
    Contributor

    Created the sub-issue for #98861 and linked it under this tracking issue:

    #98878 — Button migration batch 10: leftover files after census re-scan + BaseWidgetItem public API

    It follows the existing Button migration batch N format (matching batches 1–9), captures the PR's scope (44 leftover files from the census re-scan, BaseWidgetItem's buttonProps public API + its 14 callers, and the ButtonIcon accessibilityLabel addition), and is attached as a native sub-issue of this one. Assigned to Guccio163 and ZhenjaHorbach.

    Let me know if you'd like the title, scope notes, or assignees adjusted.

  5. ZhenjaHorbach commented on Aug 18, 2026

    @ZhenjaHorbach
    Contributor

    Oh
    It works 😁
    Nice

  6. mountiny commented on Aug 18, 2026

    @mountiny
    ContributorAuthor

    Yep sounds good

  7. Guccio163 commented on Aug 20, 2026

    @Guccio163
    Contributor

    @MelvinBot create a new sub-issue, for migrating success/danger props to variant in Button wrappers + other button-specific props passed by wrappers that has changes in Button component.

  8. MelvinBot commented on Aug 20, 2026

    @MelvinBot
    Contributor

    Created the sub-issue and linked it as a native sub-issue under this tracker:

    #99057 — Button wrappers: align legacy button-specific props (success/danger → variant) in ConfirmModal & FormAlertWithSubmitButton

    This covers the "fuller alignment" the plan flagged as a separate decision — renaming a wrapper's own public props to the composed conventions. I scoped it to the wrappers that aren't already handled:

    • ConfirmModal → ConfirmContent — both expose public success/danger booleans and ConfirmContent still renders the old @components/Button. Collapse to a single variant prop + migrate the internal Button. (~16 caller files pass success/danger.)
    • FormAlertWithSubmitButton — still on the old Button; forwards the same concepts under isSubmitActionDangerous → danger, useSmallerSubmitButtonSize → medium/large, shouldBlendOpacity, and hardcodes success. Migrate the internal Button to composed conventions (variant/size/blendOpacity). (~45 caller files.)

    Deliberately excluded (already covered):

    Labeled Weekly + Task and assigned to Guccio163, ZhenjaHorbach, and mountiny to match the sibling sub-issues. Let me know if you'd like the scope adjusted (e.g. keeping FormAlertWithSubmitButton's domain-named public props vs. renaming them).


    view run

  9. ZhenjaHorbach commented on Aug 31, 2026

    @ZhenjaHorbach
    Contributor

    The last PR is left!

  10. melvin-bot commented on Sep 23, 2026

    @melvin-bot

    This issue has not been updated in over 15 days. @mountiny, @war-in, @ZhenjaHorbach, @Guccio163 eroding to Monthly issue.

    P.S. Is everyone reading this sure this is really a near-term priority? Be brave: if you disagree, go ahead and close it out. If someone disagrees, they'll reopen it, and if they don't: one less thing to do!

  11. expensify-chore-bot commented on Nov 19, 2026

    @expensify-chore-bot

    @mountiny, @war-in, @ZhenjaHorbach, @Guccio163, this Monthly task hasn't been acted upon in 6 weeks; closing.

    If you disagree, feel encouraged to reopen it -- but pick your least important issue to close instead.

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

Metadata

Metadata

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions