Using Add-Ons

This walkthrough goes from a fresh install to working product options, then explains what the shopper and the store see at each step.

1. Set the store-wide display

Open WooCommerce → Add-Ons and decide how the group reads across the store: the group heading, whether to show prices next to paid options, whether to mark required fields with an asterisk, and whether to wrap the options in a card. These are presentation choices, the fields are defined per product.

2. Add fields to a product

Edit the product and open the Add-Ons tab in the Product data panel. Click Add option for each row. Some common patterns:

• Engraving text, a Text field, no price. The shopper types a message.
• Gift wrap, a Checkbox with a small price. Ticking it adds the cost to the line.
• Warranty length, a Select with options 1 year | 0 and 3 years | 20, each choice carrying its own price.

Mark a field Required when the product cannot ship without it, a name for a personalised item, say. The product-data tab appears on simple and variable products.

3. Confirm on the product page

Open the product on the storefront. The fields render just above the Add to cart button, under the heading you set. Paid options show their price in brackets if Show prices is on. When a shopper fills a text field or picks a select choice, the field draws a small ink underline, a presentation-only cue that the choice is committed, driven by a deferred vanilla-JavaScript class toggle that changes no values.

4. Watch the price and validation

• Picking a paid option updates the cart line total automatically, the delta is added on woocommerce_before_calculate_totals.
• If a required field is left empty, WooCommerce blocks the add-to-cart and shows a notice naming the field: Please complete the “Engraving text” option before adding to cart.

5. Follow the choice through the order

The shopper’s selections appear:

• in the cart, under the product line,
• at checkout,
• on the order the store receives, written as line-item meta keyed by the field label (with the price appended when the choice cost extra), so staff can read the engraving text or see that gift wrapping was selected.

Free and paid in one form

A single product can mix free and paid fields, a free engraving message alongside a paid gift-wrap checkbox. Leave a field’s price blank to keep it free; the choice is still recorded through to the order.

Theming the fields

The storefront styles are built on --addons-* CSS custom properties, gap, radius, border, surface and the selection accent, so you can re-theme the fields from your theme stylesheet without fighting markup. The accent inherits your theme’s primary colour (--wp--preset--color--primary) when one is exposed. Focus-visible rings, a dark-mode palette and prefers-reduced-motion handling are built in and need no configuration. The fields are server-rendered and reserve their space, so they do not cause layout shift.

Developer hooks

Add-Ons keeps the free storage format stable and exposes hooks so a PRO extension (or your own code) can reshape definitions without forking the templates. The internal boot signals are not part of this contract.

Filters

• addons_product_definitions, filter a product’s active definitions before they are rendered and validated. Receives the definitions array and the WC_Product.
• addons_supported_definition_types, extend the field types accepted on save. Defaults to ['text', 'checkbox', 'select'].
• addons_sanitize_definition, adjust a single sanitised definition before it is persisted (for example to attach extra metadata). Receives the clean definition and the raw posted row.

Actions

• addons_product_data_row_fields, render extra inputs inside an existing definition row in the product editor. Receives the row index and the stored row data.
• addons_product_data_row_template_fields, render the same extra inputs inside the JavaScript “new row” template; use the __INDEX__ placeholder in input names so the repeater can substitute a fresh index.

Register a new field type so it is accepted on save:

add_filter( 'addons_supported_definition_types', function ( array $types ): array {
    $types[] = 'textarea';
    return $types;
} );

Hide some definitions on the front end without changing what is stored:

add_filter( 'addons_product_definitions', function ( array $definitions, WC_Product $product ): array {
    if ( ! is_user_logged_in() ) {
        // Drop members-only add-ons for guests.
        $definitions = array_values( array_filter(
            $definitions,
            static fn ( array $def ): bool => empty( $def['members_only'] )
        ) );
    }
    return $definitions;
}, 10, 2 );

When to reach for Pro

The free edition covers text, checkbox and select fields, free or priced, with validation and order display. Add-Ons Pro adds conditional logic, showing or hiding fields based on earlier choices, and file uploads. See Add-Ons Pro.