Widget.js Reference

Widget.js Reference

The Mapsemble widget is a lightweight JavaScript file that creates and manages an embedded map using Shadow DOM, keeping your map fully isolated from the host page's styles and scripts.

Basic usage

Add the script tag and a container element to your HTML:

<script src="https://app.mapsemble.com/widget.js"></script>
<div data-mapsemble-map="YOUR_MAP_ID"></div>

That's it. The widget will automatically render the map inside the container.

How it works

When widget.js loads, it:

1. Finds all elements on the page with a data-mapsemble-map attribute
2. Renders a fully interactive map inside each element using Shadow DOM

Multiple maps on one page

You can embed multiple maps on the same page. Each element with a data-mapsemble-map attribute creates a separate, independent map:

<script src="https://app.mapsemble.com/widget.js"></script>

<div data-mapsemble-map="MAP_ID_1"></div>
<div data-mapsemble-map="MAP_ID_2"></div>

Each map manages its own state independently.

JavaScript API

Beyond automatic setup, widget.js exposes methods you can call from your own JavaScript to control the embedded map programmatically.

Mapsemble.init(options)

Initializes a Mapsemble embed. Required for advanced usage (Shadow DOM embedding, custom rendering callbacks, zone selection).

Mapsemble.init({
  container: '#my-map',
  mapId: 'YOUR_MAP_ID',
  embed: 'shadow',
  language: 'en',
  mode: 'light',
});

onCount callback

React to total count changes. Called after every feature load with the backend total count (accounting for current filters and extent).

Mapsemble.init({
  container: '#my-map',
  mapId: 'YOUR_MAP_ID',
  embed: 'shadow',
  onCount: function(count) {
    document.querySelector('#property-count').textContent = count + ' properties';
  },
});

The callback receives a single count argument (number). It fires:

• After initial feature load
• After filter changes trigger a reload
• After pagination changes

countPhrase callback

Customize the count text displayed inside the widget. By default, the widget shows translated phrases like "X items match your search". Use countPhrase to override this with your own localized text.

Mapsemble.init({
  container: '#my-map',
  mapId: 'YOUR_MAP_ID',
  embed: 'shadow',
  countPhrase: function(count) {
    if (count === 0) return 'Keine Ergebnisse';
    if (count === 1) return '1 Immobilie gefunden';
    return count + ' Immobilien gefunden';
  },
});

The callback receives the total count and must return a string. The returned string replaces the default count text inside the widget. When not provided, the widget uses its built-in translations.

Scroll capture

On mobile, the widget can integrate with the host page scroll. When enabled, the widget becomes a sticky scroll section — as the user scrolls the page, the card list scrolls internally. When the card list reaches the end, the page continues scrolling normally.

Mapsemble.init({
  container: '#my-map',
  mapId: 'YOUR_MAP_ID',
  embed: 'shadow',
  scrollCapture: true,
  scrollCaptureTop: '84px',
});

scrollCapture (boolean) — Enables the scroll-through behavior. Only active on mobile (container width < 768px). The widget wraps itself in a tall sentinel container and uses position: sticky to stay in view while translating the host page scroll into internal card list scrolling.

scrollCaptureTop (string | number) — Sets the CSS top offset for the sticky widget. Use this to position the widget below a fixed or sticky header. Accepts any CSS value:

• '84px' — pixel offset
• '5rem' — rem-based offset
• 'var(--header-height)' — CSS custom property
• 84 — plain number (treated as pixels)

Defaults to '0px'.

Mapsemble.setFilters(mapId, filters)

Set external filters on an embedded map. Filters are merged with any active Mapsemble filters and sent as a single filters JSON parameter to the datasource endpoint. This is especially useful with remote datasources, where your endpoint receives the filters and applies them to its own database query.

// Apply filters
Mapsemble.setFilters('YOUR_MAP_ID', {
  category: 'restaurant',
  price_max: 50,
});

// Clear all external filters
Mapsemble.setFilters('YOUR_MAP_ID', {});

Key behavior:

• Full replace — each call replaces the entire external filter set. To keep a filter active, include it in every call.
• Immediate refetch — the map reloads features from the datasource as soon as filters are set.
• Merged with Mapsemble filters — if the map also has its own filter UI (configured in Mapsemble), both sets are combined. Use different keys to avoid overlap.
• Arbitrary keys and values — the filter object is passed through to your datasource endpoint as-is. Your endpoint decides how to interpret them.

Works with Shadow DOM embeds.

Mapsemble.setVisibleIds(mapId, ids, options)

Filter visible markers to a specific set of feature IDs.

Mapsemble.setVisibleIds('YOUR_MAP_ID', ['feature-1', 'feature-2']);

Mapsemble.setMainIds(mapId, ids)

Highlight specific markers as "main" (full size with labels) while dimming the rest.

Mapsemble.setMainIds('YOUR_MAP_ID', ['feature-1', 'feature-2']);

Mapsemble.setHoverId(mapId, id)

Highlight a single marker (e.g. when hovering a list item on your page). Pass null to clear.

Mapsemble.setHoverId('YOUR_MAP_ID', 'feature-1');
Mapsemble.setHoverId('YOUR_MAP_ID', null); // clear