Monday, 26-09-2022

woocommerce_form_field() user guide and 10 sample examples

woocommerce_form_field() is a function that outputs the payment/address form field in the Woocomerce plugin.


Function name: woocommerce_form_field
Plugin ref: WooCommerce
Source file: woocommerce/includes/wc-template-functions.php
Called by: woocommerce/templates/checkout/form-billing.php, woocommerce/templates/checkout/form-shipping.php, woocommerce/templates/myaccount/form-edit-address.php


$key: ( string ) required – Key.
$args: ( mixed ) required – Arguments.
$value: ( string ) optional – (default: null).

$args – Array of field parameters

$args parameters include the following:
type: woocommerce_form_field helps you to create fields of different types. Below is a list of the types of HTML fields it can generate. Surely I don’t need to explain more about these default HTML field types  like  <input type="number" /> anymore, do I?.

Here is the list that this function supports

  • text
  • select
  • radio
  • password
  • datetime
  • datetime-local
  • date
  • month
  • time
  • week
  • number
  • email
  • URL
  • tel
  • country – a dropdown list of countries supported by your store, which are set in WooCommerce settings > General tab. The interesting thing is that depending on the field $key parameter it will display a different list of countries. So, if you pass the value of the field equal to shipping_country it will display the countries you ship to (another WooCommerce setting).
  • state – a dropdown list of states.

country (string): Only for state field types. Name of a country which states you would like to display. If not passed, this field will try to get states of a billing or shipping country.

label (string): Field label.

description (string): Any custom text (HTML tags are supported too) will be displayed just under а field.

placeholder (string): You can use it to add a placeholder to any supported fields like text and textarea.

maxlength (int): Adds maxlength HTML attribute to the field. Defaults to false (no attribute added).

required (bool): Do you think it adds the required HTML attribute? Example: <input type="text" required="required" /> No, it doesn’t! All this parameter does is add an asterisk near the field label. If you want to add the required attribute to the input field then read Add an attribute to woocommerce_form_field below

Custom your checkout field with woocommerce_form_field

Customizing checkout fields using woocommerce_form_field

Customizing checkout fields using woocommerce_form_field

Some examples of how to use the woocommerce_form_field() function

Display a VAT number for the B2B field on the Checkout Page

Add this code snippet to functions.php in your theme. It will add a VAT number for the B2B field on Checkout Page.

And the result of the code:

Use woocommerce_form_field() to add vat field to check-out page

woocommerce_form_field() select options

This function Use woocommerce_form_field() to add a custom select options field to the check-out page

Add custom CSS class to WooCommerce checkout fields

I would like to share the way I used to add a custom CSS class to WooCommerce checkout fields. I’m using Twitter Bootstrap 4.7 and I would like to be able to use their .form-control class.  Here I will use the PHP foreach function to run through each form field then add the value to the class

Adding a hidden checkout field in WooCommerce

‘type’ => ‘hidden’ is not supported by woocommerce_form_field(). Therefore, we must use our own function to display and save the data of this hidden field when the customer submits the order.

The example below will save the IP address of the customer when submitting the order to the database along with the order data

Then you will need to save this hidden field in the order:

Add checkbox field to the checkout

The code below has the goal of adding a checkbox that says “Add me to your mailing list”. This functionality does work to provide a checkbox that is required to proceed.

If you want the Checkbox Checked by default, you can replace the functions below in the code above:

Add an attribute to woocommerce_form_field

If you actually want to add an attribute to woocommerce_form_field then you can add the woocommerce_form_field_checkbox filter hook.

You just need to add this hook after the code you added the custom field

As you can see, the example above will require the receive_email field to be required. However, in my opinion, the required parameter is a bit disappointing. You would always expect that WooCommerce developers to at least implement both, must validate required ” both in frontend and backend. However, currently, if you want to “required” a certain field, you need to build an accompanying function to validate it.

Set default value of woocommerce_form_field

To add a default value arg to the checkout form fields, simply add ‘default’ => $value, to the array in the function. Eg:

Woocommerce_form_field radio

Add radio buttons before the order total in the WooCommerce Order review section. I figured out how to add custom radio buttons to the order review section. Here is the code:

Woocommerce_form_field priority

To set priority for custom fields or reorder checkout fields, you must first create that field

You then rearrange the order of the fields this way:

The code above will move the position of the VAT field to the top right after the first name field

Woocommerce_form_field read-only

There are 2 ways to create a read-only field for Woocommerce Billing Fields or Woocommerce Shipping Fields
The first way is to use the Add an attribute to woocommerce_form_field as mentioned above to add the readonly=”readonly” attribute to it.

Method 2, use the code below:

Note that it does not apply to live websites because the example above will make the 3 fields first_name / last_name / email read-only and cannot enter data.

The article references some tutorials from WooCommerce Docs and Stack Overflow


About Author

Leave A Reply