[FEE-501] Component Composition Patterns
INFO
Composition is the primary mechanism for building complex UIs from simple components. Rather than inheritance or configuration objects, modern frontend architecture favors composing small, focused components together.
Context
When a component grows beyond a single responsibility, the instinct is often to add props: showHeader, variant, mode. This leads to "god components" with dozens of props and complex conditional rendering. Composition solves this differently -- instead of configuring one large component, you assemble multiple small ones.
Patterns
Slots / Children (Content Projection)
The parent controls what content appears inside a child component. The child controls where and how that content is rendered.
<!-- Framework-agnostic concept: slot-based composition -->
<!-- Parent decides content -->
<Card>
<CardHeader>User Profile</CardHeader>
<CardBody>
<Avatar src="user.jpg" />
<p>Welcome back, Alive.</p>
</CardBody>
</Card>
<!-- Card component defines layout, not content -->When to use: When a component provides structure (layout, styling, behavior) but the content varies per usage.
Compound Components
A set of components designed to work together, sharing implicit state through a common parent.
<!-- The Select manages state; Option and Trigger read from it -->
<Select>
<SelectTrigger>Choose a fruit</SelectTrigger>
<SelectContent>
<SelectOption value="apple">Apple</SelectOption>
<SelectOption value="banana">Banana</SelectOption>
</SelectContent>
</Select>When to use: When a group of components represents a single logical widget (select, accordion, tabs, dialog) and needs coordinated behavior.
Render Delegation (Headless Components)
A component that provides behavior and state but no UI. The consumer provides the rendering.
// Headless toggle component -- provides state, not DOM
function useToggle(initial = false) {
let isOn = initial;
return {
get isOn() { return isOn; },
toggle() { isOn = !isOn; },
setOn() { isOn = true; },
setOff() { isOn = false; },
};
}
// Consumer provides all rendering
const { isOn, toggle } = useToggle();When to use: When the behavior is reusable but the visual representation varies significantly between contexts.
Container / Presentational Split
Separate data-fetching and business logic (container) from rendering (presentational).
Container: fetches data, handles errors, manages loading state
|
v
Presentational: receives props, renders UI, emits eventsWhen to use: When a component mixes data concerns with display. The presentational component becomes easy to test in isolation and reuse with different data sources.
Best Practices
Prefer composition over inheritance for component reuse. Components MUST communicate through well-defined interfaces — props down, events up, slots for content injection — rather than sharing behavior through class hierarchies. JavaScript inheritance creates tight coupling that makes components harder to test and refactor independently.
Keep each component focused on one concern. A component SHOULD do one thing well: either manage data and behavior, or render UI, but not both at scale. When a component grows to handle multiple unrelated responsibilities, decompose it into smaller, focused pieces that can be composed at a higher level.
Use slot and children patterns for layout flexibility. Components that render structural wrappers (cards, panels, dialogs) SHOULD accept children rather than accepting content as props. This keeps the wrapper decoupled from the content it frames and makes the wrapping component reusable across contexts without prop changes.
Compose at the right level to avoid prop drilling. You SHOULD NOT pass state through more than two or three intermediate components. When props travel through layers of components that do not use them, it signals the component tree needs restructuring — lift composition higher, or introduce context and state management at the appropriate boundary.
Common Mistakes
Over-composing simple UIs. Not everything needs three layers of abstraction. A button that only renders text does not need a ButtonContainer, ButtonPresenter, and ButtonLabel. Compose when there is a real reason -- reuse, testability, or separation of concerns.
Creating components that are too generic too early. Build the specific version first. Extract the generic pattern only when you have 2-3 concrete uses that share the same structure. Premature generalization creates components that serve no use case well.
Related FEEs
- FEE-500 Component Architecture & Design Patterns Overview
- FEE-502 Reactive State & Signals
- FEE-600 State Management Overview