Skip to content

docs(collections): explain updating collection structure#10232

Open
patrickwehbe wants to merge 1 commit into
adobe:mainfrom
patrickwehbe:docs/collections-structure-state
Open

docs(collections): explain updating collection structure#10232
patrickwehbe wants to merge 1 commit into
adobe:mainfrom
patrickwehbe:docs/collections-structure-state

Conversation

@patrickwehbe

Copy link
Copy Markdown

Closes

Closes #10199

✅ Pull Request Checklist:

  • Included link to corresponding React Spectrum GitHub Issue.
  • Added/updated unit tests and storybook for this change (for new code or code which already has tests).
  • Filled out test instructions.
  • Updated documentation (if it already exists for this component).
  • Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Docs-only change. Build the docs site and view the Collections page (react-aria/collections); the new "Updating the collection structure" subsection appears between "Dependencies" and "Combining collections".

🧢 Your Project:

React Aria docs


This adds a focused subsection to the Collections guide explaining a behavior that has tripped up several users (see #10199): state that controls which items exist in a collection must live above the collection component.

Collections are built by parsing the JSX tree itself rather than the output of the render function. To do that, the component renders a hidden copy of its children up to each item boundary to build the collection document, and only then renders the real, interactive content. Because these are two separate renders, a state update inside the collection's children re-renders only the visible content and never re-runs the hidden structure pass, so toggling local state (e.g. from SelectStateContext inside a Select popover) cannot add or remove items. Lifting that state above the collection re-runs both passes.

Per @snowystinger's suggestion in the issue this lives in the Collections page since it applies to all collections, not just Select. The explanation adapts @nwidynski's write-up from the issue thread. Prose only; no API changes.

Adds a subsection to the Collections guide explaining that state controlling which items exist must live above the collection component, because collections are built by parsing a hidden render of the JSX before the real content renders.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Toggling a useState within a Popover to control a set of Collection items fails to update properly

1 participant