> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/methods/page-2/page-2-1.md).

# Page 2-1

### 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:    'uk',
    variant:   'widget',   // 'map' | 'widget'
    viewMode:  'container', // 'container' | 'popup'
    country:   'UA',
    city:      'Київ',

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

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

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

  widget.show()
</script>
```

### Quick Start — ESM (Vite / Webpack)

Import directly into your bundler project

```
import { NovaPostWidget } from './sdk.esm.js'

const widget = new NovaPostWidget({
  container: '#nova-post-widget',
  locale:    'uk',
  country:   'UA',
  onSelect: (division) => console.log(division),
})

widget.show()
```

### Configuration — WidgetConfig

<table data-search="false"><thead><tr><th width="177">PARAM</th><th width="178">TYPE</th><th width="115">REQUIRED</th><th width="108">DEFAULT</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td>container</td><td>string | HTMLElement</td><td>Yes</td><td>—</td><td>CSS selector or DOM element to mount into</td></tr><tr><td>locale</td><td>'uk' | 'en' | 'de' | 'cs'</td><td>—</td><td>'uk'</td><td>UI language</td></tr><tr><td>variant</td><td>'map' | 'widget'</td><td>—</td><td>'map'</td><td>Display mode: map or list with filters</td></tr><tr><td>viewMode</td><td>'container' | 'popup'</td><td>—</td><td>'container'</td><td>Inline embed or modal popup</td></tr><tr><td>country</td><td>string | null</td><td>—</td><td>—</td><td>ISO country code, e.g. 'UA'</td></tr><tr><td>city</td><td>string | null</td><td>—</td><td>—</td><td>City name to pre-select</td></tr><tr><td>senderCountry</td><td>string | null</td><td>—</td><td>—</td><td>Sender ISO country code, e.g. 'UA'; unlocks partner PUDO (UPS) selection for allowed countries [PL, UA]</td></tr><tr><td>divisionId</td><td>number | null</td><td>—</td><td>—</td><td>Pre-select a specific division</td></tr><tr><td>divisionCategories</td><td>DivisionType[]</td><td>—</td><td>—</td><td>Filter by type; all shown if omitted</td></tr><tr><td>autoShow</td><td>boolean</td><td>—</td><td>false</td><td>Call show() automatically after init</td></tr><tr><td>mobileBreakpointPx</td><td>number</td><td>—</td><td>768</td><td>Fullscreen popup below this viewport width</td></tr><tr><td>onSelect</td><td>(division: DivisionItem) => void</td><td>—</td><td>—</td><td>Fires when user confirms a division</td></tr><tr><td>onReady</td><td>() => void</td><td>—</td><td>—</td><td>Fires when iframe is loaded and ready</td></tr><tr><td>onError</td><td>(error: Error) => void</td><td>—</td><td>—</td><td>Fires on runtime error inside iframe</td></tr><tr><td>onClose</td><td>(reason?) => void</td><td>—</td><td>—</td><td>Fires when popup is closed</td></tr></tbody></table>

### 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 and fires `onClose('manual_close')`.

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

Updates `city`, `country`, `senderCountry`, `divisionId`, `divisionCategories`, `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

<table><thead><tr><th width="124">VARIANT</th><th width="144">VIEWMODE</th><th>RESULT</th></tr></thead><tbody><tr><td>map</td><td>container</td><td>Google Maps embedded inline in your page</td></tr><tr><td>map</td><td>popup</td><td>Trigger button → click opens popup with Google Maps</td></tr><tr><td>widget</td><td>container</td><td>Division list with search embedded inline</td></tr><tr><td>widget</td><td>popup</td><td>Trigger button → click opens popup with division list</td></tr></tbody></table>

### onSelect callback — DivisionItem fields

Full object passed to your handler when user confirms a division

```
onSelect: (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
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://api-portal.novapost.com/methods/page-2/page-2-1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.