Appearance

Select an Entity Programmatically ​

Selecting an entity programmatically lets you highlight a specific point of interest, room, or amenity on the map from your own application logic — without requiring the user to tap or click the map themselves. This is useful for search-result highlighting, guided tours, and accessibility workflows.

Open in Sandbox ↗

Prerequisites ​

Basic usage ​

CDN ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });

  // Select a single entity by ID
  await mapsted.maps.selectEntity(56789);
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
});

// Select a single entity by ID
await maps.selectEntity(56789);

selectEntity accepts a numeric or string entity ID and optionally a second options object of type SelectOptions:

js
// CDN
await mapsted.maps.selectEntity(56789, {
  zoomTo: 18,        // zoom level to apply after selection (10–24)
  buildingId: 95,    // scope to a specific building; use -1 for property-level entities
});

// npm
await maps.selectEntity(56789, {
  zoomTo: 18,
  buildingId: 95,
});

Selecting without changing the floor ​

By default, selecting an entity on a different floor causes the map to switch to that entity's floor. Pass changeFloor: false to keep the user on their current floor while still marking the entity as selected (useful for off-floor highlighting or deep-linking without disrupting the current view):

js
// CDN
await mapsted.maps.selectEntity(56789, { changeFloor: false });

// npm
await maps.selectEntity(56789, { changeFloor: false });

Selecting without panning the camera ​

Pass panTo: false to skip the animated camera recentre on selection — useful when programmatically highlighting a series of entities (e.g. directory hover state) and the animated pan would be disruptive:

js
// CDN
await mapsted.maps.selectEntity(56789, { panTo: false });

// npm
await maps.selectEntity(56789, { panTo: false });

The flag is one-shot: subsequent selects without panTo: false revert to the default pan behavior. Can be combined with changeFloor: false to perform a fully silent selection (no floor switch, no camera pan):

js
await maps.selectEntity(56789, { changeFloor: false, panTo: false });

Using actionType for routing integration ​

The optional actionType field lets you integrate entity selection with the routing workflow. The value comes from the ActionTypes enum:

js
import * as maps from '@mapsted/maps-js-api';
import { ActionTypes } from '@mapsted/maps-js-api';

// Mark the selected entity as a routing start point
await maps.selectEntity(56789, { actionType: ActionTypes.ADD_START_POINT });

// Mark the selected entity as a routing destination
await maps.selectEntity(56789, { actionType: ActionTypes.ADD_DESTINATION });

Customizing entity appearance before selection ​

Use setEntityData to attach custom name, HTML popup content, or a custom marker icon to one or more entities before (or after) selecting them:

js
// CDN
await mapsted.maps.setEntityData([
  {
    id: 56789,
    name: 'Mapsted HQ',
    html: '<p>Visit us on the 4th floor.</p>',
    marker: 'https://example.com/custom-pin.svg',
  },
]);
await mapsted.maps.selectEntity(56789);

// npm
await maps.setEntityData([
  {
    id: 56789,
    name: 'Mapsted HQ',
    html: '<p>Visit us on the 4th floor.</p>',
    marker: 'https://example.com/custom-pin.svg',
  },
]);
await maps.selectEntity(56789);

To update a single entity by ID without replacing the full list, use setEntityDataById:

js
// npm
await maps.setEntityDataById(56789, {
  id: 56789,
  name: 'Temporary label',
  html: '<p>This store closes at 6 PM today.</p>',
});

To apply a fallback appearance for all entities that do not have explicit overrides, use setEntityDefaults:

js
// npm
await maps.setEntityDefaults({
  id: 0,           // id is required by MapEntity; ignored when used as defaults
  marker: 'https://example.com/default-pin.svg',
});

Reacting to user and API selections ​

The API fires a select event whenever the selected entity changes — whether triggered programmatically or by a user tap. The payload is of type EntityData):

js
// CDN
mapsted.maps.on('select', (payload) => {
  // payload: { buildingId, floorId, entityId }
  console.log('Entity selected:', payload.entityId);
  updateSidebar(payload.entityId);
});

// npm
maps.on('select', (payload) => {
  console.log('Entity selected:', payload.entityId);
  updateSidebar(payload.entityId);
});

The API also fires a detailsView event when the entity's detail panel is opened Its payload is the same EntityData shape:

js
// npm
maps.on('detailsView', (payload) => {
  console.log('Details opened for entity:', payload.entityId);
});

See The event system for full listener API details.

Current public-API scope ​

The following behaviours are not part of the current public JS API surface:

  • Deselecting an entity programmatically — there is no clearSelection() method and passing null to selectEntity throws MAPSTED-1012 (missing required entityId). If you need a programmatic deselect, contact info@mapsted.com to request this on the roadmap.

  • Info-popup control — SelectOptions does not include a showPopup field; popup display is governed by the defaultPopup feature flag set at init time via setFeatureFlags({ defaultPopup: false }).

Full option reference ​

OptionTypeDefaultDescription
zoomTonumber (10–24)noneZoom level to apply after centering on the entity. Omit to leave zoom unchanged.
buildingIdnumbernoneScope the selection to a specific building. Use -1 for property-level entities.
actionTypeActionTypesnoneRouting integration: ADD_START_POINT or ADD_DESTINATION.
changeFloorbooleantrueWhen false, suppresses the automatic floor switch that would otherwise occur when the target entity is on a different floor.
panTobooleantrueWhen false, suppresses the camera recentre/pan that would otherwise occur on selection. One-shot: subsequent selects without this flag revert to default pan.