This post lists notable changes to the @wordpress/components
package for the WordPress 6.7 release
Table of Contents
- CustomSelectControl rewritten to Ariakit
- Reducing experimental APIs
- Stabilized Composite
- Stabilized Navigator
- Stabilized AlignmentMatrixControl
- Stabilized BoxControl
- Stabilized Button’s __experimentalIsFocusable prop
- Deprecated DimensionControl
- TimePicker: Time input can be used in isolation
- Stricter type checking in SelectControl
- Bottom margin styles are deprecated
- Modal: Buttons in headerActions should use “small” size
CustomSelectControl
rewritten to Ariakit
The CustomSelectControl
component has been completely rewritten using ariakit
. Notably, this refactor enables the removal of the downshift
library as a dependency of the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository, causing a ~7.75 kB decrease for the @wordpress/components
package bundle size.
While there are no breaking changes to the component public APIs, the refactor also allowed us to make a few improvements to the component:
- the trigger button has the
combobox
role instead of button
, in line with the WAI-ARIA specs;
- the
__experimentalShowSelectedHint
and options[]. __experimentalHint
props have been unprefixed and stabilized;
- the select popover has a new entrance animation when opened, in line with other components;
- while the select popover’s
max-height
hasn’t changed, the popover’s height adapts to the available space, without causing extra overflow on the page;
- item hints can now wrap to a separate row from the item’s content when there isn’t sufficient space to render on the same line;
- item internal padding now matches the trigger button padding for better visual consistency.
For more information visit #63258, and #63248. (top)
Support disabled ToggleGroupControl
options
The ToggleGroupControlOption
and ToggleGroupControlOptionIcon
components can now be marked as disabled via the newly added disabled
prop. While disabled, an option cannot be selected by the end user.
For more information visit #63450. (top)
Reducing experimental APIs
A few components have been stabilized or deprecated as part of an ongoing effort to progressively reduce the number of experimental APIs exported from the @wordpress/components
package.
Stabilized Composite
Following the rewrite of the __unstableComposite
(& related) components from ariakit
to reakit
in the WordPress 6.5 release, the 6.7 release introduces a new, stable version for the Composite
component.
The new Composite
component offers a more complete and versatile way to implement low-level composite widgets, and its APIs are more consistent with the rest of the @wordpress/components
package.
import { Composite } from '@wordpress/components';
//...
<Composite>
<Composite.Item>Item one</Composite.Item>
<Composite.Item>Item two</Composite.Item>
<Composite.Item>Item three</Composite.Item>
</Composite>
For more information on the component’s APIs and other usage examples, please refer to the Storybook page.
Finally, the __unstableComposite
(& related) components have been marked as deprecated.
For more information visit #63569. (top)
Stabilized Navigator
The legacy set of __experimentalNavigator*
APIs is deprecated and should instead be imported as Navigator
. All of the sub-components are also available via the Navigator
namespace.
Moreover, the __experimentalNavigatorToParentButton
component and the goToParent()
method available via the __experimentalUseNavigator
hook are deprecated, and they now behave identically to the __experimentalNavigatorBackButton
and the goBack()
method.
To recap:
__experimentalNavigatorProvider
=> Navigator
__experimentalNavigatorScreen
=> Navigator.Screen
__experimentalNavigatorButton
=> Navigator.Button
__experimentalNavigatorBackButton
=> Navigator.BackButton
__experimentalNavigatorToParentButton
=> Navigator.BackButton
__experimentalUseNavigator
=> useNavigator
For more information visit #64613. (top)
Stabilized AlignmentMatrixControl
The __experimentalAlignmentMatrixControl
component can now be imported as AlignmentMatrixControl
.
The legacy __experimentalAlignmentMatrixControl
export is marked as deprecated.
For more information visit #60913. (top)
Stabilized BoxControl
The __experimentalBoxControl
component can now be imported as BoxControl
.
The legacy __experimentalBoxControl
export is marked as deprecated.
For more information visit #65469. (top)
The Button component had a __experimentalIsFocusable
prop to keep the button focusable when disabled. This prop is now stabilized and renamed to accessibleWhenDisabled
. (Existing usages of __experimentalIsFocusable
will continue to work indefinitely.)
In most cases, it is recommended to set this to true
. Disabling a control without maintaining focusability can cause accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) issues, by hiding their presence from screen reader users, or by preventing focus from returning to a trigger element.
Learn more about the focusability of disabled controls in the WAI-ARIA Authoring Practices Guide.
For more information visit #62282. (top)
Deprecated DimensionControl
The DimensionControl
component is now marked as deprecated and scheduled for removal in the WordPress 7.0 release.
Usages of DimensionControl
can be replaced with SelectControl
and CustomSelectControl
, passing an array of dimension options
to the components.
For more information visit #64951. (top)
The time input of the TimePicker
component can now be used in isolation as <TimePicker.TimeInput />
. In this case, the value will be passed as an object in a 24-hour format ({ hours: number, minutes: number })
.
For more information visit #60613. (top)
Stricter type checking in SelectControl
In TypeScript codebases, SelectControl
will now be able to type-check whether the value
type matches in the value
, options
, and onChange
props. See detailed examples in the full dev note.
For more information visit #64069. (top)
Bottom margin styles are deprecated
A number of UI User interface components currently ship with styles that give them bottom margins. This can make it hard to reuse them in arbitrary layouts, where you want different amounts of gap or margin between components.
To better suit modern layout needs, we have gradually been deprecating these margins. A deprecation begins with an opt-in period where you can choose to apply the new margin-free styles on a given component instance. Eventually in a future version, the margins will be completely removed.
Continuing the effort started in previous releases, for the WordPress 6.7 release we will start logging deprecation warnings for the following components if they are not yet opting into the new margin-free styles:
BaseControl
CheckboxControl
ComboboxControl
DimensionControl
FocalPointPicker
FormTokenField
RangeControl
SearchControl
SelectControl
TextControl
TextareaControl
ToggleControl
ToggleGroupControl
TreeSelect
To start opting into the new margin-free styles, set the __nextHasNoMarginBottom
prop to true
.
<SelectControl
options={ selectOptions }
value={ selectValue }
label={ __( 'Label' ) }
onChange={ onSelectChange }
__nextHasNoMarginBottom={ true }
/>
For more information visit #39358. (top)
The close button in the Modal
component is now using the “small” Button
size (currently 24px
), down from the 36px
default size in the old sizing scheme.
If you are using the headerActions
prop to inject buttons beside the close button, we recommend you also use the “small” Button
size
variant to match.
<Modal
headerActions={ <Button icon={ fullscreen } label="Fullscreen mode" size="small" /> }
/>
For more information visit #65131. (top)
Props to @mirka for the help in writing these dev notes Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase..
#6-7, #dev-notes, #dev-notes-6-7