Framer Plugin

Framer Plugin

The Mapsemble Framer plugin lets you add interactive maps to your Framer projects directly from the Framer editor. Create new maps, embed existing ones, and edit map data — all without leaving Framer.

Prerequisites

• A Mapsemble account (any plan)
• A Framer project

Step 1: Install the plugin

1. Open your Framer project.
2. Go to Assets → Plugins in the left sidebar.
3. Search for Mapsemble in the Framer Marketplace.
4. Click Install to add it to your project.

Alternatively, visit the Mapsemble plugin page on the Framer Marketplace.

Step 2: Connect your account

The plugin uses PKCE OAuth2 for secure authentication:

1. Open the Mapsemble plugin from the sidebar.
2. Click Connect with Mapsemble.
3. A browser window opens to the Mapsemble authorization page.
4. Log in and authorize the plugin.
5. The plugin automatically detects the authorization and logs you in.

Your session persists across Framer sessions. Tokens refresh automatically when they expire.

Step 3: Insert a map

The plugin offers three ways to add a map:

Create a new map:

1. Select the Create tab in the plugin panel.
2. Choose a starter kit (pre-configured map template) or start with a blank map.
3. Enter a map name.
4. Optionally toggle Import demo content to populate the map with sample data.
5. Click Create & Insert — the map is created via the Mapsemble API and inserted onto your canvas.

Embed an existing map:

1. Select the Embed tab.
2. Choose a map from the dropdown (shows all maps in your account).
3. Click Insert map.

Try a sample map:

1. Select the Try Sample tab — no account required.
2. A demo map is inserted with a visible sample overlay.
3. Useful for testing the plugin before connecting your account.

Step 4: Customize the map

Once inserted, the map component appears on your Framer canvas:

• Resize the component like any other Framer element.
• Position it within your layout using Framer's design tools.
• The map renders as a responsive iframe pointing to https://app.mapsemble.com/embed/{mapId}.

To edit the map's data and configuration:

1. Select the Mapsemble component on the canvas.
2. The plugin panel automatically switches to Edit mode.
3. An embedded editor loads, connected to your map via a secure nonce token.
4. Edit markers, fields, and settings directly within Framer.

For full map customization (styling, filters, popups), open the map in the Mapsemble dashboard.

Theme integration

The plugin automatically syncs with Framer's light/dark theme:

• The map detects the current theme from Framer's data-framer-theme attribute.
• When you switch themes in Framer, the map updates in real time via postMessage.
• Falls back to the system's prefers-color-scheme preference.
• The initial theme is passed as a URL parameter: ?theme=light or ?theme=dark.

This means your embedded map matches your Framer site's appearance without any manual configuration.

How it works under the hood

Component architecture:

The plugin inserts a Framer component instance that renders an iframe:

https://app.mapsemble.com/embed/{mapId}?theme={light|dark}

Each inserted component stores metadata via Framer's plugin data API:

When you select a Mapsemble component on the canvas, the plugin reads the pluginId from the node's plugin data and switches to edit mode.

Data editor:

The edit mode loads an iframe to:

https://app.mapsemble.com/integrations/framer/{mapId}?token={nonce}&theme={theme}

The nonce token is a short-lived authentication token obtained via POST /api/nonce-token, ensuring the editor session is secure without exposing your main access token.

API endpoints used by the plugin:

Starter kits

Starter kits are pre-configured map templates with field schemas, styling, and optional demo data. When creating a map from a starter kit:

• The map inherits the kit's field definitions, marker styles, and display settings.
• Choosing Create blank map uses the default starter kit (minimal configuration).
• Demo content can be toggled independently of the starter kit choice.

Troubleshooting

"Connect with Mapsemble" doesn't open a window: Your browser may be blocking popups. Allow popups for the Framer editor domain and try again.

Map shows "Sample map" overlay: You inserted a sample map. Connect your account and create or embed a real map to remove the overlay.

Token expired: The plugin refreshes tokens automatically. If authentication fails, click your profile name in the plugin header and reconnect.

Map not loading in preview/published site: Ensure the map is published in your Mapsemble dashboard. Unpublished maps only render in the Framer editor.

Theme not syncing: Theme detection requires Framer's data-framer-theme attribute on the page body. This is standard in Framer projects but may not work in custom code overrides.