Skip to main content

Assets Map Styles

|

This example demonstrates how to load and apply custom map styles from assets. It shows how to fetch a .style file and apply it to the map dynamically.

Overview​

The example demonstrates the following features:

  • Loading custom map style files from assets
  • Applying map styles using setMapStyleByBuffer
  • Centering the map on specific coordinates after style application
  • Error handling for asset loading

Code Implementation​

Initialize GemKit and Create Map​

index.ts
import {
  GemKit,
  GemMap,
  Coordinates,
  PositionService
} from '@magiclane/maps-sdk';

let map: GemMap | null = null;
let isStyleLoaded = false;

window.addEventListener('DOMContentLoaded', async () => {
  const gemKit = await GemKit.initialize(GEMKIT_TOKEN);
  await PositionService.instance;

  const container = document.getElementById('map-container');
  if (!container) throw new Error('Map container not found');

  const viewId = 4;
  const wrapper = gemKit.createView(viewId, (gemMap: GemMap) => {
    map = gemMap;
  });
  if (wrapper) container.appendChild(wrapper);

  // Create Apply Style button
  applyStyleBtn = document.createElement('button');
  applyStyleBtn.textContent = 'Apply Map Style';
  applyStyleBtn.onclick = () => applyStyle();
  document.body.appendChild(applyStyleBtn);
});

Load and Apply Map Style​

index.ts
async function applyStyle() {
  if (!map || isStyleLoaded) return;
  showMessage('The map style is loading...');

  // Simulate async loading delay
  await new Promise(resolve => setTimeout(resolve, 250));

  try {
    // Fetch the style file from assets
    const response = await fetch('./Basic_1_Oldtime-1_21_656.style');
    if (!response.ok) throw new Error('Failed to load style file');
    const styleBuffer = await response.arrayBuffer();
    
    // Apply style to map using setMapStyleByBuffer
    map.preferences.setMapStyleByBuffer(new Uint8Array(styleBuffer));
    isStyleLoaded = true;
    applyStyleBtn.style.display = 'none';
    showMessage('Map style applied!');
    
    // Center the map after style is applied
    map.centerOnCoordinates(new Coordinates({ latitude: 45, longitude: 20 }), { zoomLevel: 25 });
  } catch (error) {
    showMessage('Error loading map style');
    console.error(error);
  }
}

Live Demo​

Key Features​

  • Custom Map Styles: Load and apply .style files from your assets folder.
  • Dynamic Style Application: Apply styles at runtime without reloading the map.
  • Error Handling: Gracefully handle style loading failures with user feedback.
  • Map Centering: Automatically center and zoom the map after applying a new style.

Explanation of Key Components​

  • map.preferences.setMapStyleByBuffer: Applies a custom map style from a binary buffer (Uint8Array).
  • fetch API: Used to load the .style file as an ArrayBuffer from the public assets folder.
  • map.centerOnCoordinates: Centers the map on specified coordinates with a zoom level.
  • Uint8Array: Converts the ArrayBuffer to the format expected by the SDK.

Asset Preparation​

When preparing custom map styles:

  1. File Format: Use .style files compatible with the Maps SDK.
  2. Location: Place style files in the public folder or serve them from a CDN.
  3. File Size: Keep file sizes reasonable for faster loading.
  4. Testing: Test styles before deployment to ensure compatibility.

Next Steps​

Last updated on