Skip to main content

Overlapped Maps

Last updated: April 29, 2026 | 4 minutes read

This example demonstrates how to layer multiple map views on top of each other, creating overlay effects.

Live Demo​

Code Implementation​

Setup UI and Container​

First, create the app bar and main container to hold both maps:

function setupUI() {
  // App bar
  const appBar = document.createElement('div');
  appBar.style.cssText = `
    width: 100vw; height: 56px; background: #4527a0; color: #fff;
    display: flex; align-items: center; justify-content: flex-start;
    padding: 0 16px; font-size: 1.2em; font-weight: 500; position: fixed; top: 0; left: 0; z-index: 2000;
    box-shadow: 0 2px 8px rgba(0,0,0,0.10);
  `;
  appBar.innerHTML = `<span>Overlapped Maps</span>`;
  document.body.appendChild(appBar);

  // Main container for maps
  const main = document.createElement('div');
  main.id = 'overlap-map-container';
  main.style.cssText = `
    position: absolute; top: 56px; left: 0; width: 100vw; height: calc(100vh - 56px);
    background: #f5f5f5;
    overflow: hidden;
  `;
  document.body.appendChild(main);
}

Create Overlapped Maps​

Create two map instances with different sizes and positions:

window.addEventListener('DOMContentLoaded', async () => {
  setupUI();

  gemKit = await GemKit.initialize(GEMKIT_TOKEN);
  await PositionService.instance;

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

  // Large background map
  const mapBgContainer = document.createElement('div');
  mapBgContainer.style.cssText = `
    position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 1;
    border-radius: 0; overflow: hidden;
  `;
  const wrapperBg = gemKit.createView(0, (gemMap: GemMap) => {});
  if (wrapperBg) mapBgContainer.appendChild(wrapperBg);
  main.appendChild(mapBgContainer);

  // Smaller overlapped map
  const mapSmallContainer = document.createElement('div');
  mapSmallContainer.style.cssText = `
    position: absolute; top: 20px; left: 20px; width: 40vw; height: 40vh; z-index: 2;
    border: 2px solid #222; border-radius: 10px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.18);
    background: #fff;
  `;
  const wrapperSmall = gemKit.createView(1, (gemMap: GemMap) => {});
  if (wrapperSmall) mapSmallContainer.appendChild(wrapperSmall);
  main.appendChild(mapSmallContainer);
});

Key Features​

Map Layering​

Two independent GemMap instances are created using different view IDs:

  • Background Map (view ID: 0): Full-screen map covering entire viewport
  • Overlay Map (view ID: 1): Smaller map positioned in top-left corner (40% viewport width/height)

CSS Positioning​

Maps are layered using CSS absolute positioning and z-index:

  • Background: z-index: 1, positioned at top: 0, left: 0 with 100% width/height
  • Overlay: z-index: 2, positioned at top: 20px, left: 20px with 40vw x 40vh size

Independent Map Instances​

Each map is completely independent:

  • Separate GemMap instance with unique view ID
  • Can have different center coordinates
  • Can have different zoom levels
  • Can display different map styles
  • Can respond to gestures independently

Styling Details​

The smaller overlay map includes visual enhancements:

  • Border: 2px solid border (#222) for clear separation
  • Border Radius: 10px rounded corners for modern appearance
  • Box Shadow: Subtle shadow for depth effect
  • Background: White background for clean overlay look

How It Works​

  1. Initialize GemKit: Set up the SDK with API token
  2. Create Container: Main container positioned below app bar
  3. Create Background Map: Full-screen map using gemKit.createView(0)
  4. Create Overlay Map: Smaller map using gemKit.createView(1) with different styling
  5. Layer Maps: Use CSS z-index to control stacking order

Implementation Details​

  • View IDs: Each map requires a unique view ID (0 for background, 1 for overlay)
  • Container Management: Each map has its own container div with specific styling
  • Z-Index Hierarchy: Background map (z-index: 1) sits below overlay map (z-index: 2)
  • Responsive Sizing: Overlay uses viewport units (40vw x 40vh) for responsive behavior
  • Overflow Hidden: Prevents map content from extending beyond rounded corners

Use Cases​

  • Comparison Views: Compare two different map styles or time periods
  • Picture-in-Picture: Show detailed view alongside overview map
  • Split Context: Display different map data simultaneously
  • Navigation Aid: Keep overview map visible while exploring details
  • Multi-Region Monitoring: Monitor different geographic areas at once

Next Steps​

Last updated on