---
title: Custom Checkout Fields
description: How to extend WooNooW checkout with custom fields and address formatting
date: 2024-06-03
---

## 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:**
```php
$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`:
```json
[
  { "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:**
```php
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.
