Widget configuration

Configure the autocomplete widget

The v1 widget is designed for small, explicit configuration: choose an input, point at an index, set a result limit, and decide what to do when an address is selected.

Advanced config

<input id="address" name="address" autocomplete="off">
<input id="address_line_1" name="address_line_1">
<input id="address_line_2" name="address_line_2">
<input id="unit" name="unit">
<input id="street_number" name="street_number">
<input id="street" name="street">
<input id="suburb" name="suburb">
<input id="town_city" name="town_city">
<input id="region" name="region">
<input id="postcode" name="postcode">
<input type="hidden" id="selected_address" name="selected_address">
<input type="hidden" id="linz_id" name="linz_id">
<input type="hidden" id="latitude" name="latitude">
<input type="hidden" id="longitude" name="longitude">
<input type="hidden" id="source_version" name="source_version">

<link rel="stylesheet" href="https://streetkit.smp.kiwi/widget/streetkit.css">
<script src="https://streetkit.smp.kiwi/widget/streetkit.js"></script>
<script>
  StreetKit.init({
    input: "#address",
    publicMode: true,
    indexBaseUrl: "https://index.streetkit.smp.kiwi/public/v1",
    limit: 8,
    minQueryLength: 3,
    onSearchStart(event) {
      console.debug("StreetKit search started", event.normalizedQuery);
    },
    onSearchComplete(event) {
      console.debug("StreetKit search complete", event.status, event.results.length);
    },
    onSelect(address) {
      document.querySelector("#selected_address").value = address.label;
      console.log("Selected address", address);
    },
    onClear() {
      document.querySelector("#selected_address").value = "";
    },
    onError(error) {
      console.warn("StreetKit error", error.code);
    },
    fields: {
      label: "#selected_address",
      line1: "#address_line_1",
      line2: "#address_line_2",
      unit: "#unit",
      streetNumber: "#street_number",
      street: "#street",
      suburb: "#suburb",
      city: "#town_city",
      region: "#region",
      postcode: "#postcode",
      linzId: "#linz_id",
      latitude: "#latitude",
      longitude: "#longitude",
      sourceVersion: "#source_version"
    },
    fieldMapping: {
      overwrite: "emptyOrStreetKit",
      clearOnInputChange: "metadata"
    }
  });
</script>

Common options

input: Required. CSS selector or input element to attach the widget to.
indexBaseUrl: Base URL for StreetKit address data. Use the public path such as https://index.streetkit.smp.kiwi/public/v1, a registered path such as https://index.streetkit.smp.kiwi/c/{siteId}/v1, or the local fixture path /index/v1.
mode: Optional explicit access mode: "public" or "registered". Most integrations can use publicMode: true for public access or pass a siteId for registered access.
siteId: Optional public traffic label for registered mode. It must match ^sk_(live|test)_[a-z0-9]{6,32}$. It is not authentication, a secret, an API key, a bearer token, proof of ownership, or quota enforcement.
publicMode: Set to true for public/community index access without a site ID.
limit: Maximum number of suggestions to show. The default is 8; maxResults is accepted as a compatibility alias. The widget renders at most 12 suggestions.
minQueryLength: Minimum query length before search starts. The local default is 3 characters; minLength is accepted as a compatibility alias.
debounceMs: Delay between typing and search. The default is 200 milliseconds.
highlight: Set to false to disable safe text-node highlighting in rendered suggestions.
ascii: Set to true only for legacy ASCII-only forms. Rendered suggestion labels and mapped field strings are folded, while onSelect still receives the source-derived selected-address object.
callbacks: onQuery, onResults, onSearchStart, onSearchComplete, onSelect, onClear, and onError report local widget activity with public-safe payloads. Field mapping warnings use field_mapping_failed.
fields: Optional explicit field map for writing selected-address values into existing form controls.
fieldMapping: Optional overwrite, address-line, and clear behaviour for configured field targets. Supported options are overwrite, lineMode, and clearOnInputChange.
clearMappedFieldsOnClear: Set to false if widget.clear() should leave configured field targets alone.
classes: Optional class-name overrides for the widget host, listbox, status rows, options, metadata, active option, and highlight spans.

Callback payloads

