@yarrow-uz/yarrow-map-web-sdk

v1.0.45

Published

3 days ago

Yarrow Map Web SDK for embedding interactive maps and routing in web apps.

Downloads

625

0High
0Medium
0Low

abdukahhars

Yarrow Map Web SDK Documentation

This document provides a comprehensive guide to using the Yarrow Map Web SDK for embedding and interacting with Yarrow maps in your web application.

Getting Started

Installation

First, add the Yarrow Map Web SDK to your project using your preferred package manager.

npm install @yarrow-uz/yarrow-map-web-sdk

Local Development

When running your application locally, serve it on port 8080 to avoid CORS issues with the map API. Running on any other port will cause CORS errors.

Initialization

To get started, you need to create an instance of YarrowMap. This requires a configuration object that specifies the container element, center coordinates, and zoom level.

Important - Coordinate Format: This SDK uses [longitude, latitude] format for map configuration (matching MapLibre GL convention), but [latitude, longitude] format for all other methods like routing and markers (matching common usage).

import { YarrowMap } from '@yarrow-uz/yarrow-map-web-sdk';

// Configuration for the map
const mapConfig = {
  container: 'map', // ID of the div element to render the map in
  center: [69.2401, 41.2995], // Initial center [longitude, latitude] - MapLibre convention
  zoom: 12, // Initial zoom level
};

// Create a new map instance
const yarrowMap = new YarrowMap(mapConfig);

// Initialize the map
yarrowMap.init().then(() => {
  console.log('Map initialized successfully!');
});

Note: By default, all MapLibre controls (zoom, navigation, attribution) are automatically removed during initialization. Use MapLibre's addControl() method if you need to add specific controls.

Configuration Options

The YarrowMapConfig class accepts a single configuration object:

const mapConfig = new YarrowMapConfig({
  container,    // string | HTMLElement
  center,       // [number, number] - [lng, lat]
  apiKey,       // string - Required, get from https://dashboard.yarrow.uz/
  zoom,         // number (default: 10)
  minZoom,      // number (default: 0)
  maxZoom,      // number (default: 19)
  theme,        // 'light' | 'dark' (default: 'light')
  cache,        // { enabled?: boolean, lifespanDays?: number }
  brandBadgePosition, // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
  controls      // { enabled?: boolean, position?: 'left'|'left-top'|'left-bottom'|'right'|'right-top'|'right-bottom', zoom?: boolean, compass?: boolean }
});

Example with all options:

import { YarrowMap, YarrowMapConfig } from '@yarrow-uz/yarrow-map-web-sdk';

const mapConfig = new YarrowMapConfig({
  container: 'map',
  center: [69.2401, 41.2995],
  zoom: 12,
  minZoom: 5,
  maxZoom: 18,
  apiKey: 'YOUR_API_KEY',   // Required - get from https://dashboard.yarrow.uz/
  theme: 'dark',
  cache: {
    enabled: true,         // Enable local persistent cache (default: false)
    lifespanDays: 30       // Cache lifespan in days (default: 30)
  },
  brandBadgePosition: 'top-right',
  controls: {
    enabled: true,         // Yarrow controls are OFF by default
    position: 'right-bottom', // Optional placement: left/left-top/left-bottom/right/right-top/right-bottom
    zoom: true,            // Optional
    compass: true          // Optional
  },
});

const yarrowMap = new YarrowMap(mapConfig);
yarrowMap.init().then(() => {
  console.log('Map initialized successfully!');
});

When controls and the brand badge are placed in the same corner (for example right-bottom with brandBadgePosition: 'bottom-right'), the SDK automatically adds spacing so they do not overlap.

React Usage

React APIs are exported from the @yarrow-uz/yarrow-map-web-sdk/react subpath.

import { YarrowMapView } from '@yarrow-uz/yarrow-map-web-sdk/react';

export const MapScreen = () => {
  return (
    <YarrowMapView
      config={{
        center: [69.2401, 41.2995],
        zoom: 12,
        apiKey: 'YOUR_API_KEY',   // Required - get from https://dashboard.yarrow.uz/
        brandBadgePosition: 'bottom-left',
      }}
      style={{ width: '100%', height: '600px' }}
    />
  );
};

