🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms International Address Formats Setup Guide

Updated 11 min read Gravity Forms Fields & Inputs
On this page
  1. Video walkthrough
  2. What you need
  3. Install and activate
  4. Turn on the country format
  5. Countries visitors can choose
  6. Show the country first
  7. Pre-select the country from the visitor’s browser language
  8. Use each country’s own labels
  9. Show an example postcode in the box
  10. Use the country format in merge tags and on the entry screen
  11. Keep the standard layout for these countries
  12. What the visitor sees
  13. How each submission is checked
  14. Merge tags
  15. Entries, the entry screen and the export
  16. Add or change countries
  17. Privacy and performance
  18. Uninstall
  19. Questions
  20. Do my existing entries change?
  21. Does it check that the address really exists?
  22. What does the visitor see after a failed submission?
  23. How is this different from the German Address Format add-on?
  24. What happens if the license expires?

Video walkthrough

Gravity Forms International Address Formats Setup Guide: Country Address Order, Labels & Postcodes
Video setup guide: Gravity Forms International Address Formats Watch on YouTube

The Gravity Forms International Address Formats add-on gives the Gravity Forms Address field a country format. When the visitor picks a country, the address parts move into that country’s postal order, the labels change to the words people in that country use, the parts the country needs become required, the region becomes a list where the country has one, and the postcode is tidied and checked. Built-in formats cover 65 countries. This guide covers installation, every setting, what the visitor sees, how the server checks each submission, merge tags, the entry screen, the export and adding your own countries.

A delivery address form with Japan chosen as the country: the postal code box comes first with 100-0005, then a Prefecture list showing 東京都 (Tokyo), the city 千代田区 and the street 丸の内1-1-1, all in the Japanese postal order
Japan chosen: postal code first, then prefecture, city and street, the way a Japanese address is written.

What you need

  • WordPress 6.5 or newer and PHP 7.4 or newer.
  • Gravity Forms 2.9 or newer (tested with 2.9 and 3.1).
  • A GravityExtra license key for this add-on.

Nothing else is needed: no address service, no API key and no extra library. The country formats ship with the add-on and every check runs on your own server.

Install and activate

  1. In WordPress go to Plugins → Add New → Upload Plugin, choose the add-on zip file and click Install Now, then Activate.
  2. Go to Forms → Settings → International Address, paste your license key and click Activate License.
  3. Open a form in the form editor and click an Address field (or add one from Advanced Fields).

Turn on the country format

The country format works with the International address type, the one that shows a country list. In the Address field settings, set Address Type to International, then tick Country format: order, labels, required parts and postcode check follow the country. If the field uses the United States or Canada type, a short note asks you to switch to International first; those types have a fixed country, so there is nothing to switch between.

The Address field settings: the Country format tick box, the list of countries visitors can choose with tick boxes, and the options to show the country first, pre-select it from the browser language, use country labels, show an example postcode, use the country format in merge tags and keep the standard layout for chosen countries
The country format settings of an Address field.

Countries visitors can choose

Tick the countries you ship to, sell to or work with. The country list on the form then shows only those countries, and the server refuses any other country, even if someone edits the page. Leave every box empty to keep the full country list; countries without a built-in format then keep the standard layout. Tick all and Clear help with long lists.

Show the country first

On by default. Because the rest of the address depends on the country, asking for it first means visitors fill in the right boxes from the start. Untick it to keep the country at the end.

Pre-select the country from the visitor’s browser language

Off by default. When on, a browser set to English (United Kingdom) starts with United Kingdom selected, a browser set to German (Austria) starts with Austria, and so on, as long as that country is on the field’s list. It only sets the starting value; visitors can change it, and a submitted value is never overwritten. The field’s own default country, if you set one, is used when the browser gives no country.

Use each country’s own labels

On by default. The postcode box is called ZIP code in the United States, Postcode in the United Kingdom and Australia, Postal code in Canada, PIN code in India, Eircode in Ireland, CAP in Italy and CEP in Brazil. The region becomes State, Province, County, Prefecture, Emirate or Region, and the city becomes Town / City or Suburb where that is the custom. A sub-label you typed yourself in the field settings is always kept. All labels can be translated like any other text of the add-on.

