> 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/internal-solutions/ua/division-selection-widget.md).

# Віджет вибору відділення

Додайте віджет вибору відділення або поштомата на будь-яку вебсторінку за лічені хвилини — з Google Maps, фільтрами та підтримкою TypeScript.

<p align="center"><a href="https://integration-widget.novapost.com/" class="button primary">Відкрити Playground</a><a href="https://api-portal.novapost.com/internal-solutions/ua/vidzhet-viboru-viddilennya#shvidkii-start-umd-cherez-less-than-script-greater-than" class="button secondary">Швидкий Старт</a><a href="https://api-portal.novapost.com/internal-solutions/ua/vidzhet-viboru-viddilennya#konfiguraciya-widgetconfig" class="button secondary">Довідник API</a><a href="https://api-portal.novapost.com/internal-solutions/ua/vidzhet-viboru-viddilennya/changelog" class="button secondary">Changelog</a></p>

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><h4>Два варіанти відображення</h4><p>Режим карти (Google Maps) або режим віджета (список із пошуком і фільтрами). Обидва варіанти підтримують однакові параметри та події.</p></td></tr><tr><td><h4>Лінива ініціалізація iframe</h4><p><code>&#x3C;iframe></code> створюється лише під час першого виклику <code>show()</code> — до цього моменту він не створюється.</p></td></tr><tr><td><h4>Без потреби в API-ключі</h4><p>Усі запити до Nova Post API виконуються через проксі-сервер.</p></td></tr></tbody></table>

### Швидкий старт — UMD через \<script>

Працює на будь-якій HTML-сторінці без потреби в етапі збірки.

```
<!-- 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>
```

### Конфігурація — WidgetConfig

<table data-search="false"><thead><tr><th width="181">ПАРАМЕТР</th><th width="147">ТИП</th><th width="92">ОБОВ.</th><th width="122">ЗА ЗАМОВЧ.</th><th>ОПИС</th></tr></thead><tbody><tr><td><code>container</code></td><td><code>string</code> | <code>HTMLElement</code></td><td><code>Yes</code></td><td>—</td><td>CSS-селектор або DOM-елемент для вбудовування віджета</td></tr><tr><td><code>locale</code></td><td><code>'uk'</code> | <code>'en'</code> | <code>'de'</code> | <code>'cs'</code></td><td>—</td><td><code>'en'</code></td><td>Мова інтерфейсу</td></tr><tr><td><code>variant</code></td><td><code>'map'</code> | <code>'widget'</code></td><td>—</td><td><code>'map'</code></td><td><p>Режим відображення: </p><ul><li><code>map</code> — карта</li><li><code>widget</code> — пошук, список відділень і карта</li></ul></td></tr><tr><td><code>viewMode</code></td><td><code>'container'</code> | <code>'popup'</code></td><td>—</td><td><code>'container'</code></td><td>Вбудоване відображення або спливаюче вікно</td></tr><tr><td><code>shipmentRole</code></td><td><code>'recipient'</code> | <code>'sender'</code></td><td>—</td><td><code>'recipient'</code></td><td>Визначає, чи використовується віджет для вибору відділення відправника або отримувача</td></tr><tr><td><code>country</code></td><td><code>string</code> | <code>null</code></td><td>—</td><td>—</td><td>Код країни за стандартом ISO, наприклад <code>'UA'</code></td></tr><tr><td><code>city</code></td><td><code>string</code> | <code>null</code></td><td>—</td><td>—</td><td>Назва міста для попереднього вибору</td></tr><tr><td><code>theme</code></td><td><code>'light'</code> | <code>'dark'</code></td><td>—</td><td><code>'light'</code></td><td>Тема інтерфейсу користувача</td></tr><tr><td><code>senderCountry</code></td><td><code>string</code> | <code>null</code></td><td>—</td><td>—</td><td>ISO-код країни відправника, наприклад <code>'UA'</code>; відкриває можливість вибору партнерських пунктів PUDO (UPS) для підтримуваних країн [PL, UA]</td></tr><tr><td><code>divisionId</code></td><td><code>number</code> | <code>null</code></td><td>—</td><td>—</td><td>Попередній вибір конкретного відділення</td></tr><tr><td><code>divisionCategories</code></td><td><code>DivisionType[]</code></td><td>—</td><td>—</td><td>Фільтр за типом відділення; якщо параметр не вказано, відображаються всі типи</td></tr><tr><td><code>autoShow</code></td><td><code>boolean</code></td><td>—</td><td><code>false</code></td><td>Автоматично викликає <strong>show()</strong> після ініціалізації; працює лише при <code>'viewMode'</code> = <code>'container'</code></td></tr><tr><td><code>mobileBreakpointPx</code></td><td><code>number</code></td><td>—</td><td><code>768</code></td><td>Нижче цієї ширини області перегляду спливаюче вікно відкривається в повноекранному режимі</td></tr><tr><td><code>onSelect</code></td><td><code>(division: DivisionItem) => void</code></td><td>—</td><td>—</td><td>Викликається, коли користувач підтверджує вибір відділення</td></tr><tr><td><code>onClear</code></td><td><code>() => void</code></td><td>—</td><td>—</td><td>Викликається після очищення вибраного відділення</td></tr><tr><td><code>onReady</code></td><td><code>() => void</code></td><td>—</td><td>—</td><td>Викликається після завантаження iframe та його готовності до роботи</td></tr><tr><td><code>onError</code></td><td><code>(error: Error) => void</code></td><td>—</td><td>—</td><td>Викликається у разі виникнення помилки виконання всередині iframe</td></tr><tr><td><code>onClose</code></td><td><code>(reason?) => void</code></td><td>—</td><td>—</td><td>Викликається після закриття спливаючого вікна</td></tr></tbody></table>

