Call for testing: Settings UI support for WooCommerce extensions

The WooCommerce ecosystem is currently in a transition between the legacy PHP admin user interface and the newer admin design components, powered by React. To empower extension developers through this period, WooCommerce is adding an opt-in path to test React-rendered settings pages while continuing to use the familiar WooCommerce settings array and save flow.

Beginning in WooCommerce 10.9, the new Settings UI is behind the settings-ui feature flag. When the flag is enabled, WooCommerce can render an opted-in settings page through the new React shell instead of the classic PHP settings table. When the flag is disabled, the same page continues to use the legacy settings renderer.

This is not a required migration for every extension. We are looking for feedback from developers who maintain WooCommerce settings pages and want to test how existing settings definitions behave in the new renderer.

Extending the framework for building settings pages

The key goal is incremental adoption. Today, many WooCommerce extension settings pages are built with a WC_Settings_Page class that includes a WooCommerce settings array. That array defines the fields on the page: labels, option IDs, defaults, choices, descriptions, field types, and save behavior. Similarly, some extensions may be extending the SettingsSection class, defining fields for an existing WooCommerce settings page.

Settings UI is designed to adapt those existing models rather than replace it all at once. The adapter acts as a bridge: it reads the existing settings array and converts it into a Settings UI schema. Common field types such as checkbox, text, select, number, textarea, and multiselect are rendered by native React controls.

The default save adapter is form_post, so settings can still save through WooCommerce’s existing settings form POST flow. In practice, that means extension developers can start by testing rendering and saving before introducing any custom React UI.

The adapter also maps title and sectionend entries into grouped sections in the Settings UI schema. If your settings page relies on section headings, descriptions, or grouped fields, that is useful testing coverage.

Extension points to test

There are two related pieces worth understanding:

• LegacySettingsPageAdapter is the bridge for existing WooCommerce settings arrays. It reads the fields already defined by a legacy settings page or registered settings section and turns them into the schema the React Settings UI can render. This is the starting point for 10.9 and straightforward migrations because labels, IDs, options, defaults, descriptions, and the normal save flow still come from the existing PHP settings definition.
• SettingsUIPageInterface is the native Settings UI contract. WooCommerce renders a Settings UI page from an object that implements this interface. LegacySettingsPageAdapter provides that implementation for legacy settings arrays, and more advanced integrations can provide their own SettingsUIPageInterface when they need direct control over the schema, shell navigation, JavaScript scope, script handles, or save behavior.

The relationship is simple: use LegacySettingsPageAdapter when the existing settings array can remain the source of truth, and use a custom SettingsUIPageInterface when the Settings UI page needs to be defined natively. For WooCommerce 11.0 and newer, that custom interface path is especially relevant for complex registered sections that need their own schema, shell navigation, JavaScript scope, script handles, or custom save behavior.

Developers can also customize the generated schema by extending LegacySettingsPageAdapter. For example, a field can include a component value in the schema and then register a matching React component with registerSettingsExtension() from the @woocommerce/settings-ui package, the JavaScript package that connects component names in the schema to React renderers. If you do this, make sure your adapter or section returns the script handle from get_script_handles() so the component registration script loads before the Settings UI app mounts.

What to test

Start by opting into the experiment with this code snippet:

<?php
add_filter(
	'woocommerce_admin_features',
	static function ( array $features ): array {
		$features[] = 'settings-ui';
		return array_values( array_unique( $features ) );
	}
);

If you maintain a WooCommerce extension with settings, you can help test by extending your existing WC_Settings_Page to return a LegacySettingsPageAdapter from get_settings_ui_page() and confirming that existing settings arrays render correctly and settings save through the default form_post adapter.

Simple implementations can test built-in field types such as checkbox, text, select, number, textarea, and multiselect or array-backed fields, and for more advanced implementations, registering a custom React field component or custom implementation.

When you share feedback, please include the WooCommerce version or build you tested, which settings page or section you opted in, the field types involved, whether you saw console warnings, and whether values saved as expected.

Share your feedback in the comments below or on this GitHub Discussion.

The implementation docs are available here:

• Settings UI
• Registering Settings UI components

Thank you for testing. Feedback from existing extension settings pages will help us refine the React renderer, schema conversion, custom component hooks, and compatibility behavior before this path moves beyond opt-in testing.