Show an example postcode in the box

On by default. An empty postcode box shows an example in the country’s format, such as “e.g. SW1A 1AA” or “e.g. 100-0005”. A placeholder you set yourself is kept.

Use the country format in merge tags and on the entry screen

On by default. The whole-field merge tag {Address:3}, the {all_fields} merge tag and the entry screen then show the address in the country’s postal order. Untick it to keep the standard output there; the dedicated merge tags described below work either way.

Keep the standard layout for these countries

Two-letter country codes separated by commas, for example US, CA. For these countries the field keeps the standard order and labels and the add-on does not check the postcode. Use it when another plugin already handles a country, or when your team prefers the usual layout for your home country.

What the visitor sees

When the visitor picks a country, the field changes at once, without reloading the page:

  • Order. The boxes move into the postal order of that country. Germany, France, Austria, Switzerland, the Netherlands, the Nordic countries and most of Europe put the postcode before the town. The United States, Canada and Australia put the city, then the state, then the code. Japan and China start with the postal code and region and end with the street. Hungary starts with the town.
  • Parts the country does not use are hidden. Singapore and Hong Kong have no separate city line; the United Arab Emirates and Qatar use no postcode; the United Kingdom does not need a county.
  • Required and optional parts. When the field is required, the parts the country needs are required and the others are marked “(optional)”. In Ireland the Eircode and county are optional; in the United States the state and ZIP code are required.
  • Region lists. The region box becomes a list for the United States, Canada, Australia, Brazil, Mexico, Argentina, Chile, Italy, Spain, Ireland, India, Japan, China, Malaysia, Hong Kong and the United Arab Emirates. Other countries keep a text box.
  • Postcode help. When the visitor leaves the postcode box, the add-on tidies it: upper case, the right space or hyphen. “sw1a1aa” becomes “SW1A 1AA”, “k1a0b1” becomes “K1A 0B1”, “1000005” becomes “100-0005” and “950141234” becomes “95014-1234”. If it still does not match the country, a short message under the box says so and gives an example, for instance “Please enter a valid ZIP code for United States, for example 95014.”
The same form on a 390 pixel wide phone screen with United States chosen: country, street, city, a State list showing New York and the ZIP code 10118 stacked in one column with no sideways scrolling
On a phone every part takes the full width, so nothing scrolls sideways.

On phones the parts stack in one column. Text boxes follow the direction of what is typed, so Arabic and Hebrew addresses read right to left inside a left-to-right form, and Japanese, Chinese and Korean addresses are kept exactly as typed. Number-only postcode boxes open the number keypad on phones.

How each submission is checked

The browser helps the visitor, but the server decides. Before Gravity Forms saves anything, the add-on repeats every step with the values that were actually posted:

  1. It works out the country from the posted value and refuses a country that is not on the field’s list (“Please choose a country from the list.”).
  2. It empties parts the country does not use, so a city typed into a hidden box for Singapore is not stored.
  3. It brings the postcode into the country’s format, so a postcode typed in lower case or without a space is stored correctly even if the visitor’s browser ran no script.
  4. It matches the region to the country’s list by name, label or abbreviation (“ca” and “California” both store “California”) and refuses a region that is not in the list.
  5. When the field is required, it checks the parts that country requires and names the missing ones, for example “Please complete: State, ZIP code.”
  6. It checks the postcode against the country’s pattern.

These checks replace the standard required check for the field, so a required address in Singapore no longer asks for a city, and one in the United Arab Emirates no longer asks for a postcode. A part you hid in the field settings is never required. For a country without a built-in format, or one on the “keep the standard layout” list, Gravity Forms’ own check applies unchanged. When the field is not required and left empty, nothing is checked; when it is partly filled, the postcode and region checks still apply.

Merge tags

The usual sub-input merge tags, such as {Address (City):3.3}, keep working exactly as before. The add-on adds four modifiers for the whole field (replace 3 with your field ID):

  • {Address:3:formatted} – the address in the country’s postal order, one part per line, with the country as the last line. In HTML emails the lines are separated by line breaks. Ready for a shipping label.
  • {Address:3:nocountry} – the same without the country line, for domestic labels.
  • {Address:3:oneline} – the formatted address on one line, parts separated by commas, for text messages, spreadsheets and feeds.
  • {Address:3:country_code} – the two-letter country code, such as JP, for routing rules and shipping integrations.

