How to Add a Customizable Field to a WooCommerce Product

UPDATED 9/29/2019: Noticed some code typos and updated some of the display sections for compatibility with WooCommmerce 3.7.

In this WooCommerce tutorial I will be showing you how to add a custom field to the front-end of a WooCommerce product. We’ll be adding a text input that a customer could use to enter some special instructions or a custom inscription, etc. In theory, you could expand this to do all kinds of customizations (like allow the customer to upload an image), but this is a tutorial so let’s keep it kind of simple. Or in lieu of banging your head against a wall you could just buy WooCommerce Product Add-ons (This is an affiliate link).

We’ll start with adding the input to the single product page template then add the custom text to the cart, order, and even the checkout emails!

Please note that all code could go in your theme’s functions.php but really, this is functionality, so please put it in a plugin! This is going to be pretty code-heavy, so if you need a refresher on actions and filters and the like then you might want to review the basics before diving in to this.

First step is to add the text input to the front end

You can technically add this input anywhere, but since it is a core WooCommerce hook, woocommerce_before_add_to_cart_button is about 99% likely to work with any theme. Nothing too special going on here. We’re just adding a text input. Pay attention the input’s name. We’re going to be using that a lot.

/**
 * Display input on single product page
 */
function kia_custom_option(){
    $value = isset( $_POST['_custom_option' ] ) ? sanitize_text_field( $_POST['_custom_option'] ) : '';
    printf( '<p><label>%s<input name="_custom_option" value="%s" /></label></p>', __( 'Enter your custom text', 'kia-plugin-textdomain' ), esc_attr( $value ) );
}
add_action( 'woocommerce_before_add_to_cart_button', 'kia_custom_option', 9 );Code language: PHP (php)

Validate and sanitize the input data

If your field is optional, then you can delete this function completely. Or you could modify it to validate however, you’d like. For simplicity’s sake I’ve triggered an error if the customer tries to add the item to the cart without filling in any custom text.

/**
 * Validate when adding to cart
 * 
 * @param bool $passed
 * @param int $product_id
 * @param int $quantity
 * @return bool
 */
function kia_add_to_cart_validation( $passed, $product_id, $qty ){

    if( isset( $_POST['_custom_option'] ) && sanitize_text_field( $_POST['_custom_option'] ) === '' ){
        $product = wc_get_product( $product_id );
        wc_add_notice( sprintf( __( '%s cannot be added to the cart until you enter some custom text.', 'kia-plugin-textdomain' ), $product->get_title() ), 'error' );
        return false;
    }

    return $passed;

}
add_filter( 'woocommerce_add_to_cart_validation', 'kia_add_to_cart_validation', 10, 3 );Code language: PHP (php)

Add the custom data to the cart item

At first there’s a lot of mystery going on with the cart. Where the heck is that data coming from anyway? All the products are stored in an array in _$SESSION data. For the most part, Woo saves the product ID and the quantity and a handful of other things, but conveniently has a filter that will allow us to pass some of our own data to the cart item.

/**
 * Add custom data to the cart item
 * 
 * @param array $cart_item
 * @param int $product_id
 * @return array
 */
function kia_add_cart_item_data( $cart_item, $product_id ){

    if( isset( $_POST['_custom_option'] ) ) {
        $cart_item['custom_option'] = sanitize_text_field( $_POST[ '_custom_option' ] );
    }

    return $cart_item;

}
add_filter( 'woocommerce_add_cart_item_data', 'kia_add_cart_item_data', 10, 2 );
Code language: PHP (php)

Preserve the Cart Data

The cart is reloaded from the $_SESSION on every page load. This must be a security feature, but I am not actually 100% sure. I do know that the first time I started messing around I didn’t understand why the previous function was adding the info to the cart, but as soon as I loaded the cart it disappeared. That drove me crazy for a bit until someone pointed out the woocommerce_get_cart_item_from_session filter. Basically, we’ll just check if we already had the data in the $cart_item array, and if so, maintain it.

/**
 * Load cart data from session
 * 
 * @param array $cart_item
 * @param array $other_data
 * @return array
 */
function kia_get_cart_item_from_session( $cart_item, $values ) {

    if ( isset( $values['custom_option'] ) ){
        $cart_item['custom_option'] = $values['custom_option'];
    }

    return $cart_item;

}
add_filter( 'woocommerce_get_cart_item_from_session', 'kia_get_cart_item_from_session', 20, 2 );Code language: PHP (php)

