Address picker guide

The component ElemrootAddressPicker is one script file without dependencies (with a map it loads MapLibre GL JS itself). It works with Estonian, Latvian and Lithuanian addresses and returns an output on every selection that you can store directly in your system. You can assemble the settings in the configurator, which also gives you the ready code.

Installation

Add the script, an empty element and the create call. The element gets the class eap; several components on one page are allowed.

<script src="https://examples.elemroot.com/widget/aadressivalija/v1/aadressivalija.js"></script>
<div id="aadress"></div>
<script>
  var picker = ElemrootAddressPicker.create('#aadress', {
    key: 'YOUR_API_KEY',
    countries: ['ee'],
    map: 'raster',
    onChange: function (a) {
      // a = null (cleared) or the output (see below)
    }
  });
</script>

Options

The same setting can be given to all components at once: ElemrootAddressPicker.defaults = { endpoints: { … } }.

Map

When map is set, the map is visible at once. With an empty value it shows the area of the configured countries (one country: that country; several: all of them; after a country switch that country), with a selected address the marker at zoom 15. The map can be panned and zoomed with the buttons and the mouse wheel. The raster map covers Estonia; for Latvian and Lithuanian addresses the component shows the vector map even when 'raster' is set.

With drag on, a click on the map places the marker at the click point and the marker can be dragged. Reverse geocoding finds the nearest address to the point, it is looked up in the address search and selected like a normal match, so the output has the same shape as with a search. A point in another allowed country switches the country. If there is no address within 500 m, the marker stays at the previous address and the component says so.

The map size comes from CSS variables: --eap-map-h (height, default 180px, applies with the map below) and --eap-map-w (width beside the form, default 300px).

Output

onChange delivers and getValue() returns an object; the same object comes with the event elemroot-address (event.detail) from the component element.

{
  "country": "ee",
  "address": "Anne tn 1-1, Tartu linn, Tartu linn, Tartu maakond",
  "addressId": 3124193,
  "postcode": "50604",
  "coordinates": { "lon": 26.742994, "lat": 58.381567 },
  "nationalCoordinates": { "epsg": "EPSG:3301", "x": 6474513.33, "y": 660418.47, "north": 6474513.33, "east": 660418.47 },
  "components": { "county": "Tartu maakond", "municipality": "Tartu linn", "settlement": "Tartu linn", "street": "Anne tänav", "house": "1", "apartment": "1" },
  "adsType": "A8",
  "final": true
}

Methods

Styling

The component brings its own style. Override colours and sizes with CSS variables on the component element: --eap-accent, --eap-border, --eap-bg, --eap-ink, --eap-muted, --eap-field (background of the select boxes), --eap-radius, --eap-map-h, --eap-map-w. All internal classes start with the prefix eap-.

#aadress { --eap-accent: #0a7d4f; --eap-map-h: 260px; --eap-map-w: 360px; }

Accessibility

For a screen reader the search field is a combo box (role="combobox") and the suggestions a list (role="listbox", role="option"): the open state, the active row and the selection are in the attributes aria-expanded, aria-activedescendant and aria-selected. Hints are read out (aria-live="polite"). Arrow keys, Enter and Escape work in the list; the dropdowns and buttons are ordinary labelled form elements.