Division selection widget

Add a branch/postomat picker to any web page in minutes — with Google Maps, filters, and TypeScript support.

Open PlaygroundQuick StartAPI ReferenceChangelog

Two variants

Map view (Google Maps) or Widget view (list with search and filters). Both support the same params and events.

Lazy iframe init

The <iframe> is created only on the first show() call — zero cost before that.

No API key needed

All Nova Post API calls go through the proxy server.

Quick Start — UMD via <script>

Works in any HTML page without a build step.

<!-- 1. Container — must have an explicit height -->
<div id="nova-post-widget" style="width:100%;height:600px"></div>

<!-- 2. Load the SDK -->
<script src="https://integration-widget.novapost.com/sdk.min.js"></script>

<script>
  const widget = new NovaPostWidget.NovaPostWidget({
    container: '#nova-post-widget',
    locale:    'en',
    variant:   'widget',   // 'map' | 'widget'
    viewMode:  'container', // 'container' | 'popup'
    country:   'UA',
    city:      'Київ',
    shipmentRole: 'recipient', // 'recipient' | 'sender'
    theme: 'light', // 'light' | 'dark'

    onReady: () => console.log('Widget ready'),

    onSelect: (division) => {
      console.log(division.name, division.displayAddress)
      widget.hide()
    },
    
    onClear: () => {
      console.log('Selection cleared')
    },

    onError: (err) => console.error(err.message),
  })

  widget.show()
</script>

Configuration — WidgetConfig

PARAM	TYPE	REQUIRED	DEFAULT	DESCRIPTION
container	string | HTMLElement	Yes	—	CSS selector or DOM element to mount into
locale	'uk' | 'en' | 'de' | 'cs'	—	'en'	UI language
variant	'map' | 'widget'	—	'map'	Display mode: map — map. widget — search, division list, and map.
viewMode	'container' | 'popup'	—	'container'	Inline embed or modal popup
shipmentRole	'recipient' | 'sender'	—	'recipient'	Init-only. Whether divisions are picked for handing a parcel in (sender) or collecting it (recipient); fixed as an iframe URL param, ignored by updateParams()
country	string | null	—	—	ISO country code, e.g. 'UA'
city	string | null	—	—	City name to pre-select
senderCountry	string | null	—	—	Sender ISO country code, e.g. 'UA'; unlocks partner PUDO (UPS) selection for allowed countries [PL, UA]
divisionId	number | null	—	—	Pre-select a specific division
divisionCategories	DivisionType[]	—	—	Filter by type; all shown if omitted
autoShow	boolean	—	false	Call show() automatically after init; works only when 'viewMode' = 'container'
mobileBreakpointPx	number	—	768	Fullscreen popup below this viewport width
theme	'light' | 'dark'	—	'light'	UI theme
onSelect	(division: DivisionItem) => void	—	—	Fires when user confirms a division
onClear	() => void	—	—	Fires when the confirmed division is cleared
onReady	() => void	—	—	Fires when iframe is loaded and ready
onError	(error: Error) => void	—	—	Fires on runtime error inside iframe
onClose	(reason?) => void	—	—	Fires when popup is closed

API Methods

widget.show() Show the widget. First call creates the iframe (lazy init).

In container mode — sets display: block on the iframe. In popup mode — opens the overlay. On every call (both modes), once the widget is ready, the map automatically recenters on the previously selected division.

widget.hide() Hide the widget without destroying the iframe.

In container mode — sets display: none. In popup mode — closes the overlay. Calling hide() directly does not fire onClose; that callback only fires when the widget itself requests closing (Escape key, overlay backdrop click, or after a selection), which then triggers hide() internally.

widget.updateParams(params) Update config without recreating the iframe.

Updates city, country, senderCountry, divisionId, divisionCategories, theme, locale. Calls before onReady are queued and flushed automatically.

widget.destroy() Remove iframe, popup elements, and all event listeners.

Call on route change in SPAs or on component unmount (Vue onUnmounted, React useEffect cleanup).

Variants & View Modes

VARIANT	VIEWMODE	RESULT
map	container	Google Maps embedded inline in your page
map	popup	Trigger button → click opens popup with Google Maps
widget	container	Division search with list and map views embedded inline
widget	popup	Trigger button → click opens popup with division search, list, and map views

Selection callbacks

Full object passed to your handler when user confirms a division:

• onSelect receives a division;
• onClear clears host state.

let selectedDivision = null

onSelect: (division) => {
  selectedDivision = division
  division.id               // number  — unique ID
  division.name             // string  — full name
  division.shortName        // string  — short name
  division.displayAddress   // string  — formatted address
  division.divisionCategory // 'PostBranch' | 'CargoBranch' | 'Postomat' | 'PUDO'
  division.source           // 'NPAX' | 'NPUA' | 'InPost' | 'UPS' | ...
  division.latitude         // number | null
  division.longitude        // number | null
  division.maxWeightPlaceRecipient  // number (kg)
  division.maxLengthPlaceRecipient  // number (cm)
  division.addressParts?.region
  division.addressParts?.city
  division.addressParts?.street
  division.addressParts?.postCode
},

onClear: () => {
  selectedDivision = null // also clear the corresponding host form fields
}