Add a custom field to WooCommerce Billing form?

Add a custom field to WooCommerce Billing form?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Adding Custom Billing Fields in WooCommerce: Why Labels and Placeholders Disappear

When attempting to inject a custom field into the WooCommerce billing form using woocommerce_billing_fields, it is common to encounter a situation where the input element renders correctly, but its associated label, placeholder text, and CSS classes are missing. The code snippet below demonstrates the standard approach for adding a field named "NIF" (Número de Identificación Fiscal) to the form.

add_filter('woocommerce_billing_fields', 'custom_woocommerce_billing_fields');

function custom_woocommerce_billing_fields($fields) {
    $fields['billing']['billing_options'] = array(
        'label' => __('NIF', 'woocommerce'), 
        'placeholder' => _x('Your NIF here....', 'placeholder', 'woocommerce'), 
        'required' => false, 
        'clear' => false, 
        'type' => 'text', 
        'class' => array('my-css')    
    );

    return $fields;
}

Despite the presence of these keys in the returned array, the frontend output often omits them. The root cause lies in how WooCommerce structures its billing form data and how the woocommerce_form_field function processes that data. Specifically, the label and placeholder are not rendered by default for certain field types or positions within the billing section unless specific conditions are met.

The primary issue is that WooCommerce does not automatically append a <label> tag to every custom field added via this filter. The rendering logic checks for a specific label key, but it often expects the label to be associated with an existing form field structure rather than being inserted as a standalone element alongside the input. Furthermore, placeholders are generally only rendered if the field is wrapped in a woocommerce_form_field context that explicitly supports them, which can vary based on the theme's template overrides or the specific version of WooCommerce being used.

To resolve this, you must understand that simply returning an array with these keys does not guarantee their visual rendering if the underlying template expects a different data structure. The most robust solution involves ensuring the field is treated as a standard form element within the billing context. However, if you strictly require the label to appear above or next to the input without modifying the core template files, you might need to adjust how the field is registered.

A more reliable method often involves using woocommerce_form_field directly or ensuring your custom field inherits the necessary properties from existing billing fields. If you add a new key like 'billing_options', WooCommerce treats it as a distinct entity. If the theme's templates/billing-fields.php does not have specific logic to handle this new key, the default rendering might skip optional attributes like placeholders.

You can verify your current version of WooCommerce, as behavior regarding custom fields has evolved over time. In older versions, adding a label required explicit wrapping in the template file. In newer versions, the filter approach works better but still relies on the woocommerce_form_field function to handle the output correctly. If you are using a child theme, ensure that no parent theme template is overriding the billing fields view with a version that ignores custom labels for external keys.

If the standard array modification fails to display the label, consider registering the field as a standard HTML input within your theme's functions.php and then enqueueing a script to handle its output, or use a dedicated plugin that handles form field injection more explicitly. This ensures compatibility across different themes and WooCommerce updates without relying on undocumented rendering behaviors.

For developers managing complex checkout flows, understanding the distinction between modifying the $fields array versus directly hooking into woocommerce_form_fields is crucial. The former is intended for dynamic data collection, while the latter often provides better integration with the existing form structure, including label and placeholder support out of the box. Always test changes in a staging environment to ensure that the custom field does not break validation logic or conflict with other plugins like LaravelCompany, if you are integrating with their specific commerce solutions.

Our network