wc-visual attribute type. Covers feature gating, global pa_* attribute taxonomies, the WooCommerce 11 slug byte limit, color/image term meta, visual admin search results, Store API __experimental_visual / __experimentalVisual, classic dropdown fallbacks, and safe rendering. Use for variation swatches, visual attributes, wc-visual, term_color, term_image, woocommerce_json_search_found_product_attribute_terms, or custom swatch UI.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"woocommerce\"\nwp-skills-plugin-version-tested: \"11.0.0\"\nwp-skills-php-min: \"7.4\"\nwp-skills-last-updated: \"2026-08-05\"Use this skill when a plugin or theme needs to read, write, render, or audit WooCommerce visual product attributes. In WooCommerce 11.0 this is not a mature \"classic variation swatches\" template API. It is an experimental wc-visual product attribute type with color/image term metadata, consumed by selected block UI and optionally exposed by Store API.
wc-visual-attribute.woocommerce_feature_wc_visual_attribute_enabled.wc_get_attribute_types() only exposes wc-visual when the site is a block theme with the feature enabled, or when the store already has an existing wc-visual attribute.wc-visual.Color / image.color, image, none.color hex string and image attachment ID. Image wins over color when both exist; core save logic deletes the other key.wc_dropdown_variation_attribute_options() selects. It does not output swatch buttons by itself.__experimental_visual=true; response property is __experimentalVisual.Only global product attributes can be visual attributes. A visual attribute is still a WooCommerce attribute taxonomy:
\nwoocommerce_attribute_taxonomies.attribute_name = color\nwoocommerce_attribute_taxonomies.attribute_type = wc-visual\ntaxonomy slug = pa_color\nterm meta color = #2271b1\nterm meta image = attachment ID\nDo not treat custom per-product text attributes as swatch sources. They have no term IDs, no color or image term meta, and no Store API visual payload.
Avoid importing Automattic\\WooCommerce\\Internal\\ProductAttributes\\VisualAttributeTermMeta in plugin code unless there is no alternative; it is marked @internal. Mirror the storage contract through public WP/Woo APIs instead.
function myplugin_is_wc_visual_attribute_taxonomy( string $taxonomy ): bool {\n if ( ! function_exists( 'wc_get_attribute_taxonomies' ) || ! function_exists( 'wc_attribute_taxonomy_name' ) ) {\n return false;\n }\n\n foreach ( wc_get_attribute_taxonomies() as $attribute ) {\n if (\n isset( $attribute->attribute_type, $attribute->attribute_name ) &&\n 'wc-visual' === $attribute->attribute_type &&\n wc_attribute_taxonomy_name( $attribute->attribute_name ) === $taxonomy\n ) {\n return true;\n }\n }\n\n return false;\n}\n\nfunction myplugin_get_wc_term_visual( int $term_id, string $image_size = 'thumbnail' ): array {\n $image_id = absint( get_term_meta( $term_id, 'image', true ) );\n\n if ( $image_id && wp_attachment_is_image( $image_id ) ) {\n $image_url = wp_get_attachment_image_url( $image_id, $image_size );\n\n if ( $image_url ) {\n return array(\n 'type' => 'image',\n 'value' => $image_url,\n );\n }\n }\n\n $color = sanitize_hex_color( get_term_meta( $term_id, 'color', true ) );\n\n if ( $color ) {\n return array(\n 'type' => 'color',\n 'value' => $color,\n );\n }\n\n return array(\n 'type' => 'none',\n 'value' => '',\n );\n}\nFor lists, call update_meta_cache( 'term', $term_ids ) before looping terms. If image swatches are common and the page renders many terms, collect attachment IDs from term meta and prime post caches before calling wp_get_attachment_image_url().
Write mutually exclusive term meta. Validate capability and nonce in the caller; this helper only normalizes storage.
\nfunction myplugin_set_wc_term_visual( int $term_id, string $color = '', int $image_id = 0 ): void {\n if ( $image_id && wp_attachment_is_image( $image_id ) ) {\n update_term_meta( $term_id, 'image', absint( $image_id ) );\n delete_term_meta( $term_id, 'color' );\n return;\n }\n\n $color = sanitize_hex_color( $color );\n\n if ( $color ) {\n update_term_meta( $term_id, 'color', $color );\n delete_term_meta( $term_id, 'image' );\n return;\n }\n\n delete_term_meta( $term_id, 'color' );\n delete_term_meta( $term_id, 'image' );\n}\nWhen creating an attribute programmatically, verify that wc_get_attribute_types() currently contains wc-visual. wc_create_attribute() validates the type against that function and silently falls back to select when wc-visual is not available.
if ( array_key_exists( 'wc-visual', wc_get_attribute_types() ) ) {\n $attribute_id = wc_create_attribute( array(\n 'name' => 'Color',\n 'slug' => 'color',\n 'type' => 'wc-visual',\n 'order_by' => 'menu_order',\n ) );\n}\nDo not force-create visual attributes on classic-theme stores just to get swatches. In 11.0 WooCommerce intentionally hides the feature setting UI outside block themes unless a visual attribute already exists.
\nWordPress limits taxonomy names to 32 bytes and Woo prefixes global product attributes with pa_. WooCommerce 11.0 exposes wc_get_attribute_slug_max_byte_length(), currently 29 bytes, and validates with strlen() rather than a character count.
Use the helper when validating/importing attribute slugs and return the WP_Error from wc_create_attribute() instead of truncating blindly. A 29-character multibyte slug can exceed 29 bytes; truncating by characters can still create an invalid taxonomy or collide with another normalized slug.
Use Store API only for shopper-facing reads. Fetch attribute IDs first, then opt into experimental visual data for terms:
\nGET /wp-json/wc/store/v1/products/attributes\nGET /wp-json/wc/store/v1/products/attributes/12/terms?__experimental_visual=true\nReturned term objects may include:
\n{\n \"id\": 34,\n \"name\": \"Blue\",\n \"slug\": \"blue\",\n \"__experimentalVisual\": {\n \"type\": \"color\",\n \"value\": \"#2271b1\"\n }\n}\nRules:
\n__experimental_visual is true and the term belongs to a wc-visual taxonomy.type=image returns an image URL, not an attachment object.type=color returns a sanitized hex color.type=none means no valid visual value./wc/v3/products/attributes exposes the attribute type, but do not assume the classic REST attribute-term endpoints expose the visual payload.For a visual taxonomy, WooCommerce enriches valid term objects returned through woocommerce_json_search_found_product_attribute_terms with a dynamic visual property shaped as { type, value }. Types are color, image, or none; image values are thumbnail URLs.
Treat the property defensively: the core enrichment callback is internal, non-visual taxonomies do not receive it, earlier Woo versions omit it, and another filter may return an error or nonstandard entries. Do not mutate the public filter's results into a different base shape that breaks Woo's admin selector.
\nKeep the native .variations select and attribute_pa_* field as the authoritative submission/accessibility contract. Swatch buttons are progressive enhancement: drive the select, trigger change, and synchronize selection and disabled states after Woo's woocommerce_update_variation_values and reset_data events.
Use type=\"button\", accessible names, synchronized aria-pressed, visible focus, and disabled states matching the select. If the design removes the select, implement a complete accessible radio-group including keyboard behavior. See references/classic-rendering.md for the PHP filter and JavaScript synchronization pattern.
product_variation posts. In core 11.0 the swatch data belongs to attribute terms, not variations.attribute_pa_* select values.wc-visual attributes on classic-theme stores and assuming the feature is supported. The 11.0 UI gate is deliberate.wc_get_attribute_slug_max_byte_length().__experimental_visual=true.Use wc-variations-data for real variation CRUD/sync, wc-variation-gallery for per-variation image sets, and wc-variations-pricing-filters when selection affects price/availability display.
wp-content/plugins/woocommerce/includes/wc-attribute-functions.phpwp-content/plugins/woocommerce/src/Internal/Features/FeaturesController.phpwp-content/plugins/woocommerce/src/Internal/ProductAttributes/VisualAttributeTermMeta.phpwp-content/plugins/woocommerce/src/Internal/ProductAttributes/VisualAttributeTermAdmin.phpwp-content/plugins/woocommerce/src/StoreApi/Routes/V1/ProductAttributeTerms.phpwp-content/plugins/woocommerce/src/StoreApi/Schemas/V1/ProductAttributeTermSchema.phpwp-content/plugins/woocommerce/includes/admin/meta-boxes/views/html-product-attribute-inner.phpwp-content/plugins/woocommerce/includes/wc-template-functions.phpwp-content/plugins/woocommerce/templates/single-product/add-to-cart/variable.php