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:
Is this page helpful?