[mirka]

What?

Add a migration guide from the legacy @wordpress/components SelectControl to @wordpress/ui, attached to the legacy component's Storybook entry and linked from its recommendation notice.

Why?

The recent migrations exposed differences beyond prop names, including empty-string defaults displaying a placeholder, missing initial selections, object callbacks, and portaled popup behavior. Consolidate the guidance from #84345, #84546, #84584, #83035, #84936, and #85172.

How?

Document value identity, callbacks and refs, labels and descriptions, trigger props, grouped native options, minimal controls, overlay integration, and test updates. Recommend one serialization pattern for preserving stored empty strings, distinguish clearable null values and placeholders, and explain form-submission implications. Embed interactive examples, including a controlled empty-string story that displays its stored value.

Testing Instructions

1. Open SelectControl under Components / @wordpress-components / Selection & Input / Common in Storybook. Follow the migration-guide link in its recommendation notice, or select Migration Guide in the sidebar.
2. In Preserve an empty string as a real choice, choose Sticky and then Default. Confirm the displayed stored value changes from "sticky" to "", and reopening the popup retains Default. Repeat with the keyboard.
3. In Provide an option that clears the selection, choose Dark and then Select theme. Confirm the control returns to its empty state. In Show a placeholder before selection, confirm the initial prompt is replaced by the chosen item.
4. In Migrate minimal controls with Select, change the numeric choice and confirm the trigger updates. Expand its source to inspect the primitive composition.
5. Confirm the prop table, code examples, section links, and links to the replacement components render correctly.

Screenshots or screencast

The before images show the static examples at 949e94f4def1. The after images show the interactive examples added by this revision. Both use the same viewport and 2x device pixels. The minimal after image focuses on the interactive trigger.

Example	Before	After
Empty-string choice
Minimal select

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: 0 B

Total Size: 9.05 MB

_{a72f0c9 Run}

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Regression: updating a specific option will only change its value and will not corrupt others in /test/e2e/specs/editor/various/core-settings.spec.js, passed after 1 failed attempt.

Error: expect(received).toStrictEqual(expected) // deep equality

- Expected  - 1
+ Received  + 1

  Array [
    "rewrite_rules",
-   "SERIALIZED DATA",
+   "",
  ]
    at forEach (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:46:26)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:43:35

refuses the drop and uploads nothing in /test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js, passed after 1 failed attempt.

Error: expect(received).toHaveLength(expected)

Expected length: 0
Received length: 1
Received array:  [{"_links": {"about": [{"href": "http://localhost:8889/wp-json/wp/v2/types/attachment"}], "author": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/users/1"}], "collection": [{"href": "http://localhost:8889/wp-json/wp/v2/media"}], "curies": [{"href": "https://api.w.org/{rel}", "name": "wp", "templated": true}], "replies": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/comments?post=223"}], "self": [{"href": "http://localhost:8889/wp-json/wp/v2/media/223", "targetHints": {"allow": ["GET", "POST", "PUT", "PATCH", "DELETE"]}}], "wp:attached-to": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/posts/222", "id": 222, "post_type": "post"}]}, "alt_text": "", "author": 1, "caption": {"rendered": ""}, "class_list": ["post-223", "attachment", "type-attachment", "status-inherit", "hentry", "entry"], "comment_status": "open", "date": "2026-10-22T07:53:14", "date_gmt": "2026-10-22T07:53:14", "description": {"rendered": "<p class=\"attachment\"><a href='http://localhost:8889/wp-content/uploads/2026/10/0c04a184-15e6-4746-ab79-0db5ac577654.png'><img loading=\"lazy\" decoding=\"async\" width=\"10\" height=\"10\" src=\"http://localhost:8889/wp-content/uploads/2026/10/0c04a184-15e6-4746-ab79-0db5ac577654.png\" class=\"attachment-medium size-medium\" alt=\"\" style=\"width:100%;height:100%;max-width:10px;\" /></a></p>
"}, "featured_media": 0, "filename": "0c04a184-15e6-4746-ab79-0db5ac577654.png", "filesize": 80, "guid": {"rendered": "http://localhost:8889/wp-content/uploads/2026/10/0c04a184-15e6-4746-ab79-0db5ac577654.png"}, "id": 223, "link": "http://localhost:8889/?attachment_id=223", "media_details": {"file": "2026/10/0c04a184-15e6-4746-ab79-0db5ac577654.png", "filesize": 80, "height": 10, "image_meta": {"alt": "", "aperture": "0", "camera": "", "caption": "", "copyright": "", "created_timestamp": "0", "credit": "", "focal_length": "0", "iso": "0", "keywords": [], "orientation": "0", "shutter_speed": "0", "title": ""}, "sizes": {}, "width": 10}, "media_type": "image", "meta": [], "mime_type": "image/png", "modified": "2026-10-22T07:53:14", "modified_gmt": "2026-10-22T07:53:14", "ping_status": "closed", "post": 222, "slug": "0c04a184-15e6-4746-ab79-0db5ac577654", "source_url": "http://localhost:8889/wp-content/uploads/2026/10/0c04a184-15e6-4746-ab79-0db5ac577654.png", "status": "inherit", "template": "", "title": {"rendered": "0c04a184-15e6-4746-ab79-0db5ac577654"}, "type": "attachment"}]
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js:71:45

_{a72f0c9 Run}