loading

v33.3.0

select option

Address Forms

How to utilize the AddressAutocomplete component from the @carta/identity team

Important note: this component is not maintained by the ink team. If you have any questions, please reach out to the identity team in the #team-eng-profile Slack channel.

Establishing a new pattern for address forms at Carta

The ink team is proud to partner with the @carta/identity team to introduce the AddressAutocomplete component

The AddressAutocomplete component uses the Google Maps API and the Carta address service to create a full-stack address component which includes autocomplete functionality. All new address forms being added to the Carta platform should utilize this component, rather than building a form from scratch.

Address autocomplete video

General guidelines

  • Make sure the address service is running locally or is accessible at http://localhost:8053 for local development.
  • Three letter country code is used to determine which component to be displayed, so for existing addresses it is important to pass in either the country name in country or three letter country code in countryCode field.
  • By default component is rendered as non stacked but if stacked version is preferred please set isFull and isStacked optional props.

Integration guide

Host autocomplete app within a Frontend Platform monorepo app

To use the AddressAutocomplete component in a FEP monorepo app, use the Frontend Platform team's FARSComponent to host the remote app within the monorepo app.

<FARSComponent
environment="local"
scope="identity"
baseUrl="https://d1rvb1lpl8qv3z.cloudfront.net"
module="AddressAutocomplete"
props={{
id: 'tax-address-validation',
addressFields,
setFields: (fields) => console.log('fields change`, fields),
}}
/>

The snippet above is hosting the remote app from a test environment. Right now the baseUrl is hardcoded to get the app that is deployed on test environment. This can be changed to baseUrl={window.AWS_CLOUDFRONT_FEDERATED_BUNDLES_BASE}.

You can add devServer proxy in the webpack.config.ext.js file of the host monorepo app to route traffic to locally running address-service.

devServer: {
proxy: {
'/api/address-service/v1': {
target: 'http://localhost:8053',
pathRewrite: { '^/api/address-service/v1': '/v1/' },
},
},
}

Host autocomplete app within carta-web

To use the AddressAutocomplete component on carta-web, utilize useState to instantiate address information in the following format:

const [fields, setFields] =
useState <
AddressFields >
{
streetAddress1: "",
streetAddress2: "",
streetAddress3: "",
city: "",
postalCode: "",
province: "",
countryCode: "",
country: "",
provinceCode: "",
vettedBy: VettedBy.NO_ONE.toString(),
isValid: false,
locationId: "",
}

Then, render the autocomplete app using FARSComponent and pass in the address object to the component:

<FARSComponent
baseUrl={window.AWS_CLOUDFRONT_FEDERATED_BUNDLES_BASE}
environment={window.CURRENT_ENV as Environment}
scope="identity"
module="AddressAutocomplete"
props={{
id: 'address-autocomplete-id',
addressFields: autocompleteFields,
setFields: setAutocompleteAddressFields,
routerType: 'browser',
}}
/>

API

The AddressAutocomplete component accepts the following props:

export type AddressFields = {
/** Address field 1 */
streetAddress1: string,
/** Address field 2 */
streetAddress2: string,
/** Address field 3 */
streetAddress3: string,
/** City */
city: string,
/** Subdivision name eg: Alberta */
province: string,
/** Postalcode/ zip code */
postalCode: string,
/** Country long name eg: United States, Canada */
country: string,
/** Subdivision two letter iso code. eg: AB */
provinceCode: string,
/** Country three-letter iso code eg: USA, CAN */
countryCode: string,
/** Country two-letter iso code eg: US, CA */
countryCodeAlpha2?: string,
/** Random hash value returned from Address Service */
locationId?: string | null,
/** Flag determining if address is validate */
isValid?: boolean,
/** Value holder determining who validated the address */
vettedBy?: string,
}
/** Unique identifier \*/
id: string;
/** Address fields that will be set by the component. Create a use state hook of type AddressFields and pass it down to the component. _/
addressFields: AddressFields;
/\*\* callback of type React dispatch. This will be used to assign the values to AddressFields. Create a usestate hook of type AddressFields and assign the setter to this prop. _/
setFields: React.Dispatch<React.SetStateAction<AddressFields>>;
/** Marks the element with a given id to make it easier to select it on tests \*/
'data-testid'?: string | number;
/** Set this prop if you'd like a countryCodeAlpha2 included in your response \*/
returnCountryCodeAlpha2?: boolean;
isFull?: boolean;
isStacked?: boolean;
/* Set this if you'd like to conditionally show field-level validation errors onChange of the address field */
validationCriteria?: AddressFieldsValidation

Validation criteria is input into Ink's Field error prop and input into the address component as shown below.

type ValidationFunction = (input: string) => string | false;
type AddressFieldsValidation = {
streetAddress1?: ValidationFunction,
streetAddress2?: ValidationFunction,
streetAddress3?: ValidationFunction,
city?: ValidationFunction,
postalCode?: ValidationFunction,
province?: ValidationFunction,
}

Example validation:

const postalCodeValidation = (postalCode: string) => {
if (postalCode.length > 0 && isNaN(Number(postalCode)) {
return "must be number";
}
if (postalCode.length < 5) {
return "must be at least one char long";
}
return false;
}
const validationCriteria = {
postalCode: postalCodeValidation
...
}

Examples

For real-world examples, see the following implementations of the AddressAutocomplete component:

Form Flow

Form validation, done right, can improve the form filling experience, and user satisfaction

View pattern

Form UX Writing

Forms are text interfaces. Writing good questions, help text, and actionable error messages is the single most important thing you can do to create great forms.

View pattern

Form Layout

Layout, type hierarchy, and color, impact legibility, usability, and completion metrics

View pattern

Is this page helpful?