# Configuration Reference

A complete reference for every option accepted by [`AddressFinder.setup`](/docs/address-finder/configure.md). Only [`apiKey`](#apikey) and [`outputFields`](#outputfields) are required; everything else is optional and has a sensible default.

Callbacks have their own page - see [Callbacks](/docs/address-finder/callbacks.md). Message strings, CSS classes and inline styles are summarised here and covered in depth under [Messages](/docs/address-finder/messages.md) and [Styling](/docs/address-finder/default-styling.md).

## Required[​](#required "Direct link to Required")

### `apiKey`[​](#apikey "Direct link to apikey")

`string` · required

API Key from your Ideal Postcodes account. Typically begins `ak_`.

### `outputFields`[​](#outputfields "Direct link to outputfields")

`object` · default `{}`

Specifies where to send address data when an address is selected. Maps an address attribute to an input field, identified by a CSS selector `string` or a direct `HTMLElement` reference.

```
{

  line_1: "#line_1",

  line_2: "#line_2",

  line_3: "input[name='line_3']",

  post_town: document.getElementById("post_town"),

  postcode: document.getElementById("postcode")

}
```

The attribute names match the Address response object - e.g. street name populates from [`thoroughfare`](/docs/data/paf.md#thoroughfare). The full list of attributes is in the [UK address data guide](/docs/data/paf.md).

Fields assigned with a query selector are evaluated lazily (when an address attribute needs to be piped to a field). Using an `HTMLElement` instead binds eagerly at setup.

For dynamic assignment, use the [`onAddressRetrieved`](/docs/address-finder/callbacks.md) callback.

## Targeting the DOM[​](#targeting-the-dom "Direct link to Targeting the DOM")

### `inputField`[​](#inputfield "Direct link to inputfield")

`string | HTMLElement` · default `outputFields.line_1`

The `<input>` the Address Finder binds to. Set this when the search field is not your first address line.

### `scope`[​](#scope "Direct link to scope")

`Document | HTMLElement | string` · default `window.document`

Scopes the operable area of the DOM. Useful when the same form appears more than once on a page.

### `document`[​](#document "Direct link to document")

`Document` · default `window.document`

The `Document` to operate on.

### `outputScope`[​](#outputscope "Direct link to outputscope")

`string | HTMLElement | Document | null` · default `null`

Narrows where output fields are searched for. Defaults to the controller `scope`.

### `names`[​](#names "Direct link to names")

`object` · default `{}`

Targets HTML input elements by their `name` attribute (falling back to `aria-label`) rather than by selector.

### `labels`[​](#labels "Direct link to labels")

`object` · default `{}`

Targets HTML input elements by their associated label text.

## Address output and formatting[​](#address-output-and-formatting "Direct link to Address output and formatting")

### `format`[​](#format "Direct link to format")

`"gbr" | "usa"` · default `"gbr"`

The format the resolved address is returned in.

### `titleizePostTown`[​](#titleizeposttown "Direct link to titleizeposttown")

`boolean` · default `true`

Converts the post town from upper case to title case - e.g. `"LONDON"` becomes `"London"`.

### `removeOrganisation`[​](#removeorganisation "Direct link to removeorganisation")

`boolean` · default `false`

Removes the organisation name from the address lines. Addresses that consist only of an organisation name are left untouched, as removing it would leave no premise identifier.

### `populateCounty`[​](#populatecounty "Direct link to populatecounty")

`boolean` · default `true`

Set to `false` to suppress `county` from being populated.

### `populateOrganisation`[​](#populateorganisation "Direct link to populateorganisation")

`boolean` · default `true`

Set to `false` to suppress `organisation_name` from being populated.

## Country and context[​](#country-and-context "Direct link to Country and context")

### `defaultCountry`[​](#defaultcountry "Direct link to defaultcountry")

`string` · default `"GBR"`

The country searched first, before the user changes it.

### `restrictCountries`[​](#restrictcountries "Direct link to restrictcountries")

`string[]` · default `[]`

Narrows the supported countries. An empty array enables all countries. A single country disables country selection and hides the country toolbar.

### `detectCountry`[​](#detectcountry "Direct link to detectcountry")

`boolean` · default `true`

Detects the user's country from their IP address.

### `hideToolbar`[​](#hidetoolbar "Direct link to hidetoolbar")

`boolean` · default `false`

Hides the toolbar so users cannot change country.

### `contexts`[​](#contexts "Direct link to contexts")

`object`

A custom list of countries/contexts the user can select from.

## Search behaviour[​](#search-behaviour "Direct link to Search behaviour")

### `queryOptions`[​](#queryoptions "Direct link to queryoptions")

`object` · default `{}`

A query - such as a filter or bias - applied to suggestion queries. See the [Autocomplete API Reference](/docs/api/find-address.md) for available parameters.

To apply new parameters after setup, use `setQueryOptions` on the controller instance. Do not mutate `options.queryOptions` directly.

### `resolveOptions`[​](#resolveoptions "Direct link to resolveoptions")

`object` · default `{}`

Additional query parameters applied to the address resolve request - the second API call that retrieves the full address when a user selects a suggestion. See the [Resolve Address API Reference](/docs/api/resolve-address.md).

To apply new parameters after setup, use `setResolveOptions` on the controller instance. Do not mutate `options.resolveOptions` directly.

## Key checking[​](#key-checking "Direct link to Key checking")

### `checkKey`[​](#checkkey "Direct link to checkkey")

`boolean` · default `true`

Checks the key is usable before initialising. The check can fail if:

* Your key has no remaining lookups
* Your key has run into its daily lookup limit
* Your key is requested from a URL not on your allowed list
* The user has exceeded their daily limit

On failure the widget does not initialise. Use the [`onFailedCheck`](/docs/address-finder/callbacks.md) callback to handle this case.

## Browser autofill[​](#browser-autofill "Direct link to Browser autofill")

### `autocomplete`[​](#autocomplete "Direct link to autocomplete")

`string` · default `"none"`

Sets the input's `autocomplete=` attribute, aiming to stop browsers (particularly Chrome) presenting a clashing autofill overlay. Best practice changes over time and varies by form - see [this discussion](https://stackoverflow.com/questions/15738259/disabling-chrome-autofill).

## Hiding address fields[​](#hiding-address-fields "Direct link to Hiding address fields")

### `hide`[​](#hide "Direct link to hide")

`(string | HTMLElement)[]` · default `[]`

Elements to hide with `display: none;` when Address Finder initialises. They are unhidden when an address is selected or the user opts to enter an address manually.

```
{

  hide: [

    "#line_1",

    document.getElementById("line_2"),

    document.getElementById("line_3"),

  ],

}
```

Enabling this also renders a clickable element offering manual address entry. Provide your own with [`unhide`](#unhide), or customise the default with [`msgUnhide`](#msgunhide) and [`unhideClass`](#unhideclass).

### `unhide`[​](#unhide "Direct link to unhide")

`string | HTMLElement | null` · default `null`

A custom clickable element to unhide fields hidden with [`hide`](#hide). Suppresses the default unhide element.

### `unhideClass`[​](#unhideclass "Direct link to unhideclass")

`string` · default `"idpc-unhide"`

CSS class applied to the default unhide element.

### `msgUnhide`[​](#msgunhide "Direct link to msgunhide")

`string` · default `"Enter address manually"`

Text of the default unhide element.

### `unhideStyle`[​](#unhidestyle "Direct link to unhidestyle")

`object` · default `{}`

Inline styles applied to the unhide element.

## Positioning[​](#positioning "Direct link to Positioning")

### `alignToInput`[​](#aligntoinput "Direct link to aligntoinput")

`boolean` · default `true`

Automatically aligns the suggestion list to the input.

### `offset`[​](#offset "Direct link to offset")

`number` · default `2`

Vertical offset, in pixels, of the suggestion list from the input.

### `fixed`[​](#fixed "Direct link to fixed")

`boolean` · default `false`

Sets `position: fixed` on the suggestion list element.

## Accessibility[​](#accessibility "Direct link to Accessibility")

### `aria`[​](#aria "Direct link to aria")

`"1.0" | "1.1"` · default `"1.0"`

The WAI-ARIA specification version to target. `"1.0"` enables regressions that receive the widest screen-reader support (notably VoiceOver and NVDA); `"1.1"` targets the more recent spec.

## Messages[​](#messages "Direct link to Messages")

Override any of the user-facing strings. See [Messages](/docs/address-finder/messages.md) for context.

| Option                  | Default                                                |
| ----------------------- | ------------------------------------------------------ |
| `msgPlaceholder`        | `"Type the first line or postal code of your address"` |
| `msgPlaceholderCountry` | `"Select your country"`                                |
| `msgInitial`            | `"Start typing to find address"`                       |
| `msgFallback`           | `"Please enter your address manually"`                 |
| `msgNoMatch`            | `"No matches found"`                                   |
| `msgList`               | `"Select your address"`                                |
| `msgCountryToggle`      | `"Change Country"`                                     |

## CSS classes[​](#css-classes "Direct link to CSS classes")

Override the class applied to each rendered element. See [CSS Classes](/docs/address-finder/css-classes.md).

| Option               | Default               |
| -------------------- | --------------------- |
| `containerClass`     | `"idpc_autocomplete"` |
| `mainClass`          | `"idpc_af"`           |
| `listClass`          | `"idpc_ul"`           |
| `messageClass`       | `"idpc_error"`        |
| `toolbarClass`       | `"idpc_toolbar"`      |
| `countryToggleClass` | `"idpc_country"`      |

## Inline styles[​](#inline-styles "Direct link to Inline styles")

Apply inline styles (a `CSSStyleDeclaration` object) to rendered elements. See [Styling with JavaScript](/docs/address-finder/style-js.md).

| Option           | Applies to                                                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `injectStyle`    | `boolean \| string` - inject the default stylesheet (`true`), skip it (`false`), or load a stylesheet from a URL (`string`). Default `true` |
| `inputStyle`     | the input field                                                                                                                             |
| `containerStyle` | the container wrapping all elements                                                                                                         |
| `mainStyle`      | the main component (list, toolbar, messages)                                                                                                |
| `listStyle`      | the suggestion list                                                                                                                         |
| `liStyle`        | each suggestion list item                                                                                                                   |

## Network and client[​](#network-and-client "Direct link to Network and client")

Inherited from the underlying API client. Defaults suit the production API and rarely need changing.

| Option                | Type       | Default                                               |
| --------------------- | ---------- | ----------------------------------------------------- |
| `baseUrl`             | `string`   | `"api.ideal-postcodes.co.uk"`                         |
| `version`             | `string`   | `"v1"`                                                |
| `tls`                 | `boolean`  | `true`                                                |
| `timeout`             | `number`   | `10000` (ms)                                          |
| `strictAuthorisation` | `boolean`  | `false` - force authorisation via HTTP headers only   |
| `header`              | `object`   | `{}` - default headers added to each request          |
| `tags`                | `string[]` | `[]` - tags appended to requests for your lookup logs |

## Callbacks[​](#callbacks "Direct link to Callbacks")

Every lifecycle hook is documented on the [Callbacks](/docs/address-finder/callbacks.md) page: `onLoaded`, `onFailedCheck`, `onMounted`, `onRemove`, `onOpen`, `onClose`, `onFocus`, `onBlur`, `onInput`, `onKeyDown`, `onMouseDown`, `onSuggestionsRetrieved`, `onSuggestionError`, `onAddressSelected`, `onSelect`, `onAddressRetrieved`, `onAddressPopulated`, `onSearchError`, `onCountrySelected`, `onContextChange` and `onUnhide`.