Embed options

Felt.embed() takes an optional third argument that controls how the embedded map looks and behaves:

const felt = await Felt.embed(container, FELT_MAP_ID, {
  uiControls: {
    showLegend: false,
    cooperativeGestures: false,
  },
  initialViewport: {
    center: { latitude: 40.7128, longitude: -74.006 },
    zoom: 10,
  },
});

UI controls

All uiControls options are booleans:

Option

Default

Description

showLegend

true

Whether the legend is shown.

cooperativeGestures

true

Adjusted gesture behavior for embeds: on mobile, one-finger drag scrolls the page while two fingers pan the map; on desktop, scroll-to-zoom requires holding Ctrl/Cmd. Disable for app-like embeds where the map is the main content.

fullScreenButton

true

Shows a button that opens the map in a new tab or window.

geolocation

false

Shows a geolocation button that plots and tracks the visitor's position.

zoomControls

true

Shows the zoom controls (bottom right). Hiding them does not prevent zooming.

scaleBar

true

Shows the scale bar.

You can change these after the map has loaded with updateUiControls:

Initial viewport

initialViewport overrides the map's saved viewport with a center and zoom for this embed:

Embedding private maps

Public and unlisted maps embed with no extra configuration. To embed a private map for visitors who aren't logged into Felt, generate a short-lived embed token server-side with the REST API and pass it as the token option:

1. Your server calls POST /api/v2/maps/{map_id}/embed_token?user_email=…, using your API token. The visitor's user_email is a required query parameter, not a body field, and that address should belong to a member of your workspace. The response contains a token valid for 15 minutes.

2. Your page passes that token to Felt.embed:

Never call the embed token endpoint from the browser — that would expose your API token. Generate embed tokens on your server and hand only the short-lived token to the client.