# Map Address Facet

> Address or ZIP lookup control for geo-radius dealer locator facets.

# Map Address Facet

`Map Address Facet` lets visitors search an address or ZIP code through the OME LocationIQ proxy. It stores the selected label, latitude, longitude, and provider ID on the component root, then combines with a same-target [Map Radius Facet](/facets/component-families/map-radius-facet) to emit a `geo_radius` value.

## Required Setup

- Configure a LocationIQ token in OME settings.
- Store latitude and longitude meta on each result post.
- Use the same target ID on `Map Address Facet`, `Map Radius Facet`, [Map Facet](/facets/component-families/map-facet), and [Facet Target](/facets/component-families/facet-target).
- Set matching latitude and longitude meta keys on the address and map components.

## Props

| Group    | Prop                   | Default                                  | Meaning                                                        |
| -------- | ---------------------- | ---------------------------------------- | -------------------------------------------------------------- |
| Settings | `target`               | empty                                    | Shared target ID.                                              |
| Settings | `placeholder`          | `Search address...`                      | Placeholder text shown inside the address input.               |
| Settings | `minimum_query_length` | `3`                                      | Number of characters required before lookup starts.            |
| Settings | `debounce_ms`          | `300`                                    | Delay before address lookup requests are sent.                 |
| Settings | `clear_aria_label`     | `Clear address`                          | Accessible name for the clear button inside the address input. |
| Query    | `lat_meta_key`         | `latitude`                               | Meta key used for result latitude values.                      |
| Query    | `lng_meta_key`         | `longitude`                              | Meta key used for result longitude values.                     |
| Styling  | `class`                | `ome-map-address-facet-default`          | Root wrapper class.                                            |
| Styling  | `input_class`          | `ome-map-address-facet-default__input`   | The search input.                                              |
| Styling  | `clear_button_class`   | `ome-map-address-facet-default__clear`   | The inline ✕ clear button.                                     |
| Styling  | `results_class`        | `ome-map-address-facet-default__results` | The results list.                                              |
| Styling  | `result_item_class`    | `ome-map-address-facet-default__result`  | Each result item (applied by the runtime).                     |
| Styling  | `status_class`         | `ome-map-address-facet-default__status`  | The status region.                                             |
| Styling  | `results_host_class`   | `ome-map-address-facet-default__host`    | The floating results host overlay.                             |

### Preview

The Map Address Facet ships an Etch-builder preview mode so you can design the results dropdown and clear button before live geocoding is wired up.

| Group   | Prop                | Default | Meaning                                                      |
| ------- | ------------------- | ------- | ------------------------------------------------------------ |
| Preview | `show_results`      | `true`  | In Etch: render two sample addresses into the results list.  |
| Preview | `show_clear_button` | `true`  | In Etch: render the clear ✕ visibly (no selection required). |

## Runtime Behavior

Typing opens geocode suggestions. Selecting a suggestion filters the target when a radius is selected, centers the paired map, fits the selected radius, and draws the radius circle. Clearing the address clears the radius filter and removes the map circle.

The public `ome:map-address-change` event exposes the selected human-readable address or `null`. The [Facet Events API](/facets/custom-events) includes a complete recipe for adding that address as `saddr` to authored Map POI direction links before Map consumes refreshed selected content.

### Clear button

When an address is selected, an inline ✕ icon appears at the right edge of the input. Clicking it clears the selection, the input value, and the cached results list. The icon's accessible name is configurable via `settings.clear_aria_label`.

### Selection clears results

Selecting an address from the dropdown closes the dropdown immediately and clears the cached results. The dropdown cannot reappear until a new query is typed.