@shopify/address

Address utilities for formatting addresses.

Installation

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);
/* =>
  日本
  〒100-8994東京都目黒区八重洲1-5-3
  Shopify
  田中恵子様
 */

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

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.

Eg.:

[
  ['firstName', 'lastName'],
  ['company'],
  ['address1'],
  ['address2'],
  ['city'],
  ['country', 'province', 'zip'],
  ['phone'],
];

Testing

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.
  mockCountryRequests();
});
afterEach(fetch.restore);

Note: Only FR / JA and EN are mocked.