onQuery(event): Runs before a search. The event includes rawQuery, normalizedQuery, normalisedQuery, and requestId.
onSearchStart(event): Runs when a search starts. The event includes the same query fields and requestId.
onSearchComplete(event): Runs for successful, empty, too-short, too-broad, and failed searches. The event includes rawQuery, query, normalized query aliases, requestId, status, results, and search context as plan plus the compatibility alias planning. onResults receives the same event as a compatibility alias.
onSelect(address, context): Runs after the selected address is ready. The first payload is the public selected-address object with id, label, components, location, source, and confidence. The optional second payload contains Radius and Drive Zones context when those features are configured.
onClear(event): Runs when the widget clears a StreetKit-owned selection. The event includes the input element and reason, either "api" or "user".
onError(error): Runs for config, address data, routing, selection, and field-mapping failures. The error includes code, message, and contextual fields such as status, url, siteId, fieldKey, or reason when available.

Selection context

radiusRules adds Radius context using estimated straight-line distance from selected address coordinates. deliveryZones adds Drive Zones context using configured driving-distance results.

StreetKit.init({
  input: "#address",
  publicMode: true,
  indexBaseUrl: "https://index.streetkit.smp.kiwi/public/v1",
  radiusRules: {
    mode: "straight_line",
    origins: [
      { id: "akl-warehouse", label: "Auckland warehouse", lat: -36.9001, lon: 174.8852 }
    ],
    rules: [
      { id: "free-delivery-20km", label: "Free delivery within 20 km", radiusKm: 20, fee: 0 }
    ]
  },
  deliveryZones: {
    enabled: true,
    mode: "precomputed_driving",
    metaUrl: "/streetkit-delivery/meta.json"
  },
  onSelect(address, context) {
    console.log(context.radius);
    console.log(context.delivery);
  }
});

Read the dedicated Radius and Drive Zones docs before displaying eligibility messages.

Field mapping

Field mapping runs only after a user selects a suggestion. The widget writes only the selectors or elements configured in fields; it does not scan, serialize, upload, or store the rest of the form.

Supported built-in targets include label, fullLabel, line1, line2, unit, streetNumber, street, streetName, streetType, streetSuffix, suburb, city, townCity, region, territorialAuthority, postcode, country, latitude, longitude, lat, lon, linzId, id, streetkitId, sourceProvider, sourceDataset, sourceLayer, sourceVersion, and datasetVersion.

Missing selectors are non-blocking. By default StreetKit writes empty configured fields or fields it last wrote itself, dispatches bubbling input and change events, and clears only StreetKit-owned configured values.

V1 field mapping does not include DPID, NZ Post delivery-point, delivered-only, PO Box, Private Bag, courier, or delivery certification fields.

Source metadata describes the LINZ NZ Addresses layer 123113 data used by StreetKit. The widget does not query LINZ while users type addresses into a form.

Accessible integration

Attach StreetKit to a normal labelled text input in the page form. Keep the input in the natural tab order, preserve its visible focus style, and provide the next form control after it so Tab and Shift+Tab behave normally. The widget owns the autocomplete ARIA attributes and suggestion listbox; host pages should avoid adding focus traps or tabbable controls inside the suggestion popup.

Custom address data URL

Use a custom indexBaseUrl when testing local fixtures or pointing at an approved StreetKit address data endpoint.

StreetKit.init({
  input: "#address",
  indexBaseUrl: "https://example.com/streetkit/v1",
  limit: 5
});

Access modes

Public mode reads https://index.streetkit.smp.kiwi/public/v1/meta.json and does not require a siteId. Registered mode reads https://index.streetkit.smp.kiwi/c/{siteId}/v1/meta.json and appends ?site={siteId} to StreetKit address data requests. Metadata remains public-safe and should not include customer names, email addresses, domains, billing details, internal rule IDs, or secrets.

The widget uses normal browser requests and does not send custom authentication headers by default. See rate limits for public, registered, and future protected access guidance.

const siteId = "REPLACE_WITH_ISSUED_SITE_ID";

StreetKit.init({
  input: "#address",
  indexBaseUrl: `https://index.streetkit.smp.kiwi/c/${siteId}/v1`,
  siteId,
  limit: 8
});