Save the Custom Data On Checkout

WooCommerce has improved quite a bit in how it handles this data. Now we can call a simple woocommerce_add_order_item_meta() and it kind of acts like post meta, but for the item in this specific order. The data ends up in its own table.

/**
 * Add meta to order item
 * 
 * @param int $item_id
 * @param array $values
 * @return void
 */
function kia_add_order_item_meta( $item_id, $values ) {

    if ( ! empty( $values['custom_option'] ) ) {
        wc_add_order_item_meta( $item_id, 'custom_option', $values['custom_option'] );           
    }

}
add_action( 'woocommerce_add_order_item_meta', 'kia_add_order_item_meta', 10, 2 );Code language: PHP (php)

Updated for WooCommerce 3.0

/**
 * Add meta to order item
 * 
 * @param  WC_Order_Item  $order_item
 * @param  string         $cart_item_key
 * @param  array          $values The cart item values array.
 * @since 3.0.0
 */
function kia_add_order_item_meta( $order_item, $cart_item_key, $values ) {

    if ( ! empty( $values['custom_option'] ) ) {
    	$order_item->add_meta_data( 'custom_option', sanitize_text_field( $values[ 'custom_option' ] ), true );       
    }

}
add_action( 'woocommerce_checkout_create_order_line_item', 'kia_add_order_item_meta', 10, 3 );Code language: PHP (php)

Display all the Things!

Now that we actually have some usable data in the cart, it is time to display it to the customer. First, we’ll want to show it in the cart.

/**
 * Display entered value in cart
 * 
 * @param array $other_data
 * @param array $cart_item
 * @return array
 */
function kia_get_item_data( $other_data, $cart_item ) {

    if ( isset( $cart_item['custom_option'] ) ){

        $other_data[] = array(
            'key' => __( 'Your custom text', 'kia-plugin-textdomain' ),
            'display' => sanitize_text_field( $cart_item['custom_option'] )
        );

    }

    return $other_data;

}
add_filter( 'woocommerce_get_item_data', 'kia_get_item_data', 10, 2 );Code language: PHP (php)

Then we’ll want to show it in the order overview page, which should also be the same template shown in the My Account area and all emails too.

/**
 * Restore custom field to product meta when product retrieved for order item.
 * Meta fields will be automatically displayed if not prefixed with _
 * 
 * @param WC_Product $product 
 * @param WC_Order_Item_Product $order_item
 * @return array
 */
function kia_order_item_product( $product, $order_item ){

    if( $order_item->get_meta( 'custom_option' ) ){
        $product->add_meta_data( 'custom_option', $order_item->get_meta( 'custom_option' ), true );
    }

    return $product;

}
add_filter( 'woocommerce_order_item_product', 'kia_order_item_product', 10, 2 );Code language: PHP (php)

Update: Instead of having ‘order_item’ appear in the order table, we can customize the label with the following code:

/**
 * Customize the display of the meta key in order tables.
 * 
 * @param string $display_key
 * @param obj[] $meta
 * @param WC_Order_Item_Product $order_item
 * @return string
 */
function kia_order_item_display_meta_key( $display_key, $meta, $order_item ){

    if( $meta->key == 'custom_option' ){
        $display_key =  __( 'Your custom text', 'kia-plugin-textdomain' );
    }

    return $display_key;

}
add_filter( 'woocommerce_order_item_display_meta_key', 'kia_order_item_display_meta_key', 10, 3 );Code language: PHP (php)

Bonus, order again!

Should the customer want to order the exact same item with the exact same field we can do that too by adding the order item meta to the new cart item created when ordering again.

/**
 * Order Again
 * 
 * @param array $cart_item
 * @param WC_Order_Item_Product $order_item
 * @param WC_Order $order
 * @return array
 */
function kia_order_again_cart_item_data( $cart_item, $order_item, $order ){

    if( $order_item->get_meta( 'custom_option' ) ){
        $cart_item['custom_option'] = $order_item->get_meta( 'custom_option' );
    }

    return $cart_item;

}
add_filter( 'woocommerce_order_again_cart_item_data', 'kia_order_again_cart_item_data', 10, 3 );Code language: PHP (php)

And that’s it! You can download the entire thing here.

Plugin options

If you need more customization options and you don’t want to do it yourself there are several plugins you can try to build this without writing any code.

1. Advanced Product Fields for WooCommerce by Studio Wombat
2. Product Add-ons by Woo