[mfal]

Adds performance guidance for List users: a new Performance section on the List page, a Best Practices bullet that points to it, and one line in USAGE.md so agents in consumer repos find it without opening the List page first.

Targets next: the guidance builds on renderDependencies from #3526, which exists only there.

What the section says

• Items with renderDependencies. An inline render function re-renders every item on every parent render. With renderDependencies on List.Item / List.TableRow, an item re-renders only when its data or a listed value changes; [] when the render function reads nothing but the item. Rules: list every outside value, keep listed values stable (useCallback/useMemo), keep data stable. Details link to the existing "Item-Inhalte und externer State" section instead of repeating it.
• Modals and context menus. A closed Modal renders nothing until opened, but its controller and whatever the app wraps around it multiply per item. Shows one shared modal at list level that receives the selected item, with renderDependencies={[edit]} and the pitfalls: do not reset the selection on close; without renderDependencies, setSelected re-renders every item.
• Data and batches. Load data at list level, keep the batch size of 20 ("show more" and infinite scroll keep every loaded item mounted, and sort/filter/search re-render all of them), no global listeners per item.

Basis

Measured with the harness from #3524 (200 rich items, Chromium, production React):

• parent re-render with an inline render function: 183–190 → 107 ms with renderDependencies (feat(List): skip item and table row re-renders for inline callbacks and renderDependencies #3526), ~40 %;
• a closed Modal with its own controller adds ~20 fibers and ~0.035 ms per item;
• a survey of mStudio's 109 lists found every item render function inline, no React.memo on item components, and per-item modals in 59 lists — the case this guidance targets.

Notes

• The first version recommended memo item components and targeted main. With feat(List): skip item and table row re-renders for inline callbacks and renderDependencies #3526 on next, renderDependencies is the fast path, so the PR moved to next and the section now recommends it.
• USAGE.md ships with the package, so this merge counts as release-relevant.

Related: #3528 (measurement results)

🤖 Generated with Claude Code

[github-actions]

Coverage Report for ./packages/components/

Status	Category	Percentage	Covered / Total
🔵	Lines	78.27%	1416 / 1809
🔵	Statements	77.89%	1455 / 1868
🔵	Functions	72.05%	330 / 458
🔵	Branches	71.69%	760 / 1060

File Coverage

No changed files found.

Generated in workflow #7350 for commit c90c78f by the Vitest Coverage Report Action

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-3527.docs.review.flow-components.de
storybook	pr-3527.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-3527
• storybook: ghcr.io/mittwald/flow/storybook:pr-3527