You can also use the hook for custom composition:

import { useYarrowMap } from '@yarrow-uz/yarrow-map-web-sdk/react';

export const MapScreen = () => {
  const { containerRef, isReady, error } = useYarrowMap({
    config: {
      center: [69.2401, 41.2995],
      zoom: 12,
      brandBadgePosition: 'bottom-right',
    },
  });

  return (
    <div>
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
      {isReady && <p>Map ready</p>}
      {error && <p>Failed to initialize map</p>}
    </div>
  );
};

SSR note: The React integration initializes the map only on the client side.

Basic Map Manipulation

Changing the Map Style

You can change the map's visual style. The available styles are satellite, hybrid, and the default map style.

The map supports up to 85-degree pitch for 3D perspective views.

// Switch to satellite view
yarrowMap.changeStyles('satellite');

// Switch to hybrid view (satellite with labels)
yarrowMap.changeStyles('hybrid');

// Switch back to the default map style
yarrowMap.changeStyles();

Changing the Map Theme

You can set the initial theme in the configuration or switch between light and dark themes dynamically after initialization.

Setting initial theme:

// Initialize with dark theme
const mapConfig = new YarrowMapConfig({
  container: 'map',
  center: [69.2401, 41.2995],
  zoom: 12,
  minZoom: 5,
  maxZoom: 18,
  apiKey: 'YOUR_API_KEY',   // Required - get from https://dashboard.yarrow.uz/
  theme: 'dark', // Set initial theme to dark
});

Switching theme dynamically:

// Switch to dark mode
await yarrowMap.changeTheme('dark');

// Switch to light mode (default)
await yarrowMap.changeTheme('light');

Features:

Automatically re-fetches appropriate styles from the server
Updates all map layers to match the theme
Preserves custom icons and markers
Seamless theme transition

Changing Brand Badge Position

You can set the initial badge position in config or change it dynamically after map initialization.

// Move badge to the top-right corner
yarrowMap.changeBrandBadgePosition('top-right');

// Other values: 'top-left' | 'bottom-left' | 'bottom-right'

Moving the Map View

You can programmatically move the map to a new location or fit it to a specific geographic area.

Zooming to a specific point:

// Fly to a new location with a specific zoom level
yarrowMap.zoomTo(41.3111, 69.2797, 15); // Latitude, Longitude, Zoom Level

Fitting the map to a set of features:

This is useful when you want to display a set of points, lines, or polygons and ensure they are all visible.

const geojsonData = {
  type: 'FeatureCollection',
  features: [
    // Your GeoJSON features here
  ],
};

yarrowMap.fitBounds(geojsonData);

Changing Background Color

You can change the background color of the map programmatically:

// Change the map background to a custom color
yarrowMap.changeBackgroundColor('#f0f0f0'); // Light gray background

Note: This method waits for the map style to be fully loaded before applying the background color change.

Handling Events

You can listen for various user interactions with the map.

Listen for Map Movement

Execute a callback function whenever the map finishes moving.

yarrowMap.onMoveEnd((lat, lng, zoom) => {
  console.log(`Map moved to: ${lat}, ${lng} with zoom: ${zoom}`);
});

Listen for Map Clicks

Execute a callback when the user clicks on the map.

yarrowMap.onMapClick((lat, lng) => {
  console.log(`Map clicked at: ${lat}, ${lng}`);
});

Listen for Clicks on POIs or Buildings

You can add click listeners to specific groups of features on the map, like points of interest (POIs) or buildings.

// Listen for clicks on POIs
yarrowMap.onIconClick('pois', (lat, lng, properties) => {
  console.log('POI clicked:', properties);
});

// Listen for clicks on buildings
yarrowMap.onIconClick('buildings', (lat, lng, properties) => {
  console.log('Building clicked:', properties);
});