### API-методи

**widget.show()** Відображає віджет. Під час першого виклику створюється iframe (лінива ініціалізація).

У режимі `container` встановлює для iframe значення `display: block`. \
У режимі `popup` відкриває спливаюче вікно. \
Під час кожного виклику (в обох режимах), після готовності віджета, карта автоматично центрується на раніше вибраному відділенні.

**widget.hide()** Приховує віджет без видалення iframe.

У режимі `container` встановлює значення `display: none`. \
У режимі `popup` — закриває спливаюче вікно. \
Прямий виклик `hide()` не викликає `onClose`; цей callback викликається лише тоді, коли закриття ініціює сам віджет (натискання клавіші Escape, клік по фону спливаючого вікна або після вибору відділення), після чого `hide()` викликається внутрішньо.

**widget.updateParams(params)** Оновлює параметри без повторного створення iframe.

Оновлює параметри `city`, `country`, `senderCountry`, `divisionId`, `divisionCategories`, `theme` та `locale`.\
Якщо метод викликати до події `onReady`, зміни буде поставлено в чергу та автоматично застосовано після готовності віджета.

**widget.destroy()** Видаляє iframe, елементи спливаючого вікна та всі обробники подій.

Викликайте метод під час зміни маршруту в SPA або під час демонтування компонента (Vue `onUnmounted`, React `useEffect` cleanup).

### Варіанти та Режими Відображення

<table><thead><tr><th width="124">ВАРІАНТ</th><th width="149">РЕЖИМ ВІДОБРАЖЕНЯ</th><th>РЕЗУЛЬТАТ</th></tr></thead><tbody><tr><td><code>map</code></td><td><code>container</code></td><td>Google Maps, вбудована безпосередньо на сторінку</td></tr><tr><td><code>map</code></td><td><code>popup</code></td><td>Кнопка відкриття → після натискання відкривається спливаюче вікно з Google Maps</td></tr><tr><td><code>widget</code></td><td><code>container</code></td><td>Пошук відділень зі списком і картою, вбудованими безпосередньо на сторінку</td></tr><tr><td><code>widget</code></td><td><code>popup</code></td><td>Кнопка відкриття → після натискання відкривається спливаюче вікно з пошуком відділень, списком і картою</td></tr></tbody></table>

### onSelect callback — поля DivisionItem

Повний об'єкт, який передається до обробника після підтвердження користувачем вибору відділення:

* `onSelect` отримує об'єкт відділення.
* `onClear` очищає стан застосунку.

```
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
}
```


---

# 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/internal-solutions/ua/division-selection-widget.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.