New PPL 2.0 Map Widget

We are launching a completely redesigned map widget for selecting pickup points (PPL ParcelBoxes, AlzaBoxes, and ParcelShops). For e-commerce developers, this means three things: the end of conflicts with your website’s global CSS, integration via a single HTML tag without any framework dependency, and significantly faster performance in the browser.

Migration notice: If you are using a customized version of the original 1.x widget on your website, you must migrate to version 2.0 no later than August 31, 2026.

Full technical documentation and API reference can be found on the official PPL Widget 2.0 documentation portal.

Architectural shift: version 1.x vs. Widget 2.0

The previous generation of the widget injected its code into the global page scope and required manually loading an external CSS file into the document head. Version 2.0 changes this approach from the ground up.

1. Isolation using Shadow DOM

The biggest issue with version 1.x was style leakage. Developers had to override styles using specific selectors (e.g. #ppl-parcelshop-map .accordion-map--select { display: none !important; }), which often broke layouts depending on the CSS framework used (Tailwind, Bootstrap).

Widget 2.0 is built as a Web Component using Shadow DOM. The entire widget lives in its own isolated DOM tree:

➡️ Global styles from your e-shop do not affect the widget.

➡️ Internal widget styles do not affect your cart layout.

Important for migration: due to this isolation, old CSS overrides targeting #ppl-parcelshop-map will no longer work. If you previously customized the widget via CSS in v1.x, this is the main reason migration is required. In version 2.0, appearance and behavior are configured via API key settings in the admin panel, not by external CSS overrides.

2. Mandatory API key authentication

In the original version, it was enough to place a universal container <div id="ppl-parcelshop-map"> on the page. Version 2.0 introduces API key-based access management.

Benefits:

➡️ higher security and endpoint stability,

➡️ widget configuration (allowed countries, place types, language) tied directly to your key,

➡️ better visibility of map service usage for your e-shop.

⚠️ Before integration: You must first generate an API key and activate it in the administration panel. Then make sure to set allowed domains — the widget will only load on domains explicitly assigned to your key.

3. Framework independence — React, Vue, and plain HTML

No more complex initialization inside component lifecycle methods. Widget 2.0 is a standard Web Component with React bundled inside — meaning your website does not need React (or any other framework).

It works the same way in all environments:

➡️ Pure HTML / Vanilla JS — just insert one tag.

➡️ React — use the same tag in JSX and handle events with standard addEventListener.

➡️ Vue, Angular and others — Web Components are natively supported by all modern frameworks.

No npm package or server SDK is required — integration is always a single HTML element.

Quick start: how integration works in practice

Loading is asynchronous and non-blocking — no synchronous <link rel="stylesheet"> in the <head> like before. Just load the script and insert the component with your API key and configuration.

Static HTML / Vanilla JS integration

<!-- Loader automatically loads all required widget files -->

<script src="https://www.ppl.cz/accesspointwidget/loader.js" async></script>

<ppl-access-point-widget
    api-key="YOUR_API_KEY"
></ppl-access-point-widget>

➡️ api-key (required) — your API key issued by PPL.

➡️ config (optional) — JSON settings: mode, language, default country, inline vs modal display.

Handling pickup point selection (Event Handling)

The widget emits selection via a custom event sent directly on the element (not on document). The returned object in event.detail is structured and typed — it contains precise geolocation data, place type (ParcelShop / ParcelBox / AlzaBox), and payment information.

JavaScript

<script>
const widget = document.querySelector("ppl-access-point-widget");

widget.addEventListener("ppl-accesspointwidget-select", (event) => {
  const selectedPoint = event.detail;
  console.log("Selected pickup point ID:", selectedPoint.id);
  console.log("Full data:", selectedPoint);
});
</script>

In addition to selection, the widget emits other events you can hook into:

Event	When it occurs
ppl-accesspointwidget-select	User selects a pickup point
ppl-accesspointwidget-close	User closes the widget
ppl-accesspointwidget-error	An error occurs (e.g. invalid API key)
ppl-accesspointwidget-ready	Widget is initialized and ready

New features and user improvements

Filtering pickup point types

Users can quickly narrow down results between PPL Boxes, partner AlzaBoxes, and physical PPL Shops, and also filter by additional criteria (opening hours, card payment, parcel size, accessibility). Filters are optimized so that even when multiple conditions change at once, only one server request is made, ensuring fast and efficient performance.

Favorites and history inside the widget

A new feature allows saving favorite locations (heart icon) and storing recently selected locations in the browser (Local Storage). This makes repeat purchases faster as users can instantly reuse previous locations.

Improved mobile behavior

The widget adapts to the space it is placed in. If the parent container does not have a fixed height, the widget will intelligently expand to ensure comfortable use in mobile checkout flows, improving conversion rates.

Search and geolocation

Address search with autocomplete and the ability to find the nearest pickup points based on the user’s current location are fully supported.

Migration timeline

➡️ Widget v1.x (Legacy): no longer actively developed. Standard integration continues to work, but heavily customized widgets (custom CSS overrides, non-standard e-commerce setups) must migrate to version 2.0.

➡️ August 31, 2026: final deadline for migrating all customized widgets to version 2.0. After this date, legacy CSS overrides and integrations without API keys will no longer be compatible with the new pickup point network.

Full reference documentation — parameters, response schema, and interactive examples — is available on the official PPL Widget 2.0 documentation portal