WooCommerce is testing Settings UI support for extensions while keeping legacy PHP settings as the source of truth. Custom React components, script handles, option IDs, and runtime effects need a field-by-field check before a store trusts the migrated screen.
Use this for payment, tax, shipping, subscriptions, CRM, tracking, wholesale, and custom WooCommerce extensions that add their own settings fields or admin components.
Quick answer
WooCommerce Settings UI Custom Component Script Handle Checklist should be handled with a narrow evidence-first workflow: inventory fields, enable on staging, verify scripts, then verify the result before making broader changes.
What to check first
- Inventory each settings section and field that controls checkout, payment, email, tax, shipping, or tracking.
- Confirm custom component script handles are registered, enqueued, and loaded before the Settings UI app mounts.
- Save each field and compare the stored option value against the legacy admin screen.
- Check console errors, failed REST requests, nonce failures, missing dependencies, and fields that render with blank defaults.
- Retest the runtime workflow that the setting controls, such as checkout, gateway routing, order email, or tracking payload.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Inventory fields | Inventory each settings section and field that controls checkout, payment, email, tax, shipping, or tracking. | Every critical field renders, saves, reloads, and affects the workflow it controls. |
| Enable on staging | Confirm custom component script handles are registered, enqueued, and loaded before the Settings UI app mounts. | No console error, missing dependency, or failed REST request appears during save. |
| Verify scripts | Save each field and compare the stored option value against the legacy admin screen. | The legacy settings screen still works when the feature flag is disabled. |
| Save and reload | Check console errors, failed REST requests, nonce failures, missing dependencies, and fields that render with blank defaults. | A checkout, email, tax, shipping, or tracking workflow proves the saved value is active. |
Why this usually happens
- A field can render in the new admin shell while saving a different value shape than the extension expects.
- A missing script dependency can make the page look normal but break one custom component.
- Legacy settings arrays and React components do not always agree on defaults or nested values.
- The real failure often appears at checkout, not on the settings page.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_filter('woocommerce_admin_features', static function (array $features): array {
$features[] = 'settings-ui';
return array_values(array_unique($features));
});
wp option get woocommerce_gateway_settings
wp option get woocommerce_tax_settings
# Open DevTools and watch console, network, and REST responses while saving.
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Inventory fields
- Enable on staging
- Verify scripts
- Save and reload
- Retest runtime
What to tell the client or owner
Report readiness by extension and field type. Avoid marking the whole store as ready from one settings page.
Production verification checklist
- Every critical field renders, saves, reloads, and affects the workflow it controls.
- No console error, missing dependency, or failed REST request appears during save.
- The legacy settings screen still works when the feature flag is disabled.
- A checkout, email, tax, shipping, or tracking workflow proves the saved value is active.
Mistakes to avoid
- Do not judge the fix by one browser or the homepage only.
- Do not delete evidence before recording usernames, file paths, timestamps, and response headers.
- Do not add a cache, security, or tracking plugin while the original problem is still unclear.
- Do not leave test users, temporary debug logs, or broad API keys active after verification.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, malware risk, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, test WooCommerce extension settings during updates.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references