Skip to content

UI: Mark Select and SelectControl as recommended #83030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mirka merged 6 commits into from
Sep 17, 2026
Merged

UI: Mark Select and SelectControl as recommended #83030

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
62763b2
UI: Mark Select and SelectControl as recommended
mirka Sep 16, 2026
3c805e3
Add PR number to eslint-plugin changelog
mirka Sep 16, 2026
21d8cfe
Mark legacy SelectControl as not recommended in Storybook
mirka Sep 16, 2026
6214c47
Point minimal SelectControl usages at the Select primitive
mirka Sep 16, 2026
15173b4
Merge trunk into ui/recommend-select.
mirka Sep 17, 2026
97c4a64
Add a changelog for recommending Select and SelectControl.
mirka Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion packages/block-editor/src/hooks/position.jsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ import { getBlockSupport, hasBlockSupport } from '@wordpress/blocks';
import { useInstanceId } from '@wordpress/compose';
import { useSelect } from '@wordpress/data';
import { useMemo } from '@wordpress/element';
// eslint-disable-next-line @wordpress/use-recommended-components -- Use the portal-based popup to avoid inspector clipping.
import { SelectControl } from '@wordpress/ui';
import { useSettings } from '../components/use-settings';
import InspectorControls from '../components/inspector-controls';
Expand Down
1 change: 1 addition & 0 deletions packages/components/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

### Enhancements

