@shopify/address

@shopify/address

Address utilities for loading and ordering 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

constructor(private locale: string)

Instantiate the AddressFormatter by passing it a locale.

updateLocale(locale: string)

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

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

Loads and return data about a given country in the locale used for instanciation. Country and province names are localized. Province names are ordered based on the locale

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

Loads and return data about a all countries in the given locale. Countries are ordered alphabetically based on the locale. Provinces are also ordered based on the locale.

async .getOrderedFields(countryCode): FieldName[][]

Returns how to order address fields.

Eg.:

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

async .format(address: Address): string[]

Given an address, returns the address ordered for multiline show. Eg.

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

async .getTranslationKey(countryCode: string, key: FieldName): string

Get the translation key for a given field for a given country. Eg:

await getTranslationKey('CA', 'province'); // => "province"
await getTranslationKey('US', 'province'); // => "state"
await getTranslationKey('JA', 'province'); // => "prefecture"
await getTranslationKey('CA', 'zip'); // => "postalCode"
await getTranslationKey('US', 'zip'); // => "zipCode"
await getTranslationKey('CA', 'address2'); // => "aptUnitNumber"
await getTranslationKey('JA', 'address2'); // => "aptSuiteEtc"

Translation keys

The label used to designate zip code and provinces are not the same from a country to another

• zoneKey is one of the following

  • county
  • emirate
  • governorate
  • prefecture
  • province
  • region
  • stateAndTerritory
  • state

• zipKey is one of the following

  • postalCode
  • postcode
  • pincode
  • zipCode

• address2Key is one of the following

  • aptSuiteEtc
  • aptUnitNumber

Example Usage

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']
  ]
 */