For UIs where the user picks from products (and optionally variations) — meta boxes, settings pages, dashboard widgets. The mistake AI assistants consistently make is loading the entire product catalog into a static <select> upfront. WC has a built-in AJAX endpoint for exactly this, with proper variation support, and the wiring is two HTML attributes plus a server-side pre-render of the saved options.
\n\n\"I'll query all products with
\nposts_per_page = -1and feed them into a<select>for the user to pick from.\"
A WC store can have 20,000+ products plus 10× that in variations. Loading them all server-side is a hard timeout on render and a hard browser-freeze on render-into-DOM. WC ships an AJAX search endpoint for exactly this case — and it has a separate variant that includes variations.
\nTrigger when ANY of the following is true:
\n<select> populated by a WP_Query/get_posts over product post type — replace that pattern.wc-product-search, selectWoo, wc-enhanced-select, or data-action=\"woocommerce_json_search_*\".WC ships two product-search AJAX actions (wp-content/plugins/woocommerce/includes/class-wc-ajax.php:1768, 1844):
\n| Action name | \nWhat it returns | \n
|---|---|
woocommerce_json_search_products | \nProducts only (no variations). | \n
woocommerce_json_search_products_and_variations | \nProducts AND variations. | \n
The _and_variations variant is what you want most of the time for store-side features (related products, upsell/cross-sell, stock-rule targets, etc.) — variations are independently priced, stocked, and SKU'd, so a UI that can't pick variations is incomplete.
The variations endpoint is a one-line wrapper around the products one (self::json_search_products( '', true ) — $include_variations = true); same nonce, same data shape, the only difference is the result set.
The AJAX handler filters each candidate through wc_products_array_filter_readable() before sending JSON. WooCommerce 10.8 fixed hidden-product search visibility, so do not assume hidden/private products appear for every admin-like request. If a previously saved hidden product must remain visible in your field, the pre-rendered <option selected> loop is what preserves its label; the live search result list should still respect WC readability/capability rules.
const MYPLUGIN_META = '_myplugin_related_products';\n\nadd_action( 'add_meta_boxes_product', static function (): void {\n add_meta_box(\n 'myplugin-related-products',\n __( 'Related products', 'myplugin' ),\n 'myplugin_render_related_products_box',\n 'product',\n 'side',\n 'default'\n );\n} );\n\nfunction myplugin_render_related_products_box( WP_Post $post ): void {\n $saved_ids = (array) get_post_meta( $post->ID, MYPLUGIN_META, true );\n $saved_ids = array_filter( array_map( 'absint', $saved_ids ) );\n\n wp_nonce_field( 'myplugin_save_related', 'myplugin_nonce' );\n ?>\n <select\n id=\"myplugin-related-products\"\n name=\"<?php echo esc_attr( MYPLUGIN_META ); ?>[]\"\n class=\"wc-product-search\"\n multiple=\"multiple\"\n style=\"width: 100%;\"\n data-placeholder=\"<?php esc_attr_e( 'Search products and variations…', 'myplugin' ); ?>\"\n data-action=\"woocommerce_json_search_products_and_variations\"\n data-exclude=\"<?php echo intval( $post->ID ); ?>\"\n data-sortable=\"true\"\n >\n <?php\n // SERVER-SIDE pre-render of the saved options. The AJAX endpoint\n // only fires on user typing — without this loop, the select renders\n // empty even when meta has saved IDs.\n foreach ( $saved_ids as $product_id ) {\n $product = wc_get_product( $product_id );\n if ( $product instanceof WC_Product ) {\n echo '<option value=\"' . esc_attr( (string) $product_id ) . '\" selected=\"selected\">'\n . esc_html( wp_strip_all_tags( $product->get_formatted_name() ) )\n . '</option>';\n }\n }\n ?>\n </select>\n <?php\n}\n\nadd_action( 'save_post_product', static function ( int $post_id, WP_Post $post ): void {\n if ( ! isset( $_POST['myplugin_nonce'] ) ) return;\n if ( ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['myplugin_nonce'] ) ), 'myplugin_save_related' ) ) return;\n if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;\n if ( ! current_user_can( 'edit_product', $post_id ) ) return;\n\n $raw = isset( $_POST[ MYPLUGIN_META ] ) ? (array) wp_unslash( $_POST[ MYPLUGIN_META ] ) : array();\n $ids = array_values( array_filter( array_map( 'absint', $raw ) ) );\n\n if ( empty( $ids ) ) {\n delete_post_meta( $post_id, MYPLUGIN_META );\n return;\n }\n update_post_meta( $post_id, MYPLUGIN_META, $ids );\n}, 10, 2 );\nThat's the whole pattern. WC's wc-enhanced-select JS picks up the wc-product-search class on DOM-ready and turns the plain <select> into a selectWoo (a WC fork of select2) with AJAX search wired to the action you specified.
class=\"wc-product-search\" is the triggerThe WC enhanced-select script (wp-content/plugins/woocommerce/assets/js/admin/wc-enhanced-select.js) auto-initializes any <select> with this class. Without the class, your select stays a plain HTML control.
data-action controls products-only vs products+variations<!-- Products only -->\ndata-action=\"woocommerce_json_search_products\"\n\n<!-- Products AND variations (most common) -->\ndata-action=\"woocommerce_json_search_products_and_variations\"\nIf you omit data-action entirely, the JS defaults to woocommerce_json_search_products_and_variations (verified in wc-enhanced-select.js's ajax data handler). Be explicit anyway; readers shouldn't have to chase JS defaults.
The AJAX search runs only on user input (with minimumInputLength: 3 by default). It does not run on initial render. Without server-side pre-rendered <option selected> tags, the select shows empty even when meta is populated — the IDs are in the DB but the select doesn't know how to label them.
Pattern: wc_get_product( $id )->get_formatted_name() returns the WC-styled label including SKU, attributes, and parent product for variations (e.g. T-Shirt - Color: Red, Size: M (#42)). Use it.
data-* attributes| Attribute | \nPurpose | \nExample | \n
|---|---|---|
data-placeholder | \nEmpty-state placeholder | \nSearch products… | \n
data-action | \nWhich AJAX action to call | \nwoocommerce_json_search_products_and_variations | \n
data-exclude | \nID or JSON array of IDs to exclude | \n42 or [42,43] | \n
data-include | \nRestrict results to an ID or JSON array | \n[12,15] | \n
data-limit | \nRequested result limit | \n100 (default 30, filter woocommerce_json_search_limit) | \n
data-exclude_type | \nComma-list of product types to skip | \nexternal,grouped | \n
data-display_stock | \nAppend \" — Stock: N\" to labels for managed-stock items | \n1 | \n
data-allow_clear | \nShow a clear (x) control on single-value selects | \n1 | \n
data-minimum_input_length | \nOverride default 3-char minimum | \n2 | \n
data-sortable=\"true\" | \nEnable drag-sort on multi-select chips | \ntrue | \n
Do not pass multiple IDs as a comma-separated string to data-exclude or data-include: the PHP handler casts the request to an array and then applies absint, so \"12,15\" collapses to 12. Core emits multiple IDs as JSON ([12,15]), which jQuery parses into an array. data-exclude_type is the exception: its handler explicitly accepts a comma-delimited value.
WC's AJAX handler verifies check_ajax_referer( 'search-products', 'security' ) (class-wc-ajax.php:1769). The nonce is auto-attached by wc-enhanced-select.js from the wc_enhanced_select_params.search_products_nonce PHP-localized variable. Don't try to add your own nonce to the AJAX request — WC handles it.
wc-enhanced-select is auto-enqueued on WC admin screensWC enqueues wc-enhanced-select (plus selectWoo, plus the matching styles) on every screen returned by wc_get_screen_ids() (wp-content/plugins/woocommerce/includes/admin/class-wc-admin-assets.php:412-415). That covers: product edit / new screens, orders, coupons, shipping, settings, etc. You do not need to manually enqueue on those.
For the same <select> markup on a non-WC admin page (your plugin's settings page, a dashboard widget, a modal in the post-type editor of another CPT), explicit enqueue IS needed:
add_action( 'admin_enqueue_scripts', static function ( string $hook_suffix ): void {\n if ( $hook_suffix !== 'my-plugin_page_my-settings' ) return; // gate to your screen\n\n wp_enqueue_script( 'wc-enhanced-select' );\n wp_enqueue_style( 'woocommerce_admin_styles' );\n} );\nThe handles are stable: wc-enhanced-select (JS) and woocommerce_admin_styles (CSS). The dependency on selectWoo is declared internally by the WC handle; you don't need to enqueue selectWoo separately.
The <select multiple> posts as an array of strings. Always array_map( 'absint', $raw ) and array_filter to drop empties. Never trust the IDs back from the form — a user can craft a <option value=\"9999999\"> and submit it. If the ID space matters (the picked products must be readable to the current user), revalidate with wc_get_product( $id ) and current_user_can( 'read_product', $id ) before storing.
// WRONG — load all products upfront, freeze the page on stores with > a few hundred\n$products = get_posts( array( 'post_type' => 'product', 'posts_per_page' => -1 ) );\necho '<select multiple>';\nforeach ( $products as $p ) {\n echo '<option value=\"' . $p->ID . '\">' . $p->post_title . '</option>';\n}\necho '</select>';\n\n// WRONG — missing pre-render of saved values; on edit the select shows empty\necho '<select class=\"wc-product-search\" name=\"related_products[]\"\n multiple=\"multiple\"\n data-action=\"woocommerce_json_search_products_and_variations\"></select>';\n// Saved IDs are in DB but invisible in the UI; user thinks the data is lost.\n\n// WRONG — products only when variations are needed\ndata-action=\"woocommerce_json_search_products\"\n// Cross-sell-style features almost always need to target specific variations.\n\n// WRONG — manually enqueueing on the product edit screen (redundant)\nadd_action( 'admin_enqueue_scripts', function () {\n wp_enqueue_script( 'wc-enhanced-select' ); // already loaded by WC here\n} );\n// Harmless but adds noise. Only enqueue manually on NON-WC admin screens.\n\n// WRONG — saving raw $_POST without sanitization\nupdate_post_meta( $post_id, '_related_products', $_POST['related_products'] );\n// Allows attacker to inject arbitrary IDs / strings.\n\n// RIGHT — sanitize-then-save\n$ids = array_values( array_filter( array_map( 'absint', (array) wp_unslash( $_POST['related_products'] ?? array() ) ) ) );\nupdate_post_meta( $post_id, '_related_products', $ids );\n$ids = (array) get_post_meta( $post_id, '_myplugin_related_products', true );\nforeach ( $ids as $id ) {\n $product = wc_get_product( (int) $id );\n if ( ! $product instanceof WC_Product ) {\n continue; // product was deleted\n }\n\n if ( $product->is_type( 'variation' ) ) {\n // Variation-specific handling: $product->get_parent_id(), get_attributes()\n } else {\n // Regular / variable / grouped / external\n }\n\n // For frontend display:\n echo esc_html( $product->get_name() );\n echo wc_price( (float) $product->get_price() );\n}\nThe IDs returned by the search endpoint are post IDs that may belong to either product or product_variation post types. wc_get_product() handles both transparently.
wc-shipping-method if the broader plugin context is shipping — the shipping zones admin uses the same Backbone-modal pattern with PHP-rendered HTML; nothing in WC admin is React-only.wp-plugin-architecture for the broader question of how to organize the meta box class file alongside other plugin code.wp-security-audit on the save handler — it's an admin-context write endpoint with attacker-controlled input.wc/product-control from @woocommerce/components); not the same wiring./wc/v3/products with ?search=). That's for external integrations, not admin UI; this skill is admin-UI-specific.get_formatted_name() returns. The endpoint returns plain text labels via wp_strip_all_tags; richer renderings require a custom AJAX handler or a per-result formatter, both out of scope here.WC_AJAX::json_search_products and json_search_products_and_variations: wp-content/plugins/woocommerce/includes/class-wc-ajax.php (lines ~1768 and 1844).wc-enhanced-select.js — the JS that turns class=\"wc-product-search\" into selectWoo with AJAX wiring: wp-content/plugins/woocommerce/assets/js/admin/wc-enhanced-select.js.WC_Data_Store::load( 'product' )->search_products() — the underlying query method called by the AJAX handler. Worth reading if you need a programmatic equivalent of the AJAX search (e.g. WP-CLI command).search_products().