After saving the widget, the code snippet required for integration will appear in the editor interface. It consists of two parts: the script load and the widget's unique HTML tag.

<script src="https://www.pickupselect.com/map-widget.js"></script>

<pickup-select
   id="pickupWidget"
   widget-key="wk_1234567890abcdef"
   api-key="pk_1234567890abcdef"
         >
</pickup-select>

What to do: Copy the above code to the part of your website where you want to display the map selector (usually in the checkout process, in the shipping methods step).

Event handling, point selection

When the user selects a pickup point, the widget triggers a unique onSelectPickupPoint event. You can handle this event with the following JavaScript code:

                
<script>
  const widget = document.getElementById('pickupWidget');
  widget.addEventListener('onSelectPickupPoint', (e) => {
      console.log(e.detail.selectedPickupPoint);
  });
</script>
                
            

Tip: If the user already has a selected point, pass its ID in the appropriate attribute when initializing the widget so that the map opens immediately focused on that point. To do this, use the selected-point-id attribute, whose value is the ID of the selected point.

<script src="https://www.pickupselect.com/map-widget.js"></script>

<pickup-select
   id="pickupWidget"
   widget-key="wk_1234567890abcdef"
   api-key="pk_1234567890abcdef"
   selected-point-id="999"
         >
</pickup-select>

Starting from the shipping address: If there is no selected point yet but you already know the shopper's address, pass the country and the postal code so that the map opens at that postal code:

• selected-country-code: two-letter ISO country code (for example HU, PL). The widget opens with this country selected; if the country is not enabled for the widget, the widget's default country is used.
• selected-postal-code: postal code in that country. It only takes effect together with selected-country-code; if the postal code is not found, the map shows the points around the center of the country.

selected-point-id takes precedence: when it is set, the map opens at the selected point.

<script src="https://www.pickupselect.com/map-widget.js"></script>

<pickup-select
   id="pickupWidget"
   widget-key="wk_1234567890abcdef"
   api-key="pk_1234567890abcdef"
      selected-country-code="HU"
      selected-postal-code="1051"
   >
</pickup-select>

What the event contains

e.detail.selectedPickupPoint is a plain object (safe to JSON.stringify), or null when the shopper clears the selection. Store at least id and external_id with the order.

• id: the PickupSelect point ID (use it for selected-point-id later)
• external_id: the carrier's own point ID, the one carrier APIs and label printing expect
• name, street, city, postal_code, country_code: the address to show in the order
• group_code: the carrier's point type (for example locker or shop)
• lat, lng, distance (km from the searched location), opening_hours (time ranges per weekday, Monday first; depending on the carrier a list or an object keyed 1–7), icon_url

Using it with a framework

The widget is a standard web component, so no package is needed: load the script once and render the <pickup-select> tag. The only framework-specific part is attaching the event listener. The snippets below use the example keys from above; use your own from the widget editor.

React

Add the script tag to your index.html, then:

import { useEffect, useRef } from 'react';

export function PickupPointSelector({ onSelect }) {
  const ref = useRef(null);

  useEffect(() => {
    const el = ref.current;
    const handler = (e) => onSelect(e.detail.selectedPickupPoint);
    el.addEventListener('onSelectPickupPoint', handler);
    return () => el.removeEventListener('onSelectPickupPoint', handler);
  }, [onSelect]);

  return (
    <div style={{ height: 600 }}>
      <pickup-select
        ref={ref}
        id="pickupWidget"
        widget-key="wk_1234567890abcdef"
        api-key="pk_1234567890abcdef"
      />
    </div>
  );
}

With TypeScript, declare the tag once (for example in src/pickup-select.d.ts):

import 'react';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'pickup-select': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        'widget-key': string;
        'api-key': string;
        'selected-point-id'?: number;
        'selected-country-code'?: string;
        'selected-postal-code'?: string;
      };
    }
  }
}

Next.js (App Router)

The widget runs in the browser only, so render it from a client component and load the script with next/script:

'use client';

import Script from 'next/script';
import { useEffect, useRef } from 'react';

export default function PickupPointSelector({ onSelect }) {
  const ref = useRef(null);

  useEffect(() => {
    const el = ref.current;
    const handler = (e) => onSelect(e.detail.selectedPickupPoint);
    el.addEventListener('onSelectPickupPoint', handler);
    return () => el.removeEventListener('onSelectPickupPoint', handler);
  }, [onSelect]);

  return (
    <>
      <Script src="https://pickupselect.com/map-widget.js" strategy="afterInteractive" />
      <div style={{ height: 600 }}>
        <pickup-select
          ref={ref}
          id="pickupWidget"
          widget-key="wk_1234567890abcdef"
          api-key="pk_1234567890abcdef"
        />
      </div>
    </>
  );
}

Vue 3

Add the script tag to your index.html, and tell the Vue compiler that pickup-select is a custom element (in vite.config.js):

vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === 'pickup-select',
    },
  },
})

<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';

const emit = defineEmits(['select']);
const widget = ref(null);
const handler = (e) => emit('select', e.detail.selectedPickupPoint);

onMounted(() => widget.value.addEventListener('onSelectPickupPoint', handler));
onBeforeUnmount(() => widget.value.removeEventListener('onSelectPickupPoint', handler));
</script>

<template>
  <div style="height: 600px">
    <pickup-select
      ref="widget"
      id="pickupWidget"
      widget-key="wk_1234567890abcdef"
      api-key="pk_1234567890abcdef"
    />
  </div>
</template>

Testing locally: the script always loads the widget from pickupselect.com, so it also works on localhost. Add your local address (for example http://localhost:3000) to the widget's Allowed Origins if you have set any.