Updates to user-interface components in WordPress 6.7

This post lists notable changes to the @wordpress/components package for the WordPress 6.7 release

Table of Contents

  1. CustomSelectControl rewritten to Ariakit
  2. Reducing experimental APIs
    1. Stabilized Composite
    2. Stabilized Navigator
    3. Stabilized AlignmentMatrixControl
    4. Stabilized BoxControl
    5. Stabilized Button’s __experimentalIsFocusable prop
  3. Deprecated DimensionControl
  4. TimePicker: Time input can be used in isolation
  5. Stricter type checking in SelectControl
  6. Bottom margin styles are deprecated
  7. 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 GutenbergGutenberg 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)

Stabilized Button‘s __experimentalIsFocusable prop

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 accessibilityAccessibility 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)

TimePicker: Time input can be used in isolation

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 UIUI 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 notesdev note 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