The AFD Software React plugin allows for easy integration with the AFD Software API. The plugin provides a collection of React Components that can be added to any React project and with a small amount of configuration add AFD, search, lookup and validation.
The components are provided as either generic HTML elements or as wrappers that add AFD functionality to framework components or custom components.
First install the module:
npm install --save @afd-software/pce-react
afdOptions is an object that should be added as a prop to any context provider or validation component. This contains basic information like credentials and the URL of the AFD API. The AFD API accepts two types of credential pairs Serial/Password and ID/Token, each with their own pceURL. Typically, id/token is recommended.
IMPORTANT: serial/password are not for use in public facing websites, for more information contact the AFD support team.
For ID/Token:
afdOptions = {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
}
For Serial/Password:
afdOptions = {
pceURL: 'https://pce.afd.co.uk/afddata.json',
serial: '11111',
password: 'XXXXXXXXX'
}
There are two main types of address search that can be added to forms to improve the speed, ease, and accuracy of address entry – these are Typeahead and Lookup.
Typeahead is a single search box that when typed in dynamically searches for addresses based on the string input and shows the results in a dropdown box below. Once the user sees their result, they click on it and the address fields will be populated with the full address.
Lookup consists of three controls, a lookup box, a lookup button, and a results field. With Lookup, the user will type a search string in the lookup box (usually a postcode), click on the lookup button, and then the results box will show and will be populated with relevant results. The user then clicks on the result and the address fields will be populated.
We typically recommend Typeahead, but some form designers prefer to use lookup for UK based addresses where looking addresses up via postcode is an already established and expected behaviour.
In all instances of address search and lookup, each form should be wrapped in a context provider. This allows the various fields to communicate with each other and ensures that each form is encapsulated when using multiple forms on a single page.
The context provider is also where the AFD options and various control specific options should be included.
Example:
import { AFDContextProvider } from '@afd-software/pce-react'
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX' },
typeaheadOptions: {
...
} }
return (
<AFDContextProvider {...options}>
<form>
...
</form>
</AFDContextProvider>
)}
export default ExampleComponent
The typeahead component can either be implemented as a native HTML input or can be supplied with a custom component as a child element, with optional helper elements. This makes it easy for developers to maintain a consistent design language across their app with minimum interference by the AFD plugin.
To use a native input simply close the tag:
import { AFDContextProvider, AFDTypeahead, AFDResult } from '@afd-software/pce-react'
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
} }
return (
<AFDContextProvider {...options}>
<AFDTypeahead />
<AFDResult afdResult="Postcode" />
<AFDResult afdResult="Property" />
<AFDResult afdResult="Street" />
<AFDResult afdResult="Locality" />
<AFDResult afdResult="Town" />
</AFDContextProvider>
)
}
To use a custom component, wrap it in the <AFDTypeahead> tag along with any utility components such as labels and tooltips. The typeahead control should be identified using the data attribute data-afd-type={'typeahead'}.
We have provided examples using the Mantine and React-Bootstrap frameworks, however this should work with all custom components. If you have any difficulty getting custom components to work, please contact AFD Support.
import { AFDContextProvider, AFDTypeahead, AFDResult } from '@afd-software/pce-react'
import { TextInput } from '@mantine/core'
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
} }
return (
<AFDContextProvider {...options}>
<AFDTypeahead>
<TextInput placeholder={'Start typing your address'} label={'Address Search'} data-afd-type={'typeahead'} />
</AFDTypeahead>
<AFDResult afdResult={'Postcode'}>
<TextInput label={'Postcode'} />
</AFDResult>
<AFDResult afdResult={'Property'}>
<TextInput label={'Property'} />
</AFDResult>
<AFDResult afdResult={'Street'}>
<TextInput label={'Street'} />
</AFDResult>
<AFDResult afdResult={'Locality'}>
<TextInput label={'Locality'} />
</AFDResult>
<AFDResult afdResult={'Town'}>
<TextInput label={'Town'} />
</AFDResult>
</AFDContextProvider>
)}
Notice here that the component used for the Typeahead control can be embedded further down the tree, it does not need to be a direct child of the <AFDTypeahead> component.
import { AFDContextProvider, AFDTypeahead, AFDResult } from '@afd-software/pce-react'
import { Form } from "react-bootstrap";
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
} }
return (
<AFDContextProvider {...options}>
<Form>
<AFDTypeahead>
<Form.Group>
<Form.Label data-hide-with-afd-control={true}>Address Search</Form.Label>
<Form.Control type="text" placeholder={'Start typing your address'} data-afd-type= {'typeahead'} />
</Form.Group>
</AFDTypeahead>
<Form.Group>
<AFDResult afdResult={'Postcode'}>
<Form.Label>Postcode</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Property'}>
<Form.Label>Property</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Street'}>
<Form.Label>Street</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Locality'}>
<Form.Label>Locality</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Town'}>
<Form.Label>Town</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
</Form>
</AFDContextProvider>
)}
label?: string | null
The label added to the input. This is only applicable when using the native HTML element.
placeholder?: string | null
The placeholder added to the input. This is only applicable when using the native HTML element.
maxItems?: number
The maximum number of items that a search should return.
matchPositions?: boolean
When true, matching parts of the search string will be enclosed in < span >< /span > with font weight set to bold.
afterHideTypeahead?: boolean
When a search is complete, and address selected the typeahead control will be hidden. If you would like the option to search again, see the section “Search Again Button” for custom components and the “Search Again” options (below) for native elements.
searchAgain?: boolean
Adds a search again button that appears after a search and will reshow the typeahead button when clicked. Only applicable when using native HTML element and afterHideTypeahead: true.
searchAgainText?: string
Text shown if searchAgain: true. Only applicable when using native HTML element, afterHideTypeahead: true and searchAgain: true.
afterClearTypeahead?: boolean
Clears the typeahead box after an address has been selected and the results populated.
manualInputButton?: boolean
Adds a button that when clicked shows the result fields and hides the typeahead field. Only applicable when using native HTML element and resultfields.beforeHideResults: true.
manualInputButtonText?: string
Text shown if manualInputButton: true. Only applicable when using native HTML element, resultfields.beforeHideResults: true and manualInputButton: true.
manualInputAddressSearchText?: string
When manualInputButton: true, a second button is created that toggles back to the typeahead control if the manual input button has been clicked. This option is the text for that button. Only applicable when using native HTML element, resultfields.beforeHideResults: true and manualInputButton: true.
fewResultsManualInput?: boolean
When fewer results than the number set in maxItems are returned by the AFD API, an extra result is inserted that when clicked hides the search box and shows the result fields so that the user can enter them manually. Only applicable when resultfields.beforeHideResults: true.
fewResultsManualInputText?: string
retrieveFields?: string
‘standard’ causes the API to return standard PCE fields. ‘international’ returns international fields.
minLength?: number
The minimum number of characters in the typeahead field before triggering a search.
postcodeFirst?: boolean
In the search result dropdown, this option dictates whether the Postcode will be shown at the beginning or end of the address.
listEnv?: boolean
flatSubBuild?: boolean
extraPCESearchParams?: {}
Extra parameters to add to PCE search API calls.
extraPCERetrieveParams?: {}
Extra parameters to add to PCE retrieve API calls.
bankLookup?: boolean
Instead of looking up addresses, lookup UK banks. Requires AFD BankFinder licence.
Lookup functionality consists of three components, <AFDLookupField>, <AFDLookupButton> and <AFDLookupResults>. They can either be implemented as a native HTML form controls or can be supplied with a custom component as a child element, with optional helper elements. This makes it easy for developers to maintain a consistent design language across their app with minimum interference by the AFD plugin.
To use a native input, simply close the tags of the three AFD lookup components.
<AFDLookupField>
import { AFDContextProvider, AFDTypeahead, AFDResult } from '@afd-software/pce-react'
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
} }
return (
<AFDContextProvider {...options}>
<AFDLookupField />
<AFDLookupButton />
<AFDLookupResults />
<AFDResult afdResult="Postcode" />
<AFDResult afdResult="Property" />
<AFDResult afdResult="Street" />
<AFDResult afdResult="Locality" />
<AFDResult afdResult="Town" />
</AFDContextProvider>
)
}
There are three tags used to enable lookup functionality, <AFDLookupField>, <AFDLookupButton> and <AFDLookupResults>.
A custom component wrapped in the <AFDLookupField> component should ultimately contain an input element that uses an onChange event and the resulting event object should contain the input string in e.target.value. The actual input component should have the data-afd-type={'lookupField'} prop set to identify it.
A custom component wrapped in the <AFDLookupButton> should have the data-afd-type={'lookupField'} prop set to identify it.
When using custom components for <AFDLookupResults>, these need to be provided as React elements as a template. These can either be nested divs, << ul> and < li> or any similar structure. They should be added as the props resultsContainer and resultsItem.
We have provided examples using the Mantine and React-Bootstrap frameworks, however this should work with all custom components. If you have any difficulty getting custom components to work, please contact AFD Support.
import {
AFDContextProvider,
AFDLookupField,
AFDLookupButton,
AFDLookupResults,
AFDResult
} from '@afd-software/pce-react'
import { TextInput, Button } from "@mantine/core";
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
lookupOptions: {
... // see "Lookup Options"
} }
const resultsContainer = (<List style={listStyle} listStyleType={'none'}>a</List>)
const resultsItem = (<List.Item style={listItemStyle}>b</List.Item>)
return (
<AFDContextProvider {...options}>
<AFDLookupField>
<TextInput placeholder={ctx.lookupOptions.placeholder} label={ctx.lookupOptions.label} data-afd-type={'lookupField'} />
</AFDLookupField>
<AFDLookupButton>
<Button>Lookup</Button>
</AFDLookupButton>
<AFDLookupResults resultsContainer={resultsContainer} resultsItem={resultsItem} />
<AFDResult afdResult={'Postcode'}>
<TextInput label={'Postcode'}/>
</AFDResult>
<AFDResult afdResult={'Property'}>
<TextInput label={'Property'} />
</AFDResult>
<AFDResult afdResult={'Street'}>
<TextInput label={'Street'} />
</AFDResult>
<AFDResult afdResult={'Locality'}>
<TextInput label={'Locality'} />
</AFDResult>
<AFDResult afdResult={'Town'}>
<TextInput label={'Town'} />
</AFDResult>
</AFDContextProvider>
}
}
import {
AFDContextProvider,
AFDLookupField,
AFDLookupButton,
AFDLookupResults,
AFDResult
} from '@afd-software/pce-react'
import { Form, Button } from "react-bootstrap";
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
} }
return (
<AFDContextProvider {...options}>
<Form>
<AFDTypeahead>
<Form.Group>
<Form.Label data-hide-with-afd-control={true}>Address Search</Form.Label>
<Form.Control type="text" placeholder={'Start typing your address'} data-afd-type= {'typeahead'} />
</Form.Group>
</AFDTypeahead>
<Form.Group>
<AFDResult afdResult={'Postcode'}>
<Form.Label>Postcode</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Property'}>
<Form.Label>Property</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Street'}>
<Form.Label>Street</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Locality'}>
<Form.Label>Locality</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
<Form.Group>
<AFDResult afdResult={'Town'}>
<Form.Label>Town</Form.Label>
<Form.Control/>
</AFDResult>
</Form.Group>
</Form>
</AFDContextProvider>
)}
Once an address has been selected, the form needs to be populated. This is achieved using the <AFDResult> component. Like Typeahead and Lookup, this can be done either by using native HTML elements or by supplying a custom component.
There are also some options that can be set that govern the visibility of the fields at various stages of use.
To use a native input, simply close the tag.
import { AFDContextProvider, AFDTypeahead, AFDResult } from '@afd-software/pce-react'
const ExampleComponent = () => {
const options = {
afdOptions: {
pceURL: 'https://apps.afd.co.uk/json',
id: '1111',
token: 'XXXXXXXXX'
},
typeaheadOptions: {
... // see "Typeahead Options"
},
resultOptions: {
...
} }
return (
<AFDContextProvider {...options}>
<AFDTypeahead /> {/* or lookup */}
<AFDResult afdResult="Postcode" />
<AFDResult afdResult="Property" />
<AFDResult afdResult="Street" />
<AFDResult afdResult="Locality" />
<AFDResult afdResult="Town" />
</AFDContextProvider>
)
}
For further help and support, please contact support@afd.co.uk.
We serve thousands of organisations and a network of hundreds of partners across multiple industry sectors, enabling them to have full confidence in their contact data.