Switch branches/tags
TS-3 add-formatcurrency-function add-formatpercentage-function add-registry add-tslib adi/form-state-size adi/react-shortcuts-refactor better-docs-for-react-serialize build-before-test__docs change-supported-types circle-ci-remove-4933a8 color-utilities create-compose debchn-patch-1 development-docs enzyme-update-rebased enzyme-utilities__mounts event-testing export-isToday-and-isYesterday feature/koa-auth-nonce fix-empty-array-counting-as-errors fix-graphql-proxy-homepage fix-non-required-validators-when-field-empty fix__graphql-version form-state-disable-on-submit form-state-doc-fix get-currency-symbol graphql__version greenkeeper/eslint-plugin-shopify-23.1.0 greenkeeper/eslint-plugin-shopify-24.0.0 greenkeeper/initial greenkeeper/lerna-3.0.0 greenkeeper/lerna-3.0.1 greenkeeper/lerna-3.0.2 greenkeeper/lerna-3.0.3 greenkeeper/lerna-3.0.4 greenkeeper/lerna-3.0.5 greenkeeper/lerna-3.0.6 greenkeeper/lerna-3.1.0 greenkeeper/lerna-3.1.1 greenkeeper/lerna-3.1.2 greenkeeper/lerna-3.2.0 greenkeeper/lerna-3.2.1 greenkeeper/lerna-3.3.0 itp-2.1 jest-mock-router-v4 koa-auth-test__ci-fix koa-auth-tests master optimisticly-regenerate-form-values-on-submit perf-remove-lodash-deep-equal prepublish-only provide-default-for-react-compose-c-type-argument react-google-analytics-nonce react-i18n-minzipped-error react-infuse__init revert-231-simplify-field-types revert-234 revert-301-revert-231-simplify-field-types revert-325-react-import-remote-nonce revert-nested-race-condition safe-redirect shopify-polyfills simplify-itp ssr-async-bundles-2 ssr-async-bundles-backup ssr-async-bundles test-shipit tophat-command typescript-pattern-matching upgrade-apollo-link-1.2.3 upgrade-graphql-tool-utilities-0.8.0 use-original-react-apollo
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
CHANGELOG.md
README.md
package.json
tsconfig.build.json

README.md

@shopify/address

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

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'); // => "POSTAL_CODE"
await getTranslationKey('US', 'zip'); // => "ZIP_CODE"
await getTranslationKey('CA', 'address2'); // => "APT_UNIT_NUMBER"
await getTranslationKey('JA', 'address2'); // => "APT_SUITE_ETC"

Translation keys

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

  • ProvinceKey is one of the following

    • COUNTY
    • EMIRATE
    • GOVERNORATE
    • PREFECTURE
    • PROVINCE
    • REGION
    • STATE_AND_TERRITORY
    • STATE
  • ZipKey is one of the following

    • POSTAL_CODE
    • POSTCODE
    • PINCODE
    • ZIP_CODE
  • Address2Key is one of the following

    • APT_SUITE_ETC
    • APT_UNIT_NUMBER

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

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';

beforeEach(mockCountryRequests);
afterEach(fetch.restore);

Note: Only FR / JA and EN are mocked.