@majlxrd/inpost-geowidget-next

React InPost GeoWidget

A lightweight and simple React component for integrating the official InPost GeoWidget v5 into your React and Next.js applications.

This component handles the dynamic loading of the required InPost scripts and stylesheets, providing a clean and straightforward way to display the parcel locker map.

Features

• Easy Integration: Drop the component into your app, provide a token, and you're ready to go.
• Dynamic Script Loading: Automatically loads the InPost GeoWidget JavaScript and CSS files without needing to add them to your layout.js/ts.
• TypeScript Support: Written entirely in TypeScript, providing full type safety for all props.
• Event Callbacks: Easily handle events like point selection (onPointSelect) and API readiness (onApiReady).
• Next.js 13+ Ready: Fully compatible with the Next.js App Router (requires the "use client"; directive).
• Customizable: Supports all standard GeoWidget options like language, config, and sandbox mode.

Installation

You can install the package using npm or yarn.

Using npm:

npm install @majlxrd/inpost-geowidget-next

Using yarn:

yarn add @majlxrd/inpost-geowidget-next

Usage

Here's a basic example of how to use the InpostGeowidget component in a Next.js 13+ application.

// app/page.tsx
"use client"; // This is required for components with hooks and event listeners in Next.js App Router.

import React, {useState} from 'react';
import InpostGeowidget, {InpostGeowidgetProps} from '@majlxrd/inpost-geowidget-next';

export default function HomePage() {
    const [selectedPoint, setSelectedPoint] = useState<any>(null);

    const handlePointSelect: InpostGeowidgetProps['onPointSelect'] = (point) => {
        console.log("Parcel locker selected:", point);
        setSelectedPoint(point);
    };

    const handleApiReady: InpostGeowidgetProps['onApiReady'] = (api) => {
        console.log("GeoWidget API is ready:", api);
        // You can now use the API, for example: api.openMap();
    };

    return (
        <main style={{padding: '2rem', textAlign: 'center'}}>
            <h1>Select an InPost Parcel Locker</h1>

            {/* The container MUST have a defined width and height for the widget to be visible. */}
            <div style={{width: '800px', height: '500px', margin: '2rem auto', border: '1px solid #ccc'}}>
                <InpostGeowidget
                    token="YOUR_INPOST_API_TOKEN"
                    sandbox={true} // Use true for testing, false for production
                    onPointSelect={handlePointSelect}
                    onApiReady={handleApiReady}
                    language="en"
                />
            </div>

            {selectedPoint && (
                <div style={{marginTop: '1rem', padding: '1rem', backgroundColor: '#f0f0f0'}}>
                    <h3>Selected Point Details:</h3>
                    <p><strong>Name:</strong> {selectedPoint.name}</p>
                    <p>
                        <strong>Address:</strong> {`${selectedPoint.address_details.street}, ${selectedPoint.address_details.city}`}
                    </p>
                </div>
            )}
        </main>
    );
}

Props

The InpostGeowidget component accepts the following props:

Prop Name	Type	Default	Description
token	string	(none)	Required. The unique authentication token to initialize the widget.
identifier	string	GeoWidgetHost	A unique ID for the widget instance, useful if you have multiple widgets on the same page.
sandbox	boolean	false	If true, the widget will use the sandbox (test) environment.
language	'pl', 'en', 'cz', 'sk', 'hu', 'it', 'es', 'fr'	'pl'	The display language for the widget.
config	string	parcelCollect	The widget's configuration mode, which determines its behavior (e.g., parcelCollect, parcelSend).
onPointSelect	(point: any) => void	undefined	Callback function invoked when a user selects a point on the map.
onApiReady	(api: any) => void	undefined	Callback function invoked when the widget's JavaScript API is ready for programmatic control.

Handling Events

onPointSelect This callback receives the selected point object as its only argument. You can use this to store the user's choice in your application's state.

const handleSelection = (point) => {
  console.log('User selected:', point.name, point.address_details);
  // Update your form state here
};

<InpostGeowidget token="..." onPointSelect={handleSelection} />

onApiReady This callback receives the widget's API object, which you can use to control the widget programmatically.

const [widgetApi, setWidgetApi] = useState(null);

// You can now call methods like widgetApi.openMap() from a button click
<button onClick={() => widgetApi?.openMap()}>Open Map</button>

<InpostGeowidget token="..." onApiReady={setWidgetApi} />

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request if you have any improvements or bug fixes.

License

This project is licensed under the MIT License.