Custom Checkout Fields

Overview

WooNooW fully integrates with the standard woocommerce_checkout_fields filter. This means any plugin that modifies or adds fields to WooCommerce checkout will generally work seamlessly with the WooNooW SPA checkout and address book features.

However, WooNooW introduces several powerful SPA-specific enhancements that you can take advantage of when writing integrations or custom plugins (such as RajaOngkir).

Supported Field Properties

When defining a custom field via woocommerce_checkout_fields, WooNooW respects the standard WooCommerce properties (like type, label, required, default, etc.), plus it adds a few specialized ones for modern React components.

form-row-wide Class Support

The SPA natively converts WooCommerce field classes to Tailwind grid classes:

• Adding 'form-row-wide' to the class array of a field will automatically apply md:col-span-2, forcing the field to take up 100% width on the checkout and address editing forms.
• If 'form-row-wide' is omitted, the field typically spans 50% width on tablet and desktop screens (md:col-span-1).

Hidden Fields

If you want to hide a standard field (e.g., billing_last_name or shipping_country), you can do so in two ways that WooNooW understands:

1. Change the field's type: $fields['billing']['billing_last_name']['type'] = 'hidden';
2. Add a hidden class: $fields['billing']['billing_last_name']['class'][] = 'hidden';

Tip: If you hide last_name, you might want to make first_name take up the full row. You can easily do this by adding 'form-row-wide' to the first_name class array!

searchable_select Field Type (New in WooNooW)

WooNooW introduces a new searchable_select type which renders an accessible, auto-complete dropdown component with API search capabilities. This is perfect for deeply nested address data like subdistricts or provinces.

Example:

$fields['billing']['billing_destination_id'] = [
    'type'            => 'searchable_select',
    'label'           => __('Destination', 'woonoow'),
    'required'        => true,
    'search_endpoint' => '/rajaongkir/destinations',
    'search_param'    => 'search',
    'min_chars'       => 3,
    'placeholder'     => 'Type to search destination...',
];

• search_endpoint: The WooNooW API endpoint to call (e.g., GET /wp-json/woonoow/v1/rajaongkir/destinations?search=query).
• search_param: The query parameter name (default: 'search').
• min_chars: The minimum characters a user must type before firing the API request.

The endpoint must return an array of objects with value and label:

[
  { "value": "123", "label": "Jakarta Selatan, DKI Jakarta" },
  { "value": "124", "label": "Jakarta Pusat, DKI Jakarta" }
]

Custom Address Formatting

If you introduce custom fields (like a RajaOngkir destination ID), you will likely want to format how the address is displayed on the "My Account" address cards and the "Checkout" saved address selector.

WooNooW provides the woonoow_format_address filter for this exact purpose.

Example:

add_filter('woonoow_format_address', function($formatted, $address) {
    $parts = [];
    $parts[] = $address['first_name'] . ' ' . $address['last_name'];
    $parts[] = $address['address_1'];
    
    // Append custom label saved by a searchable_select component
    if (!empty($address['destination_id_label'])) {
        $parts[] = $address['destination_id_label'];
    }
    
    // The SPA uses whitespace-pre-wrap, so newlines render correctly
    return implode("\n", array_filter($parts));
}, 10, 2);

When formatted_address is provided, the SPA will automatically bypass its default layout and display your perfectly formatted, newline-separated string.