Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
1# React Composition Patterns23**Version 1.0.0**4Engineering5January 202667> **Note:**8> This document is mainly for agents and LLMs to follow when maintaining,9> generating, or refactoring React codebases using composition. Humans10> may also find it useful, but guidance here is optimized for automation11> and consistency by AI-assisted workflows.1213---1415## Abstract1617Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.1819---2021## Table of Contents22231. [Component Architecture](#1-component-architecture) — **HIGH**24 - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)25 - 1.2 [Use Compound Components](#12-use-compound-components)262. [State Management](#2-state-management) — **MEDIUM**27 - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)28 - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)29 - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)303. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**31 - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)32 - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)334. [React 19 APIs](#4-react-19-apis) — **MEDIUM**34 - 4.1 [React 19 API Changes](#41-react-19-api-changes)3536---3738## 1. Component Architecture3940**Impact: HIGH**4142Fundamental patterns for structuring components to avoid prop43proliferation and enable flexible composition.4445### 1.1 Avoid Boolean Prop Proliferation4647**Impact: CRITICAL (prevents unmaintainable component variants)**4849Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize5051component behavior. Each boolean doubles possible states and creates5253unmaintainable conditional logic. Use composition instead.5455**Incorrect: boolean props create exponential complexity**5657```tsx58function Composer({59 onSubmit,60 isThread,61 channelId,62 isDMThread,63 dmId,64 isEditing,65 isForwarding,66}: Props) {67 return (68 <form>69 <Header />70 <Input />71 {isDMThread ? (72 <AlsoSendToDMField id={dmId} />73 ) : isThread ? (74 <AlsoSendToChannelField id={channelId} />75 ) : null}76 {isEditing ? <EditActions /> : isForwarding ? <ForwardActions /> : <DefaultActions />}77 <Footer onSubmit={onSubmit} />78 </form>79 )80}81```8283**Correct: composition eliminates conditionals**8485```tsx86// Channel composer87function ChannelComposer() {88 return (89 <Composer.Frame>90 <Composer.Header />91 <Composer.Input />92 <Composer.Footer>93 <Composer.Attachments />94 <Composer.Formatting />95 <Composer.Emojis />96 <Composer.Submit />97 </Composer.Footer>98 </Composer.Frame>99 )100}101102// Thread composer - adds "also send to channel" field103function ThreadComposer({ channelId }: { channelId: string }) {104 return (105 <Composer.Frame>106 <Composer.Header />107 <Composer.Input />108 <AlsoSendToChannelField id={channelId} />109 <Composer.Footer>110 <Composer.Formatting />111 <Composer.Emojis />112 <Composer.Submit />113 </Composer.Footer>114 </Composer.Frame>115 )116}117118// Edit composer - different footer actions119function EditComposer() {120 return (121 <Composer.Frame>122 <Composer.Input />123 <Composer.Footer>124 <Composer.Formatting />125 <Composer.Emojis />126 <Composer.CancelEdit />127 <Composer.SaveEdit />128 </Composer.Footer>129 </Composer.Frame>130 )131}132```133134Each variant is explicit about what it renders. We can share internals without135136sharing a single monolithic parent.137138### 1.2 Use Compound Components139140**Impact: HIGH (enables flexible composition without prop drilling)**141142Structure complex components as compound components with a shared context. Each143144subcomponent accesses shared state via context, not props. Consumers compose the145146pieces they need.147148**Incorrect: monolithic component with render props**149150```tsx151function Composer({152 renderHeader,153 renderFooter,154 renderActions,155 showAttachments,156 showFormatting,157 showEmojis,158}: Props) {159 return (160 <form>161 {renderHeader?.()}162 <Input />163 {showAttachments && <Attachments />}164 {renderFooter ? (165 renderFooter()166 ) : (167 <Footer>168 {showFormatting && <Formatting />}169 {showEmojis && <Emojis />}170 {renderActions?.()}171 </Footer>172 )}173 </form>174 )175}176```177178**Correct: compound components with shared context**179180```tsx181const ComposerContext = createContext<ComposerContextValue | null>(null)182183function ComposerProvider({ children, state, actions, meta }: ProviderProps) {184 return <ComposerContext value={{ state, actions, meta }}>{children}</ComposerContext>185}186187function ComposerFrame({ children }: { children: React.ReactNode }) {188 return <form>{children}</form>189}190191function ComposerInput() {192 const {193 state,194 actions: { update },195 meta: { inputRef },196 } = use(ComposerContext)197 return (198 <TextInput199 ref={inputRef}200 value={state.input}201 onChangeText={(text) => update((s) => ({ ...s, input: text }))}202 />203 )204}205206function ComposerSubmit() {207 const {208 actions: { submit },209 } = use(ComposerContext)210 return <Button onPress={submit}>Send</Button>211}212213// Export as compound component214const Composer = {215 Provider: ComposerProvider,216 Frame: ComposerFrame,217 Input: ComposerInput,218 Submit: ComposerSubmit,219 Header: ComposerHeader,220 Footer: ComposerFooter,221 Attachments: ComposerAttachments,222 Formatting: ComposerFormatting,223 Emojis: ComposerEmojis,224}225```226227**Usage:**228229```tsx230<Composer.Provider state={state} actions={actions} meta={meta}>231 <Composer.Frame>232 <Composer.Header />233 <Composer.Input />234 <Composer.Footer>235 <Composer.Formatting />236 <Composer.Submit />237 </Composer.Footer>238 </Composer.Frame>239</Composer.Provider>240```241242Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.243244---245246## 2. State Management247248**Impact: MEDIUM**249250Patterns for lifting state and managing shared context across251composed components.252253### 2.1 Decouple State Management from UI254255**Impact: MEDIUM (enables swapping state implementations without changing UI)**256257The provider component should be the only place that knows how state is managed.258259UI components consume the context interface—they don't know if state comes from260261useState, Zustand, or a server sync.262263**Incorrect: UI coupled to state implementation**264265```tsx266function ChannelComposer({ channelId }: { channelId: string }) {267 // UI component knows about global state implementation268 const state = useGlobalChannelState(channelId)269 const { submit, updateInput } = useChannelSync(channelId)270271 return (272 <Composer.Frame>273 <Composer.Input value={state.input} onChange={(text) => sync.updateInput(text)} />274 <Composer.Submit onPress={() => sync.submit()} />275 </Composer.Frame>276 )277}278```279280**Correct: state management isolated in provider**281282```tsx283// Provider handles all state management details284function ChannelProvider({285 channelId,286 children,287}: {288 channelId: string289 children: React.ReactNode290}) {291 const { state, update, submit } = useGlobalChannel(channelId)292 const inputRef = useRef(null)293294 return (295 <Composer.Provider state={state} actions={{ update, submit }} meta={{ inputRef }}>296 {children}297 </Composer.Provider>298 )299}300301// UI component only knows about the context interface302function ChannelComposer() {303 return (304 <Composer.Frame>305 <Composer.Header />306 <Composer.Input />307 <Composer.Footer>308 <Composer.Submit />309 </Composer.Footer>310 </Composer.Frame>311 )312}313314// Usage315function Channel({ channelId }: { channelId: string }) {316 return (317 <ChannelProvider channelId={channelId}>318 <ChannelComposer />319 </ChannelProvider>320 )321}322```323324**Different providers, same UI:**325326```tsx327// Local state for ephemeral forms328function ForwardMessageProvider({ children }) {329 const [state, setState] = useState(initialState)330 const forwardMessage = useForwardMessage()331332 return (333 <Composer.Provider state={state} actions={{ update: setState, submit: forwardMessage }}>334 {children}335 </Composer.Provider>336 )337}338339// Global synced state for channels340function ChannelProvider({ channelId, children }) {341 const { state, update, submit } = useGlobalChannel(channelId)342343 return (344 <Composer.Provider state={state} actions={{ update, submit }}>345 {children}346 </Composer.Provider>347 )348}349```350351The same `Composer.Input` component works with both providers because it only352353depends on the context interface, not the implementation.354355### 2.2 Define Generic Context Interfaces for Dependency Injection356357**Impact: HIGH (enables dependency-injectable state across use-cases)**358359Define a **generic interface** for your component context with three parts:360361`state`, `actions`, and `meta`. This interface is a contract that any provider362363can implement—enabling the same UI components to work with completely different364365state implementations.366367**Core principle:** Lift state, compose internals, make state368369dependency-injectable.370371**Incorrect: UI coupled to specific state implementation**372373```tsx374function ComposerInput() {375 // Tightly coupled to a specific hook376 const { input, setInput } = useChannelComposerState()377 return <TextInput value={input} onChangeText={setInput} />378}379```380381**Correct: generic interface enables dependency injection**382383```tsx384// Define a GENERIC interface that any provider can implement385interface ComposerState {386 input: string387 attachments: Attachment[]388 isSubmitting: boolean389}390391interface ComposerActions {392 update: (updater: (state: ComposerState) => ComposerState) => void393 submit: () => void394}395396interface ComposerMeta {397 inputRef: React.RefObject<TextInput>398}399400interface ComposerContextValue {401 state: ComposerState402 actions: ComposerActions403 meta: ComposerMeta404}405406const ComposerContext = createContext<ComposerContextValue | null>(null)407```408409**UI components consume the interface, not the implementation:**410411```tsx412function ComposerInput() {413 const {414 state,415 actions: { update },416 meta,417 } = use(ComposerContext)418419 // This component works with ANY provider that implements the interface420 return (421 <TextInput422 ref={meta.inputRef}423 value={state.input}424 onChangeText={(text) => update((s) => ({ ...s, input: text }))}425 />426 )427}428```429430**Different providers implement the same interface:**431432```tsx433// Provider A: Local state for ephemeral forms434function ForwardMessageProvider({ children }: { children: React.ReactNode }) {435 const [state, setState] = useState(initialState)436 const inputRef = useRef(null)437 const submit = useForwardMessage()438439 return (440 <ComposerContext441 value={{442 state,443 actions: { update: setState, submit },444 meta: { inputRef },445 }}446 >447 {children}448 </ComposerContext>449 )450}451452// Provider B: Global synced state for channels453function ChannelProvider({ channelId, children }: Props) {454 const { state, update, submit } = useGlobalChannel(channelId)455 const inputRef = useRef(null)456457 return (458 <ComposerContext459 value={{460 state,461 actions: { update, submit },462 meta: { inputRef },463 }}464 >465 {children}466 </ComposerContext>467 )468}469```470471**The same composed UI works with both:**472473```tsx474// Works with ForwardMessageProvider (local state)475<ForwardMessageProvider>476 <Composer.Frame>477 <Composer.Input />478 <Composer.Submit />479 </Composer.Frame>480</ForwardMessageProvider>481482// Works with ChannelProvider (global synced state)483<ChannelProvider channelId="abc">484 <Composer.Frame>485 <Composer.Input />486 <Composer.Submit />487 </Composer.Frame>488</ChannelProvider>489```490491**Custom UI outside the component can access state and actions:**492493```tsx494function ForwardMessageDialog() {495 return (496 <ForwardMessageProvider>497 <Dialog>498 {/* The composer UI */}499 <Composer.Frame>500 <Composer.Input placeholder="Add a message, if you'd like." />501 <Composer.Footer>502 <Composer.Formatting />503 <Composer.Emojis />504 </Composer.Footer>505 </Composer.Frame>506507 {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}508 <MessagePreview />509510 {/* Actions at the bottom of the dialog */}511 <DialogActions>512 <CancelButton />513 <ForwardButton />514 </DialogActions>515 </Dialog>516 </ForwardMessageProvider>517 )518}519520// This button lives OUTSIDE Composer.Frame but can still submit based on its context!521function ForwardButton() {522 const {523 actions: { submit },524 } = use(ComposerContext)525 return <Button onPress={submit}>Forward</Button>526}527528// This preview lives OUTSIDE Composer.Frame but can read composer's state!529function MessagePreview() {530 const { state } = use(ComposerContext)531 return <Preview message={state.input} attachments={state.attachments} />532}533```534535The provider boundary is what matters—not the visual nesting. Components that536537need shared state don't have to be inside the `Composer.Frame`. They just need538539to be within the provider.540541The `ForwardButton` and `MessagePreview` are not visually inside the composer542543box, but they can still access its state and actions. This is the power of544545lifting state into providers.546547The UI is reusable bits you compose together. The state is dependency-injected548549by the provider. Swap the provider, keep the UI.550551### 2.3 Lift State into Provider Components552553**Impact: HIGH (enables state sharing outside component boundaries)**554555Move state management into dedicated provider components. This allows sibling556557components outside the main UI to access and modify state without prop drilling558559or awkward refs.560561**Incorrect: state trapped inside component**562563```tsx564function ForwardMessageComposer() {565 const [state, setState] = useState(initialState)566 const forwardMessage = useForwardMessage()567568 return (569 <Composer.Frame>570 <Composer.Input />571 <Composer.Footer />572 </Composer.Frame>573 )574}575576// Problem: How does this button access composer state?577function ForwardMessageDialog() {578 return (579 <Dialog>580 <ForwardMessageComposer />581 <MessagePreview /> {/* Needs composer state */}582 <DialogActions>583 <CancelButton />584 <ForwardButton /> {/* Needs to call submit */}585 </DialogActions>586 </Dialog>587 )588}589```590591**Incorrect: useEffect to sync state up**592593```tsx594function ForwardMessageDialog() {595 const [input, setInput] = useState("")596 return (597 <Dialog>598 <ForwardMessageComposer onInputChange={setInput} />599 <MessagePreview input={input} />600 </Dialog>601 )602}603604function ForwardMessageComposer({ onInputChange }) {605 const [state, setState] = useState(initialState)606 useEffect(() => {607 onInputChange(state.input) // Sync on every change 😬608 }, [state.input])609}610```611612**Incorrect: reading state from ref on submit**613614```tsx615function ForwardMessageDialog() {616 const stateRef = useRef(null)617 return (618 <Dialog>619 <ForwardMessageComposer stateRef={stateRef} />620 <ForwardButton onPress={() => submit(stateRef.current)} />621 </Dialog>622 )623}624```625626**Correct: state lifted to provider**627628```tsx629function ForwardMessageProvider({ children }: { children: React.ReactNode }) {630 const [state, setState] = useState(initialState)631 const forwardMessage = useForwardMessage()632 const inputRef = useRef(null)633634 return (635 <Composer.Provider636 state={state}637 actions={{ update: setState, submit: forwardMessage }}638 meta={{ inputRef }}639 >640 {children}641 </Composer.Provider>642 )643}644645function ForwardMessageDialog() {646 return (647 <ForwardMessageProvider>648 <Dialog>649 <ForwardMessageComposer />650 <MessagePreview /> {/* Custom components can access state and actions */}651 <DialogActions>652 <CancelButton />653 <ForwardButton /> {/* Custom components can access state and actions */}654 </DialogActions>655 </Dialog>656 </ForwardMessageProvider>657 )658}659660function ForwardButton() {661 const { actions } = use(Composer.Context)662 return <Button onPress={actions.submit}>Forward</Button>663}664```665666The ForwardButton lives outside the Composer.Frame but still has access to the667668submit action because it's within the provider. Even though it's a one-off669670component, it can still access the composer's state and actions from outside the671672UI itself.673674**Key insight:** Components that need shared state don't have to be visually675676nested inside each other—they just need to be within the same provider.677678---679680## 3. Implementation Patterns681682**Impact: MEDIUM**683684Specific techniques for implementing compound components and685context providers.686687### 3.1 Create Explicit Component Variants688689**Impact: MEDIUM (self-documenting code, no hidden conditionals)**690691Instead of one component with many boolean props, create explicit variant692693components. Each variant composes the pieces it needs. The code documents694695itself.696697**Incorrect: one component, many modes**698699```tsx700// What does this component actually render?701<Composer isThread isEditing={false} channelId="abc" showAttachments showFormatting={false} />702```703704**Correct: explicit variants**705706```tsx707// Immediately clear what this renders708<ThreadComposer channelId="abc" />709710// Or711<EditMessageComposer messageId="xyz" />712713// Or714<ForwardMessageComposer messageId="123" />715```716717Each implementation is unique, explicit and self-contained. Yet they can each718719use shared parts.720721**Implementation:**722723```tsx724function ThreadComposer({ channelId }: { channelId: string }) {725 return (726 <ThreadProvider channelId={channelId}>727 <Composer.Frame>728 <Composer.Input />729 <AlsoSendToChannelField channelId={channelId} />730 <Composer.Footer>731 <Composer.Formatting />732 <Composer.Emojis />733 <Composer.Submit />734 </Composer.Footer>735 </Composer.Frame>736 </ThreadProvider>737 )738}739740function EditMessageComposer({ messageId }: { messageId: string }) {741 return (742 <EditMessageProvider messageId={messageId}>743 <Composer.Frame>744 <Composer.Input />745 <Composer.Footer>746 <Composer.Formatting />747 <Composer.Emojis />748 <Composer.CancelEdit />749 <Composer.SaveEdit />750 </Composer.Footer>751 </Composer.Frame>752 </EditMessageProvider>753 )754}755756function ForwardMessageComposer({ messageId }: { messageId: string }) {757 return (758 <ForwardMessageProvider messageId={messageId}>759 <Composer.Frame>760 <Composer.Input placeholder="Add a message, if you'd like." />761 <Composer.Footer>762 <Composer.Formatting />763 <Composer.Emojis />764 <Composer.Mentions />765 </Composer.Footer>766 </Composer.Frame>767 </ForwardMessageProvider>768 )769}770```771772Each variant is explicit about:773774- What provider/state it uses775776- What UI elements it includes777778- What actions are available779780No boolean prop combinations to reason about. No impossible states.781782### 3.2 Prefer Composing Children Over Render Props783784**Impact: MEDIUM (cleaner composition, better readability)**785786Use `children` for composition instead of `renderX` props. Children are more787788readable, compose naturally, and don't require understanding callback789790signatures.791792**Incorrect: render props**793794```tsx795function Composer({796 renderHeader,797 renderFooter,798 renderActions,799}: {800 renderHeader?: () => React.ReactNode801 renderFooter?: () => React.ReactNode802 renderActions?: () => React.ReactNode803}) {804 return (805 <form>806 {renderHeader?.()}807 <Input />808 {renderFooter ? renderFooter() : <DefaultFooter />}809 {renderActions?.()}810 </form>811 )812}813814// Usage is awkward and inflexible815return (816 <Composer817 renderHeader={() => <CustomHeader />}818 renderFooter={() => (819 <>820 <Formatting />821 <Emojis />822 </>823 )}824 renderActions={() => <SubmitButton />}825 />826)827```828829**Correct: compound components with children**830831```tsx832function ComposerFrame({ children }: { children: React.ReactNode }) {833 return <form>{children}</form>834}835836function ComposerFooter({ children }: { children: React.ReactNode }) {837 return <footer className="flex">{children}</footer>838}839840// Usage is flexible841return (842 <Composer.Frame>843 <CustomHeader />844 <Composer.Input />845 <Composer.Footer>846 <Composer.Formatting />847 <Composer.Emojis />848 <SubmitButton />849 </Composer.Footer>850 </Composer.Frame>851)852```853854**When render props are appropriate:**855856```tsx857// Render props work well when you need to pass data back858<List data={items} renderItem={({ item, index }) => <Item item={item} index={index} />} />859```860861Use render props when the parent needs to provide data or state to the child.862863Use children when composing static structure.864865---866867## 4. React 19 APIs868869**Impact: MEDIUM**870871React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.872873### 4.1 React 19 API Changes874875**Impact: MEDIUM (cleaner component definitions and context usage)**876877> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.878879In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.880881**Incorrect: forwardRef in React 19**882883```tsx884const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {885 return <TextInput ref={ref} {...props} />886})887```888889**Correct: ref as a regular prop**890891```tsx892function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {893 return <TextInput ref={ref} {...props} />894}895```896897**Incorrect: useContext in React 19**898899```tsx900const value = useContext(MyContext)901```902903**Correct: use instead of useContext**904905```tsx906const value = use(MyContext)907```908909`use()` can also be called conditionally, unlike `useContext()`.910911---912913## References9149151. [https://react.dev](https://react.dev)9162. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)9173. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)918
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| zebbern/claude-code-guideskills/react-best-practices/AGENTS.md · 4.6k | AGENTS.md | buildlint-formatstylearch+8 | 64/100 | 14 days ago |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| vllm-project/vllmAGENTS.md · 89k | AGENTS.md | setuptestlint-formatstyle+5 | 100/100 | 14 days ago | |
| mui/material-uiAGENTS.md · 99k | AGENTS.md | setupbuildtestlint-format+9 | 100/100 | 14 days ago | |
| code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 68k | AGENTS.md | setupbuildtestlint-format+6 | 100/100 | 13 days ago | |
| TryGhost/Ghoste2e/AGENTS.md · 55k | AGENTS.md | setupteststylearch+2 | 100/100 | today | |
| n8n-io/n8npackages/@n8n/agents/AGENTS.md · 201k | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| deepseek-ai/deepseek-harnessnative/landlock-run/AGENTS.md · 104k | AGENTS.md | setupteststylearch+3 | 100/100 | today | |
| duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70 | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| elastic/elasticsearchx-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ml/AGENTS.md · 78k | AGENTS.md | buildtestlint-formatstyle+2 | 100/100 | 14 days ago |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/zebbern-claude-code-guide-skills-composition-patterns-agents)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.