For a United States address the formatted tag gives “1 Infinite Loop / Building 4 / Cupertino, CA 95014-1234 / United States”; for Japan it gives “〒100-0005 / 東京都千代田区 / 丸の内1-1-1 / Japan”; for Germany “Unter den Linden 77 / 10117 Berlin / Germany”. US states, Canadian provinces, Australian states, Brazilian states, Mexican states and Italian provinces are shortened to their postal abbreviations in the formatted address, as the postal services ask. The tags are listed in the merge tag menu of notifications and confirmations.

Entries, the entry screen and the export

Each entry stores the standard address inputs (street, address line 2, city, region, postcode, country), already tidied by the server, so existing entries, exports, feeds to other add-ons and reports keep working. With the country format shown on the entry screen, the address appears in the postal order of its country.

The entry screen showing the delivery address formatted in the Japanese postal order: 〒100-0005, 東京都千代田区, 丸の内1-1-1, Japan
The entry screen shows the address in the postal order of its country.

Two extra columns are stored with each entry: Address (formatted), the one-line formatted address, and Address (country code). Both can be shown in the entry list, used in entry filters and chosen in Forms → Import/Export → Export Entries, next to the usual address columns. When you edit an entry on the entry screen, both columns are updated.

Add or change countries

The 65 built-in countries cover the Americas, Europe, the Middle East, Africa and Asia-Pacific. To add a country or change one, go to Forms → Settings → International Address and enter JSON in Extra or changed countries. Each country is a two-letter code with these keys:

  • fmt – the postal order, using %A for the street lines, %C for the city, %S for the region, %Z for the postcode and %n for a new line. Other text is kept, such as the 〒 mark in Japan. %A is required.
  • req – the letters of the required parts, for example ACZ.
  • zip – the postcode pattern (a regular expression) and ex, an example that matches it.
  • fix – an optional pattern and replacement that add the space or hyphen, for example ^(\d{3})(\d{4})$ and $1-$2.
  • labels – the label words for zip, state and city, such as postcode, province or town.
  • regions – an optional list for the region box; each item is the stored value, the label shown and the abbreviation used in the formatted address.

A country you enter replaces the built-in one with the same code. The settings page refuses JSON that cannot be read or a pattern that does not work, and tells you which country to fix. Developers can also change the data in code with the gfintladdress_formats filter, which receives every country and returns the list to use.

Privacy and performance

The add-on does not call any address service, map service or postcode service. The formats are a small file bundled with the add-on, the browser script only loads on forms that use the country format, and the add-on only contacts GravityExtra for its licence and updates. No visitor data leaves your site.

Uninstall

Deleting the add-on removes its settings. The addresses stay on the entries, and the formatted address and country code columns stay with the entries they describe.

Questions

Do my existing entries change?

No. Existing entries keep their values. The formatted output on the entry screen and in merge tags uses the country of each entry, so older entries are shown in their country’s order too.

Does it check that the address really exists?

No. It checks that the postcode has the right format for the country and that the region is a real region of that country. It does not look up streets or delivery points, because that needs an outside address service.

What does the visitor see after a failed submission?

The form comes back with the values typed, the country still selected and the field already in that country’s layout, with a message that names the problem, for example “Please complete: Postcode.”

How is this different from the German Address Format add-on?

The GravityExtra German Address Format add-on is made for Germany, Austria and Switzerland only: a separate house number, PLZ before Ort, German labels and an optional PLZ to town lookup. International Address Formats covers 65 countries in one field and switches the layout as the visitor changes country, but it has no house number box and no postcode lookup. Use the German add-on for German-speaking audiences and this one for international forms.

What happens if the license expires?

The Address field goes back to the standard layout and checks, the extra merge tag modifiers return nothing and the extra columns are hidden. Stored addresses are not touched. Renew the license to turn the country format back on.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr