Map SDK Installation and Usage

Installation

npm install @road-labs/map-sdk

Usage

After installing the package, you need to:

1. Import the component:

import { App } from "@road-labs/map-sdk";

2. Import the CSS stylesheet (required for proper styling):

import "@road-labs/map-sdk/dist/index.css";

Props

The App component accepts the following props:

| Field Name | Required | Version(s) | Context | Description | Default Value | | :-------------------------- | :------- | :--------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | height | Yes | Both | Both | Height of the map container in pixels. | - | | gestureHandling | Yes | Both | Both | Google Maps SDK parameter controlling how gestures (scroll, pinch, etc.) interact with the map. Allowed values: greedy, cooperative, none, auto. We suggest a default value of greedy. | - | | authorization | Yes | v2 | Both | The public authorization key to search for locations. | - | | context | Yes | Both | Both | Context type for the map. Allowed values: "cpo" or "msp". | - | | version | No | Both | Both | Which version of the map SDK do you wish to use. | v1 | | language | No | Both | Both | Language of the widget. Supported values: en. If nothing is set, it will use the browser language. | Browser language | | position {lat,lng} | No | Both | Both | Initial latitude/longitude to center the map on load. If not provided, defaults to visitor's IP-based location. | Visitor IP location | | useBrowserLocation | No | Both | Both | Use the browser location to center the map. | false | | enableZoomControls | No | Both | Both | Whether to display zoom (+/-) controls in the bottom-right corner. | false | | enableSidebar | No | Both | Both | Enables sidebar with location/cluster information when selected. | false | | enablePlacesSearch | No | Both | Both | Enables address search input at the top of the map. | true | | locationId | No | Both | Both | If provided, the map will zoom to the given locationId and open its sidebar (if enabled). Overrides position. | - | | locationBaseUrl | No | Both | Both | Base URL for location data. | - | | apiRoot | No | Both | Both | The root URL of the API. | - | | googleApiKey | No | Both | Both | Google Maps API key. If not provided, you can set your own Google API key. | - | | theming {} | No | Both | Both | Controls widget look and feel with keys: brandColor, backgroundColor, textColor, borderColor, fontFamily. Accepts HEX values (e.g. #ff3d00). If backgroundColor is provided without shadowRoot, a shadow root will be automatically created. | - | | shadowRoot | No | Both | Both | Shadow DOM root element. If not provided but theming.backgroundColor is set, a shadow root will be automatically created. See Theming with Shadow DOM section below. | - | | sdkRoot | No | Both | Both | Root URL for SDK CSS file. Required when using automatic shadow root creation with theming (when theming is provided without shadowRoot). The stylesheet will be loaded from sdkRoot + "/styles.css". | - | | limitToLocationIds | No | v2 | Both | Constrains the map to only show the locations with the configured IDs. Provided that they exist in the dataset. | All available locations | | preferredOperators | No | v2 | Both | Array of operator names. Ensures that the selected operators appear at the top of the operator selector dropdown. | [] | | operators | No | v2 | Both | Array of available operators. | - | | publishingMode | No | v2 | Both | Array of available publishing modes. Allowed values: "PUBLISHING_MODE_PUBLIC", "PUBLISHING_MODE_PRIVATE". | - | | showNoAdditionalFeeFilter | No | v2 | msp | Used to configure whether we enable the user to filter out stations that come with additional fees. | false | | showPublishingModeFilter | No | v2 | cpo | Used to configure whether we enable the user to filter out public or private stations. | false | | showOperatorOnly | No | v2 | both | String value representing the operator name. Include a quick filter option to find a specific operator. | - | | onMarkerClicked | No | Both | Both | Callback function that is called when a marker is clicked. Receives an object with ids property containing the location IDs. | - |

Example

Here's a complete example showing the SDK with automatic shadow root creation and theming:

import React from 'react';
import { App } from '@road-labs/map-sdk';
import '@road-labs/map-sdk/dist/index.css';

function MyMap() {
  return (
    <App
      height={600}
      authorization="your-authorization-key"
      context="cpo"
      gestureHandling="greedy"
      apiRoot="https://api.road.io"
      googleApiKey="your-google-maps-api-key"
      language="en"
      sdkRoot="https://mapsdk.road.io"
      preferredOperators={["operator1", "operator2"]}
      onMarkerClicked={({ ids }) => {
        console.log('Marker clicked:', ids);
      }}
    />
  );
}

Note: The height, gestureHandling, authorization, and context props are required. All other props are optional.

Theming with Shadow DOM

The theming options (brandColor, backgroundColor, textColor, borderColor, fontFamily) require the SDK to be rendered within a Shadow DOM context. This provides style encapsulation, preventing the map's styles from conflicting with your application's styles and vice versa.

N.B. If you provide theming options without a shadowRoot prop, the SDK will automatically create a shadow root for you.

Important Notes

1. CSS Import:

   • With automatic shadow root: The SDK loads the stylesheet from sdkRoot + "/styles.css".
   • With manual shadow root (or without theming options): You need to link the stylesheet directly in the shadow root (as shown above), or use a bundler that supports injecting styles into shadow DOM.

2. Container Height: Make sure your container element and the react root div have explicit heights set, otherwise the map may not display correctly.

Without Shadow DOM

If you don't need custom theming, you can use the SDK without Shadow DOM (simply omit both theming and shadowRoot props). The SDK will use its default theme values in this case.

// Simple usage without shadow DOM (default theme only)
<App
  height={600}
  authorization="your-authorization-key"
  context="cpo"
  gestureHandling="greedy"
  apiRoot="https://api.road.io"
  // ... other props
/>