# Configuration Reference

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

Callbacks have their own page - see [Callbacks](/docs/postcode-lookup/callbacks.md). Message strings and CSS classes are summarised here and covered in depth under [Messages](/docs/postcode-lookup/messages.md) and [CSS Classes](/docs/postcode-lookup/css-classes.md).

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

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

`string | HTMLElement` · required

The area on your page where Postcode Lookup renders its interface - typically a `<div>`, referenced by CSS selector or a direct element reference.

### `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 an `HTMLElement`.

```
{

  line_1: "#line_1",

  line_2: "#line_2",

  line_3: "#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 is in the [UK address data guide](/docs/data/paf.md). Fields assigned with a query selector are evaluated lazily.

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

### `strictlyPostcodes`[​](#strictlypostcodes "Direct link to strictlypostcodes")

`boolean` · default `true`

When `true`, only postcodes are searched. Set to `false` to search the term as a complete address, enabling queries such as `SW1A 2AA 10`.

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

`number` · default `10`

Maximum number of addresses presented after an address search. Only applies when `strictlyPostcodes` is `false`.

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

`number` · default `500`

Milliseconds the search button stays disabled after a click, preventing double presses. Set to `0` to disable.

### `selectSinglePremise`[​](#selectsinglepremise "Direct link to selectsinglepremise")

`boolean` · default `false`

When `true`, a single-premise result is populated immediately without showing the selection dropdown. [`onAddressSelected`](/docs/postcode-lookup/callbacks.md) still fires.

### `autoSearchSingleSuggestion`[​](#autosearchsinglesuggestion "Direct link to autosearchsinglesuggestion")

`boolean` · default `true`

When a postcode lookup fails but returns exactly one suggestion, the input is updated with that suggestion and a new search is triggered automatically.

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

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

`boolean` · default `true`

Title-case the post town (`true`) or keep it in all caps (`false`). All caps is recommended by Royal Mail's good addressing guidelines.

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

`boolean` · default `false`

Strips the organisation name from the address lines. Note that some "Large User" addresses consist only of an organisation name, post town and postcode.

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

`boolean` · default `true`

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

## Input field[​](#input-field "Direct link to Input field")

| Option           | Type                                 | Default                                                                                    |
| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ |
| `input`          | `string \| HTMLInputElement \| null` | `null` - supply your own input instead of the generated one                                |
| `inputId`        | `string \| null`                     | `null`                                                                                     |
| `inputClass`     | `string \| null`                     | `"idpc-input"`                                                                             |
| `inputAriaLabel` | `string`                             | `"Search a postcode to retrieve your address"`                                             |
| `placeholder`    | `string`                             | `"Search your postcode"`                                                                   |
| `inputStyle`     | `object`                             | `{}` - inline styles for the input                                                         |
| `autocomplete`   | `string`                             | `"none"` - sets the input's `autocomplete=` attribute to prevent clashing browser autofill |

## Button[​](#button "Direct link to Button")

| Option            | Type                                  | Default                               |
| ----------------- | ------------------------------------- | ------------------------------------- |
| `button`          | `string \| HTMLButtonElement \| null` | `null` - supply your own button       |
| `buttonId`        | `string \| null`                      | `null`                                |
| `buttonLabel`     | `string`                              | `"Find my Address"`                   |
| `buttonAriaLabel` | `string`                              | `"Search for address using postcode"` |
| `buttonClass`     | `string \| null`                      | `"idpc-button"`                       |
| `buttonStyle`     | `object`                              | `{}` - inline styles for the button   |

## Address dropdown[​](#address-dropdown "Direct link to Address dropdown")

| Option                 | Type                               | Default                                                  |
| ---------------------- | ---------------------------------- | -------------------------------------------------------- |
| `selectContainer`      | `string \| HTMLDivElement \| null` | `null` - element the results `<select>` is inserted into |
| `selectContainerId`    | `string \| null`                   | `null`                                                   |
| `selectContainerClass` | `string \| null`                   | `"idpc-select-container"`                                |
| `selectId`             | `string \| null`                   | `null`                                                   |
| `selectClass`          | `string \| null`                   | `"idpc-select"`                                          |
| `selectAriaLabel`      | `string \| null`                   | `"Select your address"`                                  |
| `selectStyle`          | `object`                           | `{}` - inline styles for the `<select>`                  |

### `postcodeSearchFormatter`[​](#postcodesearchformatter "Direct link to postcodesearchformatter")

`function`

Converts an address object into the suggestion string shown in the dropdown after a postcode search.

### `addressSearchFormatter`[​](#addresssearchformatter "Direct link to addresssearchformatter")

`function`

Converts an address object into the suggestion string shown after a freeform address search.

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

Override any user-facing string. See [Messages](/docs/postcode-lookup/messages.md).

| Option               | Default                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `msgSelect`          | `"Please select your address"`                                                                  |
| `msgDisabled`        | `"Finding addresses..."`                                                                        |
| `msgNotFound`        | `"Your postcode could not be found. Please type in your address"`                               |
| `msgAddressNotFound` | `"We could not find a match for your address. Please type in your address"`                     |
| `msgError`           | `"Sorry, we weren't able to get the address you were looking for. Please type in your address"` |
| `msgUnhide`          | `"Enter address manually"`                                                                      |

## Message container[​](#message-container "Direct link to Message container")

| Option         | Type                                     | Default                                        |
| -------------- | ---------------------------------------- | ---------------------------------------------- |
| `message`      | `string \| HTMLParagraphElement \| null` | `null` - supply your own message container     |
| `messageId`    | `string \| null`                         | `null`                                         |
| `messageClass` | `string \| null`                         | `"idpc-error"`                                 |
| `messageStyle` | `object`                                 | `{}` - inline styles for the message container |

## 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 Postcode Lookup initialises. They are unhidden when an address is selected or the user opts for manual entry.

```
{

  hide: [

    "#line_1",

    document.getElementById("line_2"),

    document.querySelector("#line_3"),

  ],

}
```

Enabling this also renders a clickable element offering manual entry. Provide your own with [`unhide`](#unhide), or customise the default with [`msgUnhide`](#messages) 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).

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

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

CSS class applied to the default unhide element.

## Container styling[​](#container-styling "Direct link to Container styling")

### `contextStyle`[​](#contextstyle "Direct link to contextstyle")

`object` · default `{}`

Inline styles applied to the `context` container.

## 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/postcode-lookup/callbacks.md) callback to handle this case.

## DOM scoping[​](#dom-scoping "Direct link to DOM scoping")

| Option        | Type                                        | Default                                                 |
| ------------- | ------------------------------------------- | ------------------------------------------------------- |
| `scope`       | `Document \| HTMLElement \| string`         | `window.document` - scopes the operable area of the DOM |
| `document`    | `Document`                                  | `window.document`                                       |
| `outputScope` | `string \| HTMLElement \| Document \| null` | `null` - narrows where output fields are searched for   |

## 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`                       |
| `header`              | `object`   | `{}`                          |
| `tags`                | `string[]` | `[]`                          |

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

Every lifecycle hook is documented on the [Callbacks](/docs/postcode-lookup/callbacks.md) page: `onLoaded`, `onFailedCheck`, `onButtonTrigger`, `onLookupTriggered`, `shouldLookupTrigger`, `onSearchCompleted`, `onSearchError`, `onAddressesRetrieved`, `onAddressSelected`, `onAddressPopulated`, `onSelectCreated`, `onSelectRemoved`, `onUnhide` and `onRemove`.