// Note: onLayerClick is an alias for onIconClick (they are the same method)
yarrowMap.onLayerClick('pois', (lat, lng, properties) => {
  console.log('Same as onIconClick');
});

Working with Layers and Data

Adding a GeoJSON Layer

You can add custom data to the map in the form of a GeoJSON layer. This is useful for displaying points, lines, or polygons.

const myData = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [69.2797, 41.3111],
      },
      properties: {
        name: 'My Point',
      },
    },
  ],
};

yarrowMap.addLayer(
  'my-custom-layer', // A unique name for the layer
  'circle', // The type of layer (e.g., 'circle', 'line', 'fill', 'symbol')
  myData,
  {
    'circle-radius': 10,
    'circle-color': '#ff0000',
  }
);

Advanced Layer Configuration

The addLayer method supports advanced configuration options for different layer types:

yarrowMap.addLayer(
  layerName,        // string - Unique identifier for the layer
  layerType,        // Layer type: 'symbol', 'fill', 'line', 'background', 'raster', 'circle', 'heatmap', 'fill-extrusion', 'hillshade'
  featureCollection, // GeoJSON FeatureCollection
  paint,            // Paint properties object
  layout,           // Layout properties object
  iconSettings,     // Icon configuration (width, height)
  options           // Optional: { sourceId?: string, filter?: LayerFilter }
);

Managing Sources Explicitly

yarrowMap.addSource('vehicles-source', vehicleFeatureCollection);
yarrowMap.updateSourceData('vehicles-source', nextVehicleFeatureCollection);

yarrowMap.addLayer(
  'active-vehicles',
  'circle',
  nextVehicleFeatureCollection,
  {
    'circle-radius': ['interpolate', ['linear'], ['zoom'], 10, 4, 16, 10],
    'circle-color': ['case', ['==', ['get', 'status'], 'active'], '#16a34a', '#9ca3af']
  },
  {},
  {},
  {
    sourceId: 'vehicles-source',
    filter: ['==', ['get', 'status'], 'active']
  }
);

Feature State and Rendered Queries

yarrowMap.setFeatureState(
  { source: 'vehicles-source', id: 101 },
  { selected: true }
);

const features = yarrowMap.queryRenderedFeatures({ layers: ['active-vehicles'] });

Symbol layer with custom icons:

const symbolData = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [69.2797, 41.3111] },
      properties: { name: 'Custom Point' }
    }
  ]
};

yarrowMap.addLayer(
  'custom-symbols',
  'symbol',
  symbolData,
  {
    'text-halo-color': '#ffffff',
    'text-halo-width': 2
  },
  {
    'icon-image': 'custom-icon',
    'icon-image-data': 'data:image/png;base64,...', // Base64 image data
    'icon-size': 0.8,
    'icon-allow-overlap': true,
    'text-field': ['get', 'name'],
    'text-offset': [0, 1.5],
    'text-anchor': 'top',
    'text-size': 14
  },
  {
    width: 32,  // Icon width
    height: 32  // Icon height
  }
);

Line layer with styling:

const lineData = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'LineString',
        coordinates: [[69.240, 41.299], [69.280, 41.311]]
      }
    }
  ]
};

yarrowMap.addLayer(
  'custom-line',
  'line',
  lineData,
  {
    'line-color': '#3b82f6',
    'line-width': 4,
    'line-opacity': 0.8
  },
  {
    'line-join': 'round',
    'line-cap': 'round'
  }
);

Adding and Removing Markers

You can add markers to the map to indicate specific locations.

// Add a simple red marker (default color)
const marker = yarrowMap.addMarker([41.3111, 69.2797]); // [latitude, longitude]

// Add a marker with all options
const customMarker = yarrowMap.addMarker([41.2995, 69.2401], {
  element: customElement,     // HTMLElement - Custom marker element
  color: '#0000ff',          // string - Marker color (default: '#FF0000')
  draggable: true,           // boolean - Allow dragging (default: false)
  anchor: 'bottom',          // Anchor position: 'center', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right'
  onClick: () => {           // function - Click event handler
    console.log('Marker clicked!');
  }
});

