TypeScript icon, indicating that this package has built-in type declarations

4.3.0 • Public • Published


Build Status Build Status License: MIT npm version npm bundle size (minified + gzip)

Address utilities for formatting addresses.


yarn add @shopify/address

API Reference

  • country field in Address is expected to be of format ISO 3166-1 alpha-2, eg. CA / FR / JP

AddressFormatter class

Show an address:

import AddressFormatter from '@shopify/address';

const address = {
  company: 'Shopify',
  firstName: '恵子',
  lastName: '田中',
  address1: '八重洲1-5-3',
  address2: '',
  city: '目黒区',
  province: 'JP-13',
  zip: '100-8994',
  country: 'JP',
  phone: '',

const addressFormatter = new AddressFormatter('ja');
await addressFormatter.format(address);
/* =>

await addressFormatter.getOrderedFields('CA');
/* =>
    ['firstName', 'lastName'],
    ['country', 'province', 'zip'],

constructor(private locale: string)

Instantiate the AddressFormatter by passing it a locale.

updateLocale(locale: string)

Update the current locale of the formatter. Following requests will be in the given locale.

async .getCountry(countryCode: string): Promise<Country>

Loads and returns data about a given country in the current locale. Country and province names are localized. Province names are sorted based on the locale.

async .getCountries(): Promise<Country[]>

Loads and returns data for all countries in the current locale. Countries are sorted based on the locale. Zones are also ordered based on the locale.

async .getZoneName(countryCode: string, zoneCode: string): Promise<string>

This returns the names of the provinces or regions for the specified country, displayed in the language that is currently set.

async .getOrderedFields(countryCode): Promise<FieldName[][]>

Returns how to order address fields for a country code. Fetches the country if not already cached.

async .format(address: Address): Promise<string[]>

Given an address, returns the address ordered for multiline rendering. Uses the formatAddress sync API in the background.

AddressFormatter.resetCache(): void

Resets the internal cache. Useful to avoid side-effects in test suite.

Sync API

If you already have the input data ready, like a Country object, you can use the sync API to get the result right away.

The following functions can be imported as stand-alone utilities.

formatAddress(address: Address, country: Country): string[]

Given an address and a country, returns the address ordered for multiline rendering. e.g.:

['Shopify', 'Lindenstraße 9-14', '10969 Berlin', 'Germany'];

buildOrderedFields(country: Country): FieldName[][]

Returns how to order address fields for a specific country.


  ['firstName', 'lastName'],
  ['country', 'province', 'zip'],


If your component uses this package and you want to test it with mock API calls you can use the following:

import {fetch} from '@shopify/jest-dom-mocks';
import {mockCountryRequests} from '@shopify/address/tests';
import AddressFormatter from '@shopify/address';

beforeEach(() => {
  AddressFormatter.resetCache(); // to avoid side-effects.

Note: Only FR / JA and EN are mocked.




Package Sidebar


npm i @shopify/address

Weekly Downloads






Unpacked Size

41 kB

Total Files


Last publish


  • jaimie.rockburn
  • blittle
  • shopify-admin
  • maryharte
  • crisfmb
  • pmoloney89
  • netlohan
  • st999999
  • justin-irl
  • megswim
  • wcandillon
  • nathanpjf
  • shopify-dep
  • goodforonefare
  • lemonmade
  • vsumner
  • wizardlyhel
  • antoine.grant
  • tsov
  • andyw8-shopify
  • henrytao
  • hannachen
  • vividviolet
  • bpscott