Docs: document controlled/uncontrolled prop naming conventions for @wordpress/ui#76281
Conversation
…ss/ui README Document the `defaultX` / `x` / `onXChange` prop naming pattern used across interactive components in the package. Covers uncontrolled vs controlled modes, difference from native `onChange`, and guidelines for component authors. Ref: #76252 (comment) Made-with: Cursor
…est practices Add a note at the top of the Tabs best practices page linking to the package-wide controlled/uncontrolled prop naming conventions documented in the README. Made-with: Cursor
- Use `@wordpress/element` import instead of `react` for consistency with the rest of the README and package source - Clarify that `onXChange` receives the new value as its "first" argument (some Base UI-derived components pass additional arguments) - Document behavior when neither `x` nor `defaultX` is provided Made-with: Cursor
ciampo
added
[Type] Developer Documentation
There was a problem hiding this comment.
Pull request overview
Documents the @wordpress/ui controlled/uncontrolled prop naming convention (defaultX / x / onXChange) to provide a single reference for both component authors and consumers, and links to it from the Tabs Storybook best-practices page.
Changes:
- Adds a new “Controlled and Uncontrolled Modes” section to
packages/ui/README.mddescribing the naming pattern, behavior rules, and authoring guidelines. - Includes concrete controlled/uncontrolled usage examples (Tabs + CollapsibleCard) and clarifies how
onXChangediffers from nativeonChange. - Adds a cross-reference in the Tabs best-practices MDX to the new README section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
packages/ui/src/tabs/stories/best-practices.mdx |
Adds a link to the newly documented package-wide controlled/uncontrolled conventions. |
packages/ui/README.md |
Introduces the new documentation section detailing the defaultX / x / onXChange convention with examples and guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Flaky tests detected in c838f3e. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22801491699
|
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
…m Tabs best practices" This reverts commit e061ff2.
What?
Document the controlled/uncontrolled prop naming conventions (
defaultX/x/onXChange) for the@wordpress/uipackage.Why?
As noted in #76252 (comment), these conventions should be documented so that both component authors and consumers have a single, authoritative reference for the pattern.
The
@wordpress/uipackage already follows a consistent pattern across its interactive components (inherited from Base UI), but it was not yet documented.How?
@wordpress/uiREADME, covering:defaultX/x/onXChangeprop naming patternonChangeTesting Instructions
packages/ui/README.mdCollapsibleCard,Dialog,Tabs,Input,Textarea,Select)npm run storybook:dev→ Design System > Components > Introduction)Made with Cursor