// Add a marker with custom HTML element
const customElement = document.createElement('div');
customElement.innerHTML = '📍';
customElement.style.fontSize = '24px';

const htmlMarker = yarrowMap.addMarker([41.3050, 69.2500], {
  element: customElement,
  anchor: 'center'
});

// Remove a marker
yarrowMap.removeMarker(marker);

Marker Options:

element: Custom HTML element for the marker
color: Marker color (default: '#FF0000')
draggable: Whether the marker can be dragged (default: false)
anchor: Anchor point of the marker relative to its coordinates
onClick: Click event handler function

Removing a Layer

You can remove a layer that you've previously added.

yarrowMap.removeLayer('my-custom-layer');

Routing

The SDK provides powerful routing capabilities.

Building and Displaying a Simple Route

Calculate and display a route between a start and end point.

const start = [41.2995, 69.2401]; // [latitude, longitude]
const end = [41.3111, 69.2797];
const profile = 'car'; // 'car', 'bicycle', or 'pedestrian'

yarrowMap.buildRouteWithLabels(start, end, profile).then(({ features, directions }) => {
  console.log('Route built:', features);
  console.log('Directions:', directions);
});

Building and Displaying a Multi-Stop Route

You can also create a route that passes through multiple waypoints.

const coordinates = [
  [41.2995, 69.2401], // Start [latitude, longitude]
  [41.3111, 69.2797], // Waypoint 1
  [41.325, 69.285],   // End
];
const profile = 'car';
const language = 'en'; // Optional: 'en', 'ru', etc. (default: 'ru')

yarrowMap.buildMultiSegmentRouteWithLabels(coordinates, profile, language).then(({ features, directions }) => {
  console.log('Multi-segment route built:', features);
  console.log('Directions:', directions);
});

Important Note: The SDK uses [latitude, longitude] format for all user-facing coordinate parameters (routing, markers, etc.), which is then internally converted to MapLibre's [longitude, latitude] format where needed.

Clearing Routes

To remove all route-related layers from the map:

yarrowMap.clearAllRoutes();

Rendering Multiple Routes

You can render multiple route features with automatic color coding:

// Array of route features (GeoJSON LineString features)
const routes = [
  {
    type: 'Feature',
    geometry: {
      type: 'LineString',
      coordinates: [[69.240, 41.299], [69.280, 41.311], [69.285, 41.315]]
    },
    properties: {
      duration: 15.5,
      distance: 2500
    }
  },
  {
    type: 'Feature',
    geometry: {
      type: 'LineString',
      coordinates: [[69.240, 41.299], [69.275, 41.308], [69.285, 41.315]]
    },
    properties: {
      duration: 18.2,
      distance: 3000
    }
  }
];

// Render routes with default styling
yarrowMap.renderRoutes(routes);

// Render routes with custom base layer name
yarrowMap.renderRoutes(routes, 'my-custom-routes');

Features:

