Address utilities for formatting addresses

Usage no npm install needed!

<script type="module">
  import shopifyAddress from 'https://cdn.skypack.dev/@shopify/address';



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

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 .getOrderedFields(countryCode): FieldName[][]

Returns how to order address fields.


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

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

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

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

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);
/* =>

await addressFormatter.getOrderedFields('CA');
/* =>
    ['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';


Note: Only FR / JA and EN are mocked.