- `SelectControl`: Mark as not recommended for use in a WordPress environment, in favour of `SelectControl` from `@wordpress/ui` ([#83030](https://github.com/WordPress/gutenberg/pull/83030)).
- `PaletteEdit`: Use standard menu semantics and keyboard navigation for palette option actions through `Menu` from `@wordpress/ui` ([#82768](https://github.com/WordPress/gutenberg/pull/82768)).
- `CheckboxControl`: Match the `@wordpress/ui` checkmark size and disabled fill ([#82555](https://github.com/WordPress/gutenberg/pull/82555)).
- `Snackbar`: Show the action's focus ring with the design system's outline instead of a legacy dotted outline, and let `Button`/`ExternalLink` own the ring ([#82640](https://github.com/WordPress/gutenberg/pull/82640)).
Expand Down
5 changes: 2 additions & 3 deletions packages/components/src/select-control/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ import SelectControl from '../';
import { InputControlPrefixWrapper } from '../../input-control/input-prefix-wrapper';

const meta: Meta< typeof SelectControl > = {
tags: [ 'manifest' ],
title: 'Components/Selection & Input/Common/SelectControl',
id: 'components-selectcontrol',
component: SelectControl,
Expand All @@ -23,9 +22,9 @@ const meta: Meta< typeof SelectControl > = {
controls: { expanded: true },
docs: { canvas: { sourceState: 'shown' } },
componentStatus: {
status: 'recommended',
status: 'not-recommended',
whereUsed: 'global',
notes: 'Will be superseded by [`SelectControl`](?path=/docs/design-system-components-form-selectcontrol--docs) in `@wordpress/ui`, but continue using for now.',
notes: 'Use [`SelectControl`](?path=/docs/design-system-components-form-selectcontrol--docs) from `@wordpress/ui` instead. For the `minimal` variant, use the [`Select`](?path=/docs/design-system-components-form-primitives-select--docs) primitive rather than `SelectControl`.',
},
},
};
Expand Down
1 change: 1 addition & 0 deletions packages/eslint-plugin/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

### Enhancements

- Update `use-recommended-components` rule to mark `Select` and `SelectControl` from `@wordpress/ui` as recommended ([#83030](https://github.com/WordPress/gutenberg/pull/83030)).
- `recommended`: Apply the TypeScript rules and parser to `.mts` and `.cts` files ([#83071](https://github.com/WordPress/gutenberg/pull/83071)).
- `recommended`: Resolve imports through `.mjs`, `.cjs`, `.mts` and `.cts`, and exempt `.d.mts` and `.d.cts` from the TypeScript resolver settings alongside `.d.ts` ([#83071](https://github.com/WordPress/gutenberg/pull/83071)).
- `no-i18n-in-save`: Recognise the `.mjs`, `.cjs`, `.mts` and `.cts` spellings of `save` and `deprecated` ([#83071](https://github.com/WordPress/gutenberg/pull/83071)).
Expand Down
2 changes: 2 additions & 0 deletions packages/eslint-plugin/rules/use-recommended-components.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ const ALLOWLIST = {
'RangeCalendar',
'SearchableChipSelect',
'SearchableChipSelectControl',
'Select',
'SelectControl',
'Skeleton',
'Spinner',
'Stack',
Expand Down
1 change: 1 addition & 0 deletions packages/ui/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@

### Enhancements

- `Select`, `SelectControl`: Mark as recommended for use in a WordPress environment ([#83030](https://github.com/WordPress/gutenberg/pull/83030)).
- `Select`, `SelectControl`: Add `ItemLabel` and `ItemDescription` subcomponents. Multiple descriptions contribute to `aria-describedby` in DOM order. `SelectControl` `items` may include an optional `description` string. ([#82369](https://github.com/WordPress/gutenberg/pull/82369))
- `Select`, `SelectControl`: Align the selected item with the trigger by default, and drop the popup max-height cap when that alignment is enabled ([#82043](https://github.com/WordPress/gutenberg/pull/82043)).
- `Select`, `Combobox`, `Autocomplete`: Allow browsing read-only controls while keeping their value unchanged ([#82835](https://github.com/WordPress/gutenberg/pull/82835)).
Expand Down
2 changes: 2 additions & 0 deletions packages/ui/src/form/primitives/select/root.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import { DirectionProvider } from '../../../utils/direction-provider';
/**
* A component that lets users choose one option from a list.
*
* Prefer `SelectControl` when using with a standard label and description.
*
* When using object values, pass an `items` array so `Select.Trigger` can
* auto-resolve the selected item's label. By default, items should use a
* `{ value, label }` shape, or provide `itemToStringLabel` for a custom shape.
Expand Down
9 changes: 7 additions & 2 deletions packages/ui/src/form/primitives/select/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,14 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
import * as Select from '../';

const meta: Meta< typeof Select.Root > = {
tags: [ 'manifest' ],
title: 'Design System/Components/Form/Primitives/Select',
component: Select.Root,
// Temporary: Due to an upstream bug, render the root explicitly so the
// components manifest extractor can resolve props from the JSX.
//
// See: https://github.com/storybookjs/storybook/issues/34877
render: ( args ) => <Select.Root { ...args } />,
Comment on lines +8 to +12

@aduth aduth Sep 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought this had been resolved? The issue is closed and I removed a number of them in #80692 as part of the upgrade to Storybook 10.5.

@mirka mirka Sep 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the remaining instances, they're all components I probably had in flight while you were cleaning them up 🙈 Final removal in #83124.

@aduth aduth Sep 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, yeah, I saw there were a few more as well, because of how long #80692 ended up staying open before merge. Good we can clean them up!

subcomponents: {
'Select.Trigger': Select.Trigger,
'Select.Portal': Select.Portal,
Expand All @@ -17,9 +23,8 @@ const meta: Meta< typeof Select.Root > = {
},
parameters: {
componentStatus: {
status: 'use-with-caution',
status: 'recommended',
whereUsed: 'global',
notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`, overlays compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
},
},
};
Expand Down
12 changes: 12 additions & 0 deletions packages/ui/src/form/select-control/stories/index.story.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,14 @@ import {
} from '../../stories/shared';

const meta: Meta< typeof SelectControl > = {
tags: [ 'manifest' ],
title: 'Design System/Components/Form/SelectControl',
component: SelectControl,
// Temporary: Due to an upstream bug, render the root explicitly so the
// components manifest extractor can resolve props from the JSX.
//
// See: https://github.com/storybookjs/storybook/issues/34877
render: ( args ) => <SelectControl { ...args } />,
subcomponents: {
'SelectControl.Group': SelectControl.Group,
'SelectControl.GroupLabel': SelectControl.GroupLabel,
Expand All @@ -20,6 +26,12 @@ const meta: Meta< typeof SelectControl > = {
argTypes: {
onValueChange: { action: 'onValueChange' },
},
parameters: {
componentStatus: {
status: 'recommended',
whereUsed: 'global',
},
},
};

export default meta;
Expand Down
178 changes: 167 additions & 11 deletions storybook/components-manifest.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1272,26 +1272,182 @@
- placeholder
- size
- value
- name: Select.Root
props:
- actionsRef
- autoComplete
- children
- defaultOpen
- defaultValue
- disabled
- form
- highlightItemOnHover
- id
- inputRef
- isItemEqualToValue
- items
- itemToStringLabel
- itemToStringValue
- modal
- name
- onOpenChange
- onOpenChangeComplete
- onValueChange
- open
- readOnly
- required
- value
subcomponents:
- name: Select.Group
props:
- children
- className
- render
- style
- name: Select.GroupLabel
props:
- children
- className
- render
- style
- name: Select.Item
props:
- children
- className
- disabled
- label
- nativeButton
- render
- size
- style
- value
- name: Select.ItemDescription
props:
- children
- className
- render
- style
- name: Select.ItemLabel
props:
- children
- className
- render
- style
- name: Select.Popup
props:
- children
- className
- finalFocus
- portal
- positioner
- render
- style
- width
- name: Select.Portal
props:
- className
- container
- render
- style
- name: Select.Positioner
props:
- align
- alignItemWithTrigger
- alignOffset
- anchor
- arrowPadding
- className
- collisionAvoidance
- collisionBoundary
- collisionPadding
- disableAnchorTracking
- positionMethod
- render
- side
- sideOffset
- sticky
- style
- name: Select.Trigger
props:
- children
- className
- disabled
- nativeButton
- placeholder
- render
- size
- style
- variant
- name: SelectControl
props:
- __next36pxDefaultSize
- __next40pxDefaultSize
- __nextHasNoMarginBottom
- actionsRef
- autoComplete
- children
- className
- defaultOpen
- defaultValue
- description
- details
- disabled
- help
- form
- hideLabelFromVision
- highlightItemOnHover
- id
- isItemEqualToValue
- items
- itemToStringLabel
- itemToStringValue
- key
- label
- labelPosition
- multiple
- onChange
- options
- prefix
- modal
- name
- onOpenChange
- onOpenChangeComplete
- onValueChange
- open
- placeholder
- popupWidth
- readOnly
- ref
- required
- size
- suffix
- triggerContent
- value
- variant
subcomponents:
- name: SelectControl.Group
props:
- children
- className
- render
- style
- name: SelectControl.GroupLabel
props:
- children
- className
- render
- style
- name: SelectControl.Item
props:
- children
- className
- disabled
- label
- nativeButton
- render
- style
- value
- name: SelectControl.ItemDescription
props:
- children
- className
- render
- style
- name: SelectControl.ItemLabel
props:
- children
- className
- render
- style
- name: Shortcut
props:
- className
Expand Down
12 changes: 11 additions & 1 deletion storybook/prop-description-allowlist.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,17 @@
"SearchableChipSelectControl>SearchableChipSelectControl.GroupLabel:children",
"SearchableChipSelectControl>SearchableChipSelectControl.Item",
"SearchableChipSelectControl>SearchableChipSelectControl.Item:children",
"SelectControl:ref",
"Select.Root:children",
"Select.Root>Select.Group:children",
"Select.Root>Select.GroupLabel:children",
"Select.Root>Select.Item",
"Select.Root>Select.Popup",
"Select.Root>Select.Trigger",
"SelectControl:children",
"SelectControl:key",
"SelectControl>SelectControl.Group:children",
"SelectControl>SelectControl.GroupLabel:children",
"SelectControl>SelectControl.Item",
"Slot>Fill",
"Slot>SlotFillProvider",
"ToggleControl:className",
Expand Down
Loading