Automatically assigns different colors to each route (#3b82f6, #10b981, #f59e0b, #ef4444, #8b5cf6)
Creates separate layers for each route ({baseLayerName}-0, {baseLayerName}-1, etc.)
Default base layer name is 'route' if not specified

Search

Highlighting Search Results

You can perform a search and display the results on the map. The search is performed around the current map center.

const query = 'Tashkent';

const clearHighlights = yarrowMap.highlightSearchResults(query, {
  zoomToResults: true, // Automatically zoom to fit the results
  onResultsUpdate: (results) => {
    console.log('Search results:', results);
  },
  onLoadingStateChange: (state) => {
    // state can be 'firstRender', 'rerender', or false
    console.log('Loading state:', state);
  }
});

// To remove the search results from the map later
// clearHighlights();

Advanced Search Configuration

The highlightSearchResults method accepts comprehensive configuration options:

const clearFunction = yarrowMap.highlightSearchResults('Tashkent', {
  layerName: 'my-search-layer',           // Custom layer name (default: 'search-results')
  iconImage: 'custom-search-icon',        // Custom icon image name
  highlightColor: '#ff6b35',              // Custom highlight color
  pulseAnimation: true,                   // Enable pulse animation (default: false)
  zoomToResults: false,                   // Auto-zoom to results (default: true)

  // Event handlers
  onIconClick: (lat, lng, properties) => {
    console.log('Search result clicked:', { lat, lng, properties });
    // Custom click behavior
  },

  onResultsUpdate: (results) => {
    console.log(`Found ${results.length} search results`);
    // Handle results update
  },

  onLoadingStateChange: (state) => {
    // state can be 'firstRender', 'rerender', or false
    if (state === 'firstRender') {
      console.log('Initial search loading...');
    } else if (state === 'rerender') {
      console.log('Updating search results...');
    } else {
      console.log('Search loading complete');
    }
  }
});

// Clear search results when done
clearFunction();

Configuration Options:

layerName: Custom name for the search results layer
iconImage: Custom icon image to use for search results
highlightColor: Color for highlighting search results
pulseAnimation: Enable/disable pulse animation effect
zoomToResults: Automatically zoom to fit search results
onIconClick: Callback when a search result icon is clicked
onResultsUpdate: Callback when search results are updated
onLoadingStateChange: Callback for loading state changes

Features:

Automatic re-searching when the map is moved (debounced)
Distance-based filtering (minimum 500m movement triggers re-search)
Automatic cleanup of previous search results
Real-time loading state tracking

Public Transport

Displaying Real-Time Bus Locations

You can display the real-time locations of buses on the map.

Show buses for a specific route:

const routeId = 'some-route-id';
yarrowMap.showBusRoute(routeId).then(clearBusRoute => {
  // To stop showing the bus route later
  // clearBusRoute();
});

Show all buses in the current map view:

If you don't provide a route_id, the map will show all buses within the visible area.

yarrowMap.showBusRoute().then(clearBusRoutes => {
  // To stop showing all bus routes
  // clearBusRoutes();
});

Clearing Bus Routes

The showBusRoute method returns a cleanup function that you can call to stop displaying bus locations and remove all related data:

// Store the cleanup function
const clearBuses = await yarrowMap.showBusRoute('route-123');

// Later, clear the bus route display
clearBuses();

What the cleanup function does:

Stops the automatic bus location updates (15-second interval)
Removes all bus markers from the map
Removes all route layers from the map
Removes map move event listeners
Clears internal caches (SVG cache, etc.)

Advanced Bus Route Features:

Smooth Bus Animation: Buses animate smoothly between positions, providing a realistic tracking experience:

16-second animation duration between position updates
Uses requestAnimationFrame for smooth 60fps interpolation
Each bus has independent position tracking (current vs target)
Animation starts automatically when buses are displayed

// Buses will animate smoothly between updates
const clearBuses = await yarrowMap.showBusRoute('route-123');

Performance Optimization:

Maximum 100 buses displayed at once (randomly selected if more exist)
5km radius filtering for general bus display (no route_id)
Automatic viewport filtering for subsequent updates
SVG icon caching for better performance
Debounced map movement updates (500ms delay)

Automatic Updates:

Bus locations update every 16 seconds
Map movement triggers bus location refresh (for general display)
Distance-based filtering (minimum 500m movement)

Utility Methods

Calculating Bounding Box

The SDK provides a utility method to calculate the bounding box of GeoJSON data:

const geojsonData = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [69.2797, 41.3111]
      }
    },
    {
      type: 'Feature',
      geometry: {
        type: 'LineString',
        coordinates: [[69.240, 41.299], [69.280, 41.311]]
      }
    }
  ]
};

const boundingBox = yarrowMap.getBoundingBox(geojsonData);
console.log(boundingBox);
// Output: { xMin: 69.240, xMax: 69.280, yMin: 41.299, yMax: 41.3111 }

Supported Geometry Types:

Point
LineString
Polygon

The bounding box contains:

xMin: Minimum longitude
xMax: Maximum longitude
yMin: Minimum latitude
yMax: Maximum latitude

Clearing Local Cache

