Composition

Use component boundaries to keep related markup, styles, and behavior cohesive. Prefer code whose structure makes each user-visible state obvious when read from top to bottom.

Refactoring workflow

1. Identify the states a user can actually see, such as pending, error, empty, and success.
2. Sketch each state as boxes. Separate the frame shared by every state from the content that changes.
3. Extract the shared frame into a small layout component that accepts children and only the props needed by that frame.
4. Render mutually exclusive states with ordered top-level early returns.
5. Put state-specific checks and content only in the branch where they apply.
6. Let the final branch represent the fully narrowed success state.
7. Reassess the abstraction when the layout itself accumulates many conditional props.

function Layout({ children, title }: { children: ReactNode; title?: string }) {
  return (
    <Card>
      <CardHeading>{title ?? "Items"}</CardHeading>
      <CardContent>{children}</CardContent>
    </Card>
  )
}

function ItemList() {
  const { data, error, isPending } = useItems()

  if (isPending) {
    return <Layout><Skeleton /></Layout>
  }

  if (error) {
    return <Layout><ErrorMessage error={error} /></Layout>
  }

  if (!data || data.items.length === 0) {
    return <Layout><EmptyScreen /></Layout>
  }

  return (
    <Layout title={data.title}>
      {data.assignee && <UserInfo {...data.assignee} />}
      {data.items.map((item) => <Item key={item.id} {...item} />)}
    </Layout>
  )
}

Decision rules

• Keep simple optional fragments inline when they do not represent a distinct component state, such as an optional badge or assignee.
• Use early returns when branches are mutually exclusive views. Treat each return as one screen state.
• Order guards from transient or exceptional states toward the normal success state.
• Accept repeating a small layout wrapper across branches. Prefer local, readable duplication over coupled Boolean conditions.
• Preserve self-contained components when useful; data fetching and composition can coexist.
• Do not extract a component merely to hide conditions. Extract a meaningful shared boundary, then move state selection outside JSX.
• Do not replace one conditional maze with a layout component full of flags. Split or redesign the abstraction when variants stop sharing a coherent frame.

Review checklist

• Can a reader identify every user-visible state without evaluating nested JSX expressions?
• Can two mutually exclusive branches render at the same time? If so, fix the state model or guard order.
• Does every state render only the data-dependent UI valid for that state?
• Does TypeScript narrow required data by the final branch without assertions or repeated optional checks?
• Can a new state be added as one isolated branch without modifying unrelated branches?
• Does the shared layout remain simple and cohesive?

Preserve intent

Apply this pattern when it lowers cognitive load. Do not ban conditional rendering: inline conditions remain appropriate for small optional additions within one state. Optimize for clear user-visible states, sound type narrowing, and components that can evolve without cross-branch regressions.