Tools
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.
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.
http://localhost:8053
for local development.country
or three letter country code in countryCode
field.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.
<FARSComponentenvironment="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/' },},},}
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:
<FARSComponentbaseUrl={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',}}/>
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...}
For real-world examples, see the following implementations of the AddressAutocomplete component:
Form validation, done right, can improve the form filling experience, and user satisfaction
View patternForms 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 patternLayout, type hierarchy, and color, impact legibility, usability, and completion metrics
View patternIs this page helpful?