You can clear cached map resources programmatically:

await yarrowMap.clearCache();

Advanced Features

Custom Icons and Styling

Loading Custom Icons: The SDK automatically loads and caches icons from the server during initialization. You can reference these icons by name in your layers:

// Icons are automatically available after init()
yarrowMap.init().then(() => {
  // Use server-provided icons
  yarrowMap.addLayer(
    'poi-layer',
    'symbol',
    poiData,
    {},
    {
      'icon-image': ['get', 'icon_img'], // References the icon from feature properties
      'icon-size': 0.7
    }
  );
});

Custom Icon Data: You can also provide custom icon data directly:

yarrowMap.addLayer(
  'custom-icons',
  'symbol',
  symbolData,
  {},
  {
    'icon-image': 'my-custom-icon',
    'icon-image-data': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
    'icon-size': 1.0
  },
  {
    width: 48,
    height: 48
  }
);

Performance Optimization

Layer Management:

Layers are automatically cleaned up when re-added with the same name
Sources are removed along with layers to prevent memory leaks
Icon images are cached to avoid redundant loading

Bus Route Optimization:

Maximum bus limit prevents performance issues with large datasets
Viewport-based filtering reduces unnecessary marker creation
SVG caching improves rendering performance
Debounced updates prevent excessive API calls

Memory Management:

Automatic cleanup of intervals and event listeners
Cache clearing on component destruction
Proper marker removal prevents memory leaks

Best Practices:

Always clean up resources:

const clearSearch = yarrowMap.highlightSearchResults('query');
const clearBuses = await yarrowMap.showBusRoute();

// When done, clean up
clearSearch();
clearBuses();

Reuse layer names for dynamic content:

// This will automatically clean up the previous layer
yarrowMap.addLayer('dynamic-layer', 'circle', newData, paint);

Use meaningful layer names:

// Good: descriptive and unique
yarrowMap.addLayer('user-locations-2024', 'symbol', userData);

// Avoid: generic names that might conflict
yarrowMap.addLayer('layer1', 'symbol', userData);

Handle errors appropriately:

try {
  await yarrowMap.buildRouteWithLabels(start, end, 'car');
} catch (error) {
  console.error('Route building failed:', error);
  // Handle error appropriately
}

API Reference

YarrowMapConfig Class

constructor(
  config: {
    container: string | HTMLElement;
    center: [number, number];
    zoom?: number;           // default: 10
    minZoom?: number;        // default: 0
    maxZoom?: number;        // default: 19
    theme?: 'light' | 'dark'; // default: 'light'
    cache?: {
      enabled?: boolean;      // default: false
      lifespanDays?: number;  // default: 30 (1 month)
    };
    brandBadgePosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
    controls?: {
      enabled?: boolean;      // default: false
      position?:
        | 'left'
        | 'left-top'
        | 'left-bottom'
        | 'right'
        | 'right-top'
        | 'right-bottom';
      zoom?: boolean;         // default: true
      compass?: boolean;      // default: true
    };
  }
)

YarrowMap Class Methods

