WooCommerce handles simple products well out of the box, but real-world stores often need more. Whether you’re selling personalized jewelry, custom-printed merchandise, or configurable industrial parts, your products need custom fields and add-ons that go beyond standard variations. Building a proper WooCommerce product customizer lets customers configure exactly what they want while keeping your order management clean and automated.
In this comprehensive guide, you’ll learn how to create custom product fields, implement conditional logic, handle pricing adjustments, support file uploads, and build display templates that integrate seamlessly with WooCommerce’s cart and checkout flow. Every technique here uses WooCommerce’s native hooks and APIs, no page builders or drag-and-drop plugins required. If you’re new to building custom product types, check out our guide on how to build custom WooCommerce product types first.
Understanding WooCommerce Product Data Architecture
Before writing any code, it helps to understand how WooCommerce stores product data. Products in WooCommerce are custom post types (product) with metadata stored in the wp_postmeta table. When a product is added to the cart, WooCommerce creates a cart item array that travels through the entire purchase flow, from cart to checkout to order.
The key hooks for product customization follow this lifecycle:
- Display phase:
woocommerce_before_add_to_cart_button, render custom fields on the product page - Validation phase:
woocommerce_add_to_cart_validation, validate user input before adding to cart - Cart phase:
woocommerce_add_cart_item_data, attach custom data to the cart item - Display in cart:
woocommerce_get_item_data, show custom data in cart/checkout - Order phase:
woocommerce_checkout_create_order_line_item, save data to the order
This hook chain is the backbone of every custom field implementation. Miss one hook and your data either won’t save, won’t display, or won’t persist to the order. Let’s build each piece.
Creating Custom Field Types for Products
The most common product add-ons are text inputs, dropdowns, checkboxes, radio buttons, date pickers, and color selectors. Here’s how to render them on the product page using the woocommerce_before_add_to_cart_button hook.
Text Input Fields
Text fields are perfect for engraving text, custom messages, or personalization. The implementation starts with rendering the field:
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_custom_text_field' );
function wccd_render_custom_text_field() {
global $product;
// Only show on products that have custom fields enabled
$enable_custom = $product->get_meta( '_wccd_enable_custom_text' );
if ( 'yes' !== $enable_custom ) {
return;
}
$label = $product->get_meta( '_wccd_text_label' ) ?: 'Custom Text';
$maxlength = $product->get_meta( '_wccd_text_maxlength' ) ?: 50;
$required = $product->get_meta( '_wccd_text_required' ) === 'yes';
echo '<div class="wccd-custom-field wccd-text-field">';
echo '<label for="wccd_custom_text">' . esc_html( $label );
if ( $required ) {
echo ' <span class="required">*</span>';
}
echo '</label>';
printf(
'<input type="text" id="wccd_custom_text" name="wccd_custom_text" maxlength="%d" %s />',
intval( $maxlength ),
$required ? 'required' : ''
);
echo '<small class="wccd-char-count">0/' . intval( $maxlength ) . ' characters</small>';
echo '</div>';
}Notice how we check for a product-level meta flag (_wccd_enable_custom_text) before rendering. This lets store owners enable custom fields per product from the admin, rather than showing them on every product globally.
Dropdown and Radio Button Fields
Dropdown selects work well for predefined options like material choices, sizes that don’t fit standard WooCommerce variations, or service tiers:
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_dropdown_field' );
function wccd_render_dropdown_field() {
global $product;
$options_raw = $product->get_meta( '_wccd_dropdown_options' );
if ( empty( $options_raw ) ) {
return;
}
// Options stored as "Label|price_adjustment" per line
$options = array_filter( array_map( 'trim', explode( "\n", $options_raw ) ) );
$label = $product->get_meta( '_wccd_dropdown_label' ) ?: 'Choose an Option';
echo '<div class="wccd-custom-field wccd-dropdown-field">';
echo '<label for="wccd_dropdown">' . esc_html( $label ) . '</label>';
echo '<select id="wccd_dropdown" name="wccd_dropdown">';
echo '<option value="">Select...</option>';
foreach ( $options as $option ) {
$parts = explode( '|', $option );
$opt_label = trim( $parts[0] );
$opt_price = isset( $parts[1] ) ? floatval( $parts[1] ) : 0;
$display = $opt_label;
if ( $opt_price > 0 ) {
$display .= ' (+' . wc_price( $opt_price ) . ')';
}
printf(
'<option value="%s" data-price="%s">%s</option>',
esc_attr( sanitize_title( $opt_label ) ),
esc_attr( $opt_price ),
wp_kses_post( $display )
);
}
echo '</select>';
echo '</div>';
}The data-price attribute on each option enables JavaScript-driven price updates on the frontend, which we’ll implement in the pricing adjustments section below.
Checkbox Groups
Checkboxes let customers select multiple add-ons simultaneously, gift wrapping, rush processing, insurance, etc.:
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_checkbox_group' );
function wccd_render_checkbox_group() {
global $product;
$addons = $product->get_meta( '_wccd_checkbox_addons' );
if ( empty( $addons ) || ! is_array( $addons ) ) {
return;
}
echo '<div class="wccd-custom-field wccd-checkbox-group">';
echo '<p class="wccd-group-label">Optional Add-Ons</p>';
foreach ( $addons as $addon ) {
$id = sanitize_title( $addon['label'] );
$price = floatval( $addon['price'] );
printf(
'<label class="wccd-checkbox-label">'
. '<input type="checkbox" name="wccd_addons[]" value="%s" data-price="%s" /> '
. '%s (+%s)'
. '</label>',
esc_attr( $id ),
esc_attr( $price ),
esc_html( $addon['label'] ),
wp_kses_post( wc_price( $price ) )
);
}
echo '</div>';
}Implementing Conditional Logic for Product Fields
Conditional logic makes your product forms smart, showing or hiding fields based on other selections. For example, showing an engraving text field only when the customer selects “Add Engraving” checkbox, or showing material-specific options only when a particular material is chosen from a dropdown.
The cleanest approach combines PHP data attributes with JavaScript event listeners:
// PHP: Add conditional attributes to fields
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_conditional_fields' );
function wccd_render_conditional_fields() {
global $product;
$conditions = $product->get_meta( '_wccd_field_conditions' );
if ( empty( $conditions ) ) {
return;
}
foreach ( $conditions as $field ) {
printf(
'<div class="wccd-conditional-field" '
. 'data-show-when-field="%s" '
. 'data-show-when-value="%s" '
. 'style="display:none;">',
esc_attr( $field['depends_on'] ),
esc_attr( $field['depends_value'] )
);
// Render the actual field based on type
wccd_render_field_by_type( $field );
echo '</div>';
}
}
// JavaScript: Handle conditional visibility
add_action( 'wp_footer', 'wccd_conditional_logic_script' );
function wccd_conditional_logic_script() {
if ( ! is_product() ) {
return;
}
?>
<script>
(function($) {
function updateConditionalFields() {
$('.wccd-conditional-field').each(function() {
var $field = $(this);
var dependsOn = $field.data('show-when-field');
var dependsVal = String($field.data('show-when-value'));
var $source = $('[name="' + dependsOn + '"]');
var currentVal;
if ($source.is(':checkbox')) {
currentVal = $source.is(':checked') ? 'yes' : 'no';
} else {
currentVal = $source.val();
}
if (currentVal === dependsVal) {
$field.slideDown(200);
$field.find(':input').prop('disabled', false);
} else {
$field.slideUp(200);
$field.find(':input').prop('disabled', true);
}
});
}
$(document).on('change', '.wccd-custom-field :input', updateConditionalFields);
updateConditionalFields();
})(jQuery);
</script>
<?php
}The key insight here is disabling hidden inputs with prop('disabled', true). Disabled inputs don’t submit with the form, so your validation logic doesn’t need to worry about hidden required fields. This prevents the common bug where customers can’t add to cart because a hidden required field is empty.
Pricing Adjustments Based on Custom Fields
Dynamic pricing is where product add-ons get commercially useful. There are two sides to pricing: the frontend display (showing the updated price as customers select options) and the backend calculation (actually charging the right amount). If you’re also working on your checkout experience, see our guide on customizing the WooCommerce checkout flow for higher conversions.
Frontend Price Updates
Show customers real-time price changes as they configure their product:
add_action( 'wp_footer', 'wccd_dynamic_pricing_script' );
function wccd_dynamic_pricing_script() {
if ( ! is_product() ) {
return;
}
global $product;
?>
<script>
(function($) {
var basePrice = get_price() ); ?>;
var currencySymbol = '';
function recalculatePrice() {
var totalAddon = 0;
// Sum dropdown selections
$('select[name^="wccd_"]').each(function() {
var selected = $(this).find(':selected');
totalAddon += parseFloat(selected.data('price') || 0);
});
// Sum checked checkboxes
$('input[name^="wccd_"]:checkbox:checked').each(function() {
totalAddon += parseFloat($(this).data('price') || 0);
});
// Calculate per-character pricing (e.g., engraving)
$('input[data-price-per-char]').each(function() {
var chars = $(this).val().length;
totalAddon += chars * parseFloat($(this).data('price-per-char') || 0);
});
var finalPrice = basePrice + totalAddon;
$('.wccd-dynamic-price').html(
'<span class="woocommerce-Price-amount">'
+ currencySymbol + finalPrice.toFixed(2)
+ '</span>'
);
}
// Inject price display element
$('form.cart .single_add_to_cart_button').before(
'<div class="wccd-dynamic-price-wrap">'
+ '<span class="wccd-price-label">Total: </span>'
+ '<span class="wccd-dynamic-price">' + currencySymbol + basePrice.toFixed(2) + '</span>'
+ '</div>'
);
$(document).on('change keyup', '.wccd-custom-field :input', recalculatePrice);
})(jQuery);
</script>
<?php
}Backend Price Calculation
Frontend price display is cosmetic, the actual price must be calculated server-side. Never trust client-side pricing. Use the woocommerce_before_calculate_totals hook:
add_action( 'woocommerce_before_calculate_totals', 'wccd_adjust_cart_item_price', 20 );
function wccd_adjust_cart_item_price( $cart ) {
if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
return;
}
if ( did_action( 'woocommerce_before_calculate_totals' ) >= 2 ) {
return;
}
foreach ( $cart->get_cart() as $cart_item ) {
if ( ! isset( $cart_item['wccd_addon_price'] ) ) {
continue;
}
$base_price = floatval( $cart_item['data']->get_regular_price() );
$addon_price = floatval( $cart_item['wccd_addon_price'] );
$cart_item['data']->set_price( $base_price + $addon_price );
}
}The did_action check prevents the price from being doubled on pages where WooCommerce calculates totals multiple times (like the checkout page). This is a common pitfall that causes customers to be overcharged.
Handling File Uploads as Product Add-Ons
File uploads are essential for print-on-demand products, custom artwork submissions, or document-based services. The implementation needs to handle the upload before the item is added to cart, validate file types and sizes, and attach the file to the eventual order.
Rendering the Upload Field
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_file_upload' );
function wccd_render_file_upload() {
global $product;
if ( 'yes' !== $product->get_meta( '_wccd_enable_file_upload' ) ) {
return;
}
$allowed = $product->get_meta( '_wccd_allowed_types' ) ?: 'jpg,png,pdf';
$max_size = $product->get_meta( '_wccd_max_file_size' ) ?: 5; // MB
$upload_label = $product->get_meta( '_wccd_upload_label' ) ?: 'Upload Your Design';
// Add enctype to the cart form
add_action( 'wp_footer', function() {
echo '<script>jQuery("form.cart").attr("enctype", "multipart/form-data");</script>';
});
echo '<div class="wccd-custom-field wccd-file-upload">';
printf(
'<label for="wccd_file_upload">%s</label>',
esc_html( $upload_label )
);
echo '<input type="file" id="wccd_file_upload" name="wccd_file_upload" ';
printf( 'accept=".%s" />', esc_attr( str_replace( ',', '.', $allowed ) ) );
printf(
'<small>Accepted formats: %s (max %dMB)</small>',
esc_html( strtoupper( $allowed ) ),
intval( $max_size )
);
echo '</div>';
}Processing the Upload
Handle the file during the add-to-cart validation phase. Store the uploaded file in a private directory (not the public uploads folder) and save the path as cart item data:
add_filter( 'woocommerce_add_to_cart_validation', 'wccd_validate_file_upload', 10, 3 );
function wccd_validate_file_upload( $passed, $product_id, $quantity ) {
$product = wc_get_product( $product_id );
if ( 'yes' !== $product->get_meta( '_wccd_enable_file_upload' ) ) {
return $passed;
}
if ( empty( $_FILES['wccd_file_upload']['name'] ) ) {
if ( 'yes' === $product->get_meta( '_wccd_file_required' ) ) {
wc_add_notice( 'Please upload a file.', 'error' );
return false;
}
return $passed;
}
$file = $_FILES['wccd_file_upload'];
$allowed = explode( ',', $product->get_meta( '_wccd_allowed_types' ) ?: 'jpg,png,pdf' );
$max_size = intval( $product->get_meta( '_wccd_max_file_size' ) ?: 5 ) * 1024 * 1024;
$extension = strtolower( pathinfo( $file['name'], PATHINFO_EXTENSION ) );
if ( ! in_array( $extension, $allowed, true ) ) {
wc_add_notice( 'Invalid file type. Allowed: ' . implode( ', ', $allowed ), 'error' );
return false;
}
if ( $file['size'] > $max_size ) {
wc_add_notice( 'File too large. Maximum size: ' . size_format( $max_size ), 'error' );
return false;
}
// Upload to a private directory
$upload_dir = wp_upload_dir();
$private_dir = $upload_dir['basedir'] . '/wccd-uploads/' . date( 'Y/m' );
wp_mkdir_p( $private_dir );
// Add .htaccess to prevent direct access
$htaccess = $upload_dir['basedir'] . '/wccd-uploads/.htaccess';
if ( ! file_exists( $htaccess ) ) {
file_put_contents( $htaccess, 'deny from all' );
}
$filename = wp_unique_filename( $private_dir, sanitize_file_name( $file['name'] ) );
$filepath = $private_dir . '/' . $filename;
if ( ! move_uploaded_file( $file['tmp_name'], $filepath ) ) {
wc_add_notice( 'Upload failed. Please try again.', 'error' );
return false;
}
// Store path temporarily in session for the cart item data hook
WC()->session->set( 'wccd_uploaded_file', $filepath );
WC()->session->set( 'wccd_uploaded_name', $file['name'] );
return $passed;
}Security is critical here. The uploaded files go into a directory protected by .htaccess to prevent direct URL access. The original filename is sanitized, and we validate both the extension and file size server-side regardless of client-side restrictions.
Engraving and Personalization Options
Personalization is one of the highest-value product customizations. Engraving, monogramming, and custom printing often command premium prices. Here’s a complete personalization system with preview:
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_engraving_field' );
function wccd_render_engraving_field() {
global $product;
if ( 'yes' !== $product->get_meta( '_wccd_enable_engraving' ) ) {
return;
}
$price_per_char = floatval( $product->get_meta( '_wccd_engraving_price_per_char' ) ?: 0.50 );
$max_chars = intval( $product->get_meta( '_wccd_engraving_max_chars' ) ?: 20 );
$fonts = $product->get_meta( '_wccd_engraving_fonts' ) ?: array( 'serif', 'sans-serif', 'cursive' );
echo '<div class="wccd-custom-field wccd-engraving">';
echo '<h4>Personalization</h4>';
// Font selection
echo '<label for="wccd_engraving_font">Font Style</label>';
echo '<select id="wccd_engraving_font" name="wccd_engraving_font">';
foreach ( $fonts as $font ) {
printf(
'<option value="%s" style="font-family:%s">%s</option>',
esc_attr( $font ),
esc_attr( $font ),
esc_html( ucfirst( $font ) )
);
}
echo '</select>';
// Text input
printf(
'<label for="wccd_engraving_text">Engraving Text (%s per character)</label>',
wp_kses_post( wc_price( $price_per_char ) )
);
printf(
'<input type="text" id="wccd_engraving_text" name="wccd_engraving_text" '
. 'maxlength="%d" data-price-per-char="%s" placeholder="Enter your text..." />',
$max_chars,
esc_attr( $price_per_char )
);
// Live preview
echo '<div class="wccd-engraving-preview">';
echo '<p class="preview-label">Preview:</p>';
echo '<div id="wccd-preview-text" style="font-family:serif; font-size:24px; padding:10px; border:1px dashed #ccc; min-height:40px;"></div>';
echo '</div>';
echo '</div>';
}
add_action( 'wp_footer', 'wccd_engraving_preview_script' );
function wccd_engraving_preview_script() {
if ( ! is_product() ) {
return;
}
?>
<script>
(function($) {
$('#wccd_engraving_text').on('keyup', function() {
var font = $('#wccd_engraving_font').val();
$('#wccd-preview-text')
.text($(this).val())
.css('font-family', font);
});
$('#wccd_engraving_font').on('change', function() {
$('#wccd-preview-text').css('font-family', $(this).val());
});
})(jQuery);
</script>
<?php
}The live preview gives customers confidence in their personalization before purchase, reducing returns and support tickets significantly.
Cart Data Persistence and Display
Custom field data must travel through the entire WooCommerce purchase flow. This requires hooking into the cart, checkout display, and order creation stages. Here’s the complete data persistence chain:
Adding Data to Cart Items
add_filter( 'woocommerce_add_cart_item_data', 'wccd_add_custom_data_to_cart', 10, 2 );
function wccd_add_custom_data_to_cart( $cart_item_data, $product_id ) {
$addon_price = 0;
// Text field
if ( ! empty( $_POST['wccd_custom_text'] ) ) {
$cart_item_data['wccd_custom_text'] = sanitize_text_field( $_POST['wccd_custom_text'] );
}
// Dropdown
if ( ! empty( $_POST['wccd_dropdown'] ) ) {
$product = wc_get_product( $product_id );
$options = explode( "\n", $product->get_meta( '_wccd_dropdown_options' ) );
$selected = sanitize_text_field( $_POST['wccd_dropdown'] );
foreach ( $options as $option ) {
$parts = explode( '|', $option );
if ( sanitize_title( trim( $parts[0] ) ) === $selected ) {
$cart_item_data['wccd_dropdown_label'] = trim( $parts[0] );
$addon_price += isset( $parts[1] ) ? floatval( $parts[1] ) : 0;
break;
}
}
}
// Checkboxes
if ( ! empty( $_POST['wccd_addons'] ) && is_array( $_POST['wccd_addons'] ) ) {
$product = wc_get_product( $product_id );
$addons = $product->get_meta( '_wccd_checkbox_addons' );
$selected_addons = array();
foreach ( $_POST['wccd_addons'] as $addon_id ) {
$addon_id = sanitize_text_field( $addon_id );
foreach ( $addons as $addon ) {
if ( sanitize_title( $addon['label'] ) === $addon_id ) {
$selected_addons[] = $addon['label'];
$addon_price += floatval( $addon['price'] );
}
}
}
$cart_item_data['wccd_selected_addons'] = $selected_addons;
}
// Engraving
if ( ! empty( $_POST['wccd_engraving_text'] ) ) {
$text = sanitize_text_field( $_POST['wccd_engraving_text'] );
$product = wc_get_product( $product_id );
$price_per_char = floatval( $product->get_meta( '_wccd_engraving_price_per_char' ) ?: 0.50 );
$cart_item_data['wccd_engraving_text'] = $text;
$cart_item_data['wccd_engraving_font'] = sanitize_text_field( $_POST['wccd_engraving_font'] ?? 'serif' );
$addon_price += strlen( $text ) * $price_per_char;
}
// File upload
$uploaded_file = WC()->session->get( 'wccd_uploaded_file' );
if ( $uploaded_file ) {
$cart_item_data['wccd_uploaded_file'] = $uploaded_file;
$cart_item_data['wccd_uploaded_name'] = WC()->session->get( 'wccd_uploaded_name' );
WC()->session->set( 'wccd_uploaded_file', null );
WC()->session->set( 'wccd_uploaded_name', null );
}
if ( $addon_price > 0 ) {
$cart_item_data['wccd_addon_price'] = $addon_price;
}
// Unique key to prevent merging with identical products
$cart_item_data['wccd_unique_key'] = md5( microtime() . rand() );
return $cart_item_data;
}The wccd_unique_key at the end is crucial. Without it, WooCommerce would merge two identical products with different customizations into the same cart line item, losing the customer’s personalization data.
Displaying Custom Data in Cart and Checkout
add_filter( 'woocommerce_get_item_data', 'wccd_display_cart_item_data', 10, 2 );
function wccd_display_cart_item_data( $item_data, $cart_item ) {
if ( ! empty( $cart_item['wccd_custom_text'] ) ) {
$item_data[] = array(
'key' => 'Custom Text',
'value' => esc_html( $cart_item['wccd_custom_text'] ),
);
}
if ( ! empty( $cart_item['wccd_dropdown_label'] ) ) {
$item_data[] = array(
'key' => 'Selected Option',
'value' => esc_html( $cart_item['wccd_dropdown_label'] ),
);
}
if ( ! empty( $cart_item['wccd_selected_addons'] ) ) {
$item_data[] = array(
'key' => 'Add-Ons',
'value' => esc_html( implode( ', ', $cart_item['wccd_selected_addons'] ) ),
);
}
if ( ! empty( $cart_item['wccd_engraving_text'] ) ) {
$item_data[] = array(
'key' => 'Engraving',
'value' => sprintf(
'%s (Font: %s)',
esc_html( $cart_item['wccd_engraving_text'] ),
esc_html( ucfirst( $cart_item['wccd_engraving_font'] ) )
),
);
}
if ( ! empty( $cart_item['wccd_uploaded_name'] ) ) {
$item_data[] = array(
'key' => 'Uploaded File',
'value' => esc_html( $cart_item['wccd_uploaded_name'] ),
);
}
return $item_data;
}Saving Data to Orders
The final persistence step saves cart item data to the order so it appears in admin order details, emails, and API responses:
add_action( 'woocommerce_checkout_create_order_line_item', 'wccd_save_order_item_meta', 10, 4 );
function wccd_save_order_item_meta( $item, $cart_item_key, $values, $order ) {
$meta_keys = array(
'wccd_custom_text' => 'Custom Text',
'wccd_dropdown_label' => 'Selected Option',
'wccd_engraving_text' => 'Engraving Text',
'wccd_engraving_font' => 'Engraving Font',
'wccd_uploaded_name' => 'Uploaded File',
'wccd_uploaded_file' => '_uploaded_file_path',
);
foreach ( $meta_keys as $cart_key => $meta_label ) {
if ( ! empty( $values[ $cart_key ] ) ) {
if ( str_starts_with( $meta_label, '_' ) ) {
// Hidden meta (not shown to customer)
$item->add_meta_data( $meta_label, $values[ $cart_key ], true );
} else {
$item->add_meta_data( $meta_label, sanitize_text_field( $values[ $cart_key ] ), true );
}
}
}
if ( ! empty( $values['wccd_selected_addons'] ) ) {
$item->add_meta_data( 'Add-Ons', implode( ', ', array_map( 'sanitize_text_field', $values['wccd_selected_addons'] ) ), true );
}
if ( ! empty( $values['wccd_addon_price'] ) ) {
$item->add_meta_data( '_addon_price', floatval( $values['wccd_addon_price'] ), true );
}
}Notice the underscore prefix on _uploaded_file_path and _addon_price. Meta keys starting with an underscore are hidden from the customer-facing order details but visible in the admin. The file path should never be exposed to customers.
Building Custom Add-On Display Templates
The default rendering hooks produce functional but plain HTML. For polished product pages, you’ll want custom templates that match your theme’s design language. Here’s how to build a template system for your add-on fields:
// Template loader with theme override support
function wccd_get_template( $template_name, $args = array() ) {
// Allow themes to override templates
$theme_template = locate_template( 'wccd-templates/' . $template_name );
if ( $theme_template ) {
$template_path = $theme_template;
} else {
$template_path = WCCD_PLUGIN_DIR . 'templates/' . $template_name;
}
if ( ! file_exists( $template_path ) ) {
return;
}
extract( $args, EXTR_SKIP );
include $template_path;
}
// Render all fields using templates
add_action( 'woocommerce_before_add_to_cart_button', 'wccd_render_all_custom_fields', 15 );
function wccd_render_all_custom_fields() {
global $product;
$fields = $product->get_meta( '_wccd_custom_fields' );
if ( empty( $fields ) || ! is_array( $fields ) ) {
return;
}
echo '<div class="wccd-product-addons">';
foreach ( $fields as $field ) {
$template = 'field-' . $field['type'] . '.php';
wccd_get_template( $template, array(
'field' => $field,
'product' => $product,
) );
}
echo '</div>';
}
// CSS for the add-on fields
add_action( 'wp_enqueue_scripts', 'wccd_enqueue_styles' );
function wccd_enqueue_styles() {
if ( ! is_product() ) {
return;
}
wp_enqueue_style(
'wccd-product-addons',
WCCD_PLUGIN_URL . 'assets/css/product-addons.css',
array(),
WCCD_VERSION
);
}The locate_template call lets theme developers override any field template by placing files in a wccd-templates/ directory in their theme. This follows the same pattern WooCommerce itself uses for template overrides, your store owners will find it familiar.
Admin Interface: Managing Custom Fields Per Product
Store owners need a way to configure which custom fields appear on each product. Add a custom tab to the WooCommerce product data panel:
// Add custom tab
add_filter( 'woocommerce_product_data_tabs', 'wccd_add_product_data_tab' );
function wccd_add_product_data_tab( $tabs ) {
$tabs['wccd_addons'] = array(
'label' => 'Product Add-Ons',
'target' => 'wccd_addons_panel',
'class' => array(),
'priority' => 80,
);
return $tabs;
}
// Tab content
add_action( 'woocommerce_product_data_panels', 'wccd_product_data_panel' );
function wccd_product_data_panel() {
global $post;
echo '<div id="wccd_addons_panel" class="panel woocommerce_options_panel">';
woocommerce_wp_checkbox( array(
'id' => '_wccd_enable_custom_text',
'label' => 'Enable Text Field',
'description' => 'Allow customers to enter custom text',
) );
woocommerce_wp_text_input( array(
'id' => '_wccd_text_label',
'label' => 'Text Field Label',
'placeholder' => 'Custom Text',
) );
woocommerce_wp_text_input( array(
'id' => '_wccd_text_maxlength',
'label' => 'Max Characters',
'type' => 'number',
'custom_attributes' => array( 'min' => 1, 'max' => 500 ),
) );
woocommerce_wp_checkbox( array(
'id' => '_wccd_enable_file_upload',
'label' => 'Enable File Upload',
) );
woocommerce_wp_text_input( array(
'id' => '_wccd_allowed_types',
'label' => 'Allowed File Types',
'placeholder' => 'jpg,png,pdf',
) );
woocommerce_wp_checkbox( array(
'id' => '_wccd_enable_engraving',
'label' => 'Enable Engraving',
) );
woocommerce_wp_text_input( array(
'id' => '_wccd_engraving_price_per_char',
'label' => 'Price Per Character',
'type' => 'number',
'data_type' => 'price',
'placeholder' => '0.50',
) );
woocommerce_wp_textarea_input( array(
'id' => '_wccd_dropdown_options',
'label' => 'Dropdown Options',
'description' => 'One per line. Format: Label|price (e.g., Gold|10.00)',
'rows' => 5,
) );
echo '</div>';
}
// Save meta
add_action( 'woocommerce_process_product_meta', 'wccd_save_product_meta' );
function wccd_save_product_meta( $post_id ) {
$checkboxes = array( '_wccd_enable_custom_text', '_wccd_enable_file_upload', '_wccd_enable_engraving' );
foreach ( $checkboxes as $key ) {
update_post_meta( $post_id, $key, isset( $_POST[ $key ] ) ? 'yes' : 'no' );
}
$text_fields = array( '_wccd_text_label', '_wccd_text_maxlength', '_wccd_allowed_types',
'_wccd_engraving_price_per_char', '_wccd_dropdown_options', '_wccd_dropdown_label' );
foreach ( $text_fields as $key ) {
if ( isset( $_POST[ $key ] ) ) {
update_post_meta( $post_id, $key, sanitize_textarea_field( $_POST[ $key ] ) );
}
}
}Validation Best Practices
Input validation prevents invalid data from entering your system and gives customers clear feedback. Always validate server-side even when you have client-side validation:
add_filter( 'woocommerce_add_to_cart_validation', 'wccd_validate_all_fields', 10, 3 );
function wccd_validate_all_fields( $passed, $product_id, $quantity ) {
$product = wc_get_product( $product_id );
// Validate required text field
if ( 'yes' === $product->get_meta( '_wccd_text_required' ) ) {
if ( empty( $_POST['wccd_custom_text'] ) ) {
wc_add_notice(
sprintf( '%s is required.', $product->get_meta( '_wccd_text_label' ) ?: 'Custom Text' ),
'error'
);
return false;
}
}
// Validate text length
if ( ! empty( $_POST['wccd_custom_text'] ) ) {
$maxlength = intval( $product->get_meta( '_wccd_text_maxlength' ) ?: 50 );
if ( mb_strlen( $_POST['wccd_custom_text'] ) > $maxlength ) {
wc_add_notice(
sprintf( 'Text must be %d characters or fewer.', $maxlength ),
'error'
);
return false;
}
// Block HTML/script injection
if ( wp_strip_all_tags( $_POST['wccd_custom_text'] ) !== $_POST['wccd_custom_text'] ) {
wc_add_notice( 'HTML tags are not allowed in custom text.', 'error' );
return false;
}
}
// Validate engraving character limits
if ( ! empty( $_POST['wccd_engraving_text'] ) ) {
$max_chars = intval( $product->get_meta( '_wccd_engraving_max_chars' ) ?: 20 );
if ( mb_strlen( $_POST['wccd_engraving_text'] ) > $max_chars ) {
wc_add_notice(
sprintf( 'Engraving text must be %d characters or fewer.', $max_chars ),
'error'
);
return false;
}
}
return $passed;
}Performance Considerations
Product add-ons can impact performance if not implemented carefully. Here are the key optimizations:
Lazy-load JavaScript: Only enqueue add-on scripts on product pages that actually have custom fields enabled. Check for the meta flag before enqueueing:
add_action( 'wp_enqueue_scripts', 'wccd_conditional_enqueue' );
function wccd_conditional_enqueue() {
if ( ! is_product() ) {
return;
}
global $product;
if ( ! $product ) {
$product = wc_get_product( get_the_ID() );
}
$has_addons = $product->get_meta( '_wccd_enable_custom_text' ) === 'yes'
|| $product->get_meta( '_wccd_enable_file_upload' ) === 'yes'
|| $product->get_meta( '_wccd_enable_engraving' ) === 'yes'
|| ! empty( $product->get_meta( '_wccd_dropdown_options' ) );
if ( $has_addons ) {
wp_enqueue_script( 'wccd-product-addons', WCCD_PLUGIN_URL . 'assets/js/product-addons.js', array( 'jquery' ), WCCD_VERSION, true );
wp_enqueue_style( 'wccd-product-addons', WCCD_PLUGIN_URL . 'assets/css/product-addons.css', array(), WCCD_VERSION );
}
}Cache product meta: If you have many meta queries per product, batch-load all custom field settings in a single query using get_post_meta( $product_id ) without a key to get all meta at once. WooCommerce caches this internally, but be aware of it when debugging.
Minimize cart recalculations: The woocommerce_before_calculate_totals hook fires frequently. Keep your pricing callback lightweight, avoid database queries inside the cart loop. All pricing data should already be stored in the cart item data array.
Testing Your Product Add-Ons
Custom product fields need thorough testing across multiple scenarios:
- Add to cart with all fields filled, verify data appears in cart
- Add to cart with optional fields empty, verify no errors
- Add same product twice with different customizations, verify separate cart lines
- Complete checkout, verify all data saved to order
- Check order emails, verify custom data appears in confirmation emails
- Test REST API, verify custom data appears in order API responses
- File upload edge cases, wrong file type, oversized files, no file when required
- Price calculations, verify total matches expected price with all add-ons
- Cart item removal and quantity changes, verify add-on pricing adjusts correctly
- Conditional field visibility, verify hidden fields don’t submit data
Use WooCommerce’s built-in logging (wc_get_logger()) during development to trace data through the purchase flow. Log at each hook point to verify your data reaches each stage. For more on WooCommerce customization approaches, see our guide on when and how to build your own custom product types.
Wrapping Up
Building WooCommerce product add-ons from scratch gives you complete control over the customer experience and keeps your store free from heavy third-party plugin dependencies. The hook chain, from woocommerce_before_add_to_cart_button through woocommerce_checkout_create_order_line_item, is your framework for any type of product customization.
Start with the simplest field type your products need, get the full cart-to-order data flow working, then layer on conditional logic, pricing adjustments, and advanced field types. Each piece builds on the same foundation. The code examples in this guide are production-ready starting points, adapt the sanitization, validation, and template patterns to match your store’s specific requirements.
For stores with complex product configurations, consider extracting this functionality into a standalone plugin with its own settings page, REST API endpoints for headless storefronts, and import/export tools for field configurations. The architecture patterns shown here scale cleanly to enterprise-level implementations.
