City Checkout Field for WooCommerce

Overview

↑ Back to top

City Checkout Field enhances your WooCommerce store by replacing the standard city input with a searchable dropdown, making it easier for customers to select their city during checkout. The plugin comes preloaded with the most popular cities for every country, and supports both classic and block-based checkout flows.

---

Requirements

↑ Back to top

• WordPress 6.0 or higher
• WooCommerce 9.0 or higher
• PHP 7.4 or higher

---

---

Usage

↑ Back to top

Plugin Settings Overview

↑ Back to top

• Navigate to WooCommerce > Settings > Shipping > Cities.
• Use the React-powered admin interface to:
  • Enable or disable the city dropdown for each country (and state, if applicable).
  • Add, remove, or edit cities for each country/state.
  • Changes are saved in the WordPress options table and take effect immediately.

Legacy / Shortcode Checkout

↑ Back to top

• The plugin automatically replaces the city text input with a searchable dropdown on the classic WooCommerce checkout page.
• If no cities are available for the selected country/state, the field falls back to a standard text input.
• The city dropdown is also available in user profile address forms.

Block Checkout

↑ Back to top

• Fully compatible with WooCommerce Blocks checkout.
• The plugin injects a city dropdown into the block-based checkout form using a dynamic JavaScript integration.
• If no cities are available for the selected country/state, the field falls back to a standard text input.
• No additional configuration is required; the plugin auto-detects the checkout type.

---

Scenarios

↑ Back to top

1. Store in a Country with Many Cities

↑ Back to top

Use Case:

A WooCommerce store based in Brazil wants to simplify the checkout process for customers by providing a dropdown of the most popular cities, reducing errors and typos in address entry.

How the Plugin Helps:

With City Checkout Field, the store owner enables the city dropdown for Brazil. At checkout, customers select their city from a searchable list, ensuring accurate shipping information and reducing failed deliveries due to misspelled city names.

—

2. Restricting Shipping to Specific Cities

↑ Back to top

Use Case:

A retailer only ships to certain cities within the state of California, USA. They want to prevent orders from unsupported locations.

How the Plugin Helps:

The admin customizes the city list for United States > California in the plugin settings, removing all cities except those they serve. At checkout, customers can only select from the allowed cities, ensuring the store only receives orders from deliverable locations.

—

3. Multi-language Store with Localized City Names

↑ Back to top

Use Case:

An international store operates in multiple languages and wants the city dropdown to display city names in the customer’s language.

How the Plugin Helps:

Because the plugin is fully translatable, the store owner provides translations for city names and interface text. Customers see the city dropdown in their preferred language, improving the user experience and reducing confusion.

—

4. Country/State without Predefined Cities

↑ Back to top

Use Case:

A store receives orders from a country or state not included in the plugin’s city database.

How the Plugin Helps:

For these locations, the city field automatically falls back to a standard text input, allowing customers to enter their city manually without any disruption to the checkout flow.

---

FAQs

↑ Back to top

Q: Does this plugin support WooCommerce Blocks (block-based checkout)?

A: Yes, City Checkout Field works with both classic and block-based checkout. It automatically detects and loads the correct scripts.

Q: Can I customize the list of cities?

A: Yes, you can add, remove, or edit cities for each country (and state, if applicable) using the React-powered admin interface.

Q: What happens if a country or state is missing from the city list?

A: The city field will fall back to a standard text input if no cities are available for the selected country/state.

Q: Is the plugin translatable?

A: Yes, all strings are translation-ready and a .pot file is provided.

Q: Where is the city data stored?

A: City data is loaded from PHP files in the plugin’s cities/ directory by default, but can be customized and saved in the WordPress options table via the admin UI.

Q: Can I define WooCommerce shipping zones based on city names with this plugin?

A: No, not currently. WooCommerce shipping zones are still defined by country, state, and postcode. The City Checkout Field plugin does not add the ability to create or assign shipping zones based on city names. If this feature is important to your workflow, please let us know – your feedback helps shape future development.

---

Advanced

↑ Back to top

Available Filters

↑ Back to top

Developers can customize city data, field rendering, and more using the following filters:

1. wc_city_select_cities

Filter the list of cities for a given country/state.

add_filter( 'wc_city_select_cities', function( $cities ) {
    // Example: Add a custom city to South Africa (ZA)
    if ( isset( $cities['CA'] ) && is_array( $cities['CA'] ) ) {
        $cities['US']['CA'][] = 'Silicon Valley';
    }
    return $cities;
} );

2. WooCommerce Field Filters

The plugin also hooks into standard WooCommerce field filters, which you can use to further customize the checkout fields:

• woocommerce_billing_fields
• woocommerce_shipping_fields
• woocommerce_form_field_city
• woocommerce_form_field
• woocommerce_localisation_address_formats
• woocommerce_checkout_get_value
• woocommerce_get_country_locale
• woocommerce_register_additional_checkout_field

Example: Customize the city field label

add_filter( 'woocommerce_billing_fields', function( $fields ) {
    if ( isset( $fields['billing_city'] ) ) {
        $fields['billing_city']['label'] = 'Town/City';
    }
    return $fields;
} );

Example Code Snippets

↑ Back to top

Add a new city to a country/state:

add_filter( 'wc_city_select_cities', function( $cities ) {
    $cities['US']['CA'][] = 'Silicon Valley';
    return $cities;
} );

Disable the city dropdown for a specific country:

add_filter( 'wc_city_select_cities', function( $cities ) {
    unset( $cities['GB'] ); // Remove United Kingdom
    return $cities;
} );