| Method | Parameters | Return Type | Description | |--------|------------|-------------|-------------| | init() | None | Promise<void> | Initialize the map with styles and icons | | changeStyles(styleType?) | styleType?: 'satellite' \| 'hybrid' | Promise<any> | Change map style | | changeTheme(theme) | theme: 'light' \| 'dark' | Promise<any> | Switch between light and dark themes | | changeBrandBadgePosition(position) | position: 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | BrandBadgePosition | Change brand badge corner position at runtime | | zoomTo(lat, lng, zoom) | lat: number, lng: number, zoom: number | void | Fly to specific coordinates | | fitBounds(data) | data: GeoJSON | void | Fit map to show all features | | getBoundingBox(data) | data: GeoJSON | BoundingBox | Calculate bounding box of features | | onMoveEnd(callback) | callback: (lat, lng, zoom) => void | void | Listen for map movement end | | onMapClick(callback) | callback: (lat, lng) => void | void | Listen for map clicks | | onIconClick(layerGroup, callback) | layerGroup: 'pois' \| 'buildings', callback: Function | void | Listen for icon clicks | | onLayerClick(layerGroup, callback) | layerGroup: 'pois' \| 'buildings', callback: Function | void | Alias for onIconClick (same method) | | changeBackgroundColor(color) | color: string | void | Change map background color | | addSource() | sourceId, data | void | Add/replace a GeoJSON source | | updateSourceData() | sourceId, data | void | Update data for an existing GeoJSON source (or create it) | | addLayer() | layerName, layerType, featureCollection, paint?, layout?, iconSettings?, options? | void | Add a layer to the map (supports sourceId and filter) | | setFeatureState() | featureIdentifier, state | void | Set state for a specific feature | | queryRenderedFeatures() | geometryOrOptions?, options? | MapGeoJSONFeature[] | Query currently rendered features (supports { layers }) | | removeLayer(layerName) | layerName: string | void | Remove a layer from the map | | addMarker(coordinates, options?) | coordinates: [lat, lng], options?: MarkerOptions | Marker \| null | Add a marker to the map | | removeMarker(marker) | marker: Marker | void | Remove a marker from the map | | renderRoutes(routes, baseLayerName?) | routes: Feature[], baseLayerName?: string | void | Render multiple route features | | buildRouteWithLabels() | start: [lat, lng], end: [lat, lng], profile: string | Promise<RouteResult> | Build and display a route with labels | | buildMultiSegmentRouteWithLabels() | coordinates: [lat, lng][], profile: string, language?: string | Promise<RouteResult> | Build multi-segment route | | clearAllRoutes() | None | void | Clear all route layers and popups | | clearCache() | None | Promise<void> | Clear local persistent cache | | highlightSearchResults() | query: string, options?: SearchOptions | () => void | Highlight search results with cleanup function | | showBusRoute(routeId?) | routeId?: string | Promise<() => void> | Show bus locations with cleanup function |

Type Definitions

interface BoundingBox {
  xMin: number;
  xMax: number;
  yMin: number;
  yMax: number;
}

interface RouteResult {
  features: any[];
  directions: any[];
}

interface MarkerOptions {
  element?: HTMLElement;
  color?: string;
  draggable?: boolean;
  anchor?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  onClick?: () => void;
}

interface SearchOptions {
  layerName?: string;
  iconImage?: string;
  highlightColor?: string;
  pulseAnimation?: boolean;
  zoomToResults?: boolean;
  onIconClick?: (lat: number, lng: number, properties: any) => void;
  onResultsUpdate?: (results: any[]) => void;
  onLoadingStateChange?: (state: 'firstRender' | 'rerender' | false) => void;
}

Version Information

Current Version: 1.0.45
Dependencies: maplibre-gl ^5.19.0, axios ^1.7.9
Changelog: CHANGELOG.md

Support

For issues, questions, or contributions, contact the Yarrow development team.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Yarrow Map Web SDK Documentation

Table of Contents

Getting Started

Installation

Local Development

Initialization

Configuration Options

React Usage

Basic Map Manipulation

Changing the Map Style

Changing the Map Theme

Changing Brand Badge Position

Moving the Map View

Changing Background Color

Handling Events

Listen for Map Movement

Listen for Map Clicks

Listen for Clicks on POIs or Buildings

Working with Layers and Data

Adding a GeoJSON Layer

Advanced Layer Configuration

Managing Sources Explicitly

Feature State and Rendered Queries

Adding and Removing Markers

Removing a Layer

Routing

Building and Displaying a Simple Route

Building and Displaying a Multi-Stop Route

Clearing Routes

Rendering Multiple Routes

Search

Highlighting Search Results

Advanced Search Configuration

Public Transport

Displaying Real-Time Bus Locations

Clearing Bus Routes

Utility Methods

Calculating Bounding Box

Clearing Local Cache

Advanced Features

Custom Icons and Styling

Performance Optimization

API Reference

YarrowMapConfig Class

YarrowMap Class Methods

Type Definitions

Version Information

Support