@placefield/widget

Typed loader helpers for the hosted PlaceField browser widget.

This package is for bundler-based browser apps that want TypeScript types and a clean import path while still using the supported hosted PlaceField bundles from https://cdn.placefield.dev.

• PlaceField website: https://placefield.dev
• Docs: https://placefield.dev/docs
• API reference: https://placefield.dev/api
• Runnable examples: https://github.com/PlaceField/placefield-examples

It does not embed a PlaceField API key, does not call the PlaceField API by itself, and does not replace backend/API integrations. Browser widget integrations use public pf_pub_... keys. Keep secret pf_live_... keys on your backend.

Install

npm install @placefield/widget

Full Widget

import {
  createPlaceFieldWidget,
  type PlaceFieldAutocompleteResult,
  type PlaceFieldWidgetOptions
} from "@placefield/widget";

const options: PlaceFieldWidgetOptions = {
  key: "pf_pub_xxx",
  geoBias: "country",
  typePreset: "default",
  lang: "en",
  mobile: "fullscreen",
  fields: {
    id: "#location_id",
    country: "#country",
    hierarchy: "#hierarchy",
    lat: "#lat",
    lon: "#lon"
  },
  onSelect(result: PlaceFieldAutocompleteResult) {
    console.log(result.id, result.label);
  }
};

const widget = await createPlaceFieldWidget("#city", options);

// Later, if needed:
widget.destroy();

createPlaceFieldWidget(...) loads:

• https://cdn.placefield.dev/placefield-widget.css
• https://cdn.placefield.dev/placefield-widget.min.js

Then it calls PlaceField.widget(...) with typed options.

Basic JS

import { attachPlaceField } from "@placefield/widget";

const autocomplete = await attachPlaceField("#city", {
  key: "pf_pub_xxx",
  geoBias: "country",
  typePreset: "default",
  onSelect(result) {
    console.log(result);
  }
});

autocomplete.destroy();

attachPlaceField(...) loads:

• https://cdn.placefield.dev/placefield.css
• https://cdn.placefield.dev/placefield.min.js

Then it calls PlaceField.attach(...) with typed options.

Loader Only

If you want to load the hosted assets and call the browser global yourself:

import { loadPlaceFieldWidget } from "@placefield/widget";

const PlaceField = await loadPlaceFieldWidget();

PlaceField.widget?.("#city", {
  key: "pf_pub_xxx",
  mobile: "fullscreen"
});

Framework Usage

Call the helpers only in browser/client code, after the input exists in the DOM. For React, that usually means inside useEffect.

import { useEffect, useRef } from "react";
import {
  createPlaceFieldWidget,
  type PlaceFieldAutocompleteResult,
  type PlaceFieldWidgetInstance,
  type PlaceFieldWidgetOptions
} from "@placefield/widget";

export function CityField() {
  const inputRef = useRef<HTMLInputElement | null>(null);

  useEffect(() => {
    let widget: PlaceFieldWidgetInstance | undefined;

    if (!inputRef.current) {
      return undefined;
    }

    const options: PlaceFieldWidgetOptions = {
      key: "pf_pub_xxx",
      geoBias: "country",
      onSelect(result: PlaceFieldAutocompleteResult) {
        console.log(result.id, result.label);
      }
    };

    createPlaceFieldWidget(inputRef.current, options).then((instance) => {
      widget = instance;
    });

    return () => {
      widget?.destroy();
    };
  }, []);

  return <input ref={inputRef} id="city" name="city" autoComplete="off" />;
}

Loader Options

The default loader uses the production CDN. You can override asset URLs for testing or self-hosted deployments:

await createPlaceFieldWidget("#city", options, {
  assetBaseUrl: "https://cdn.example.com/placefield",
  timeoutMs: 10000
});

Available loader options include:

• assetBaseUrl
• scriptUrl
• stylesheetUrl
• loadStyles
• timeoutMs
• nonce, scriptNonce, stylesheetNonce
• integrity, scriptIntegrity, stylesheetIntegrity
• crossOrigin

Terms

This package is proprietary PlaceField integration software, not an open-source license grant. It is provided for PlaceField integrations and is governed by the PlaceField commercial terms at https://placefield.dev/terms. PlaceField API and hosted widget usage require a valid PlaceField key.