Getting started

The Felt SDK allows you to control your Felt maps and build powerful, interactive custom applications. You can control many aspects of the Felt UI and map contents, as well as receive notifications of events happening in the map such as clicks, selections, and more.

This feature is available to customers on the Enterprise plan. Reach out to set up a trial.

See our examples page to explore what you can build with the SDK.

There are two main ways to use the Felt SDK:

Extensions
Embedded maps

Extensions

Write code directly within Felt using our Extensions feature. Extensions run directly within the Felt environment, giving you immediate access to all SDK functionality without embedding or connection steps.

When creating an extension, you automatically have access to a FeltController object named felt with no setup required. This controller provides all the methods you need to interact with your Felt map, including getViewport, createElement, setLayerStyle, and many more.

// In a Felt extension, the controller is automatically available
const layers = await felt.getLayers();

// Listen for map events
felt.onSelectionChange({
  handler: ({ selection }) => console.log("Selection changed:", selection),
});

Embedded maps

Embed Felt maps in your own applications and control them remotely.

What you'll need

A Felt map to embed. Open any map you have access to and grab its ID from the URL: in felt.com/map/Readable-Title-xPV9BqMuYQxmUraVWy9C89BNA, the ID is the trailing part, xPV9BqMuYQxmUraVWy9C89BNA.
The map's sharing settings must allow the visitor to view it. Public and unlisted maps work out of the box; for private maps see Embed options.

Installation

Install the SDK using your preferred package manager:

npm install @feltmaps/js-sdk

Alternatively, load it straight from a CDN in a <script type="module"> — no build step required:

import { Felt } from "https://esm.run/@feltmaps/js-sdk";

Embed your first map

Create an HTML page with a container element. Give the container an explicit height — an iframe inside a zero-height container renders as an invisible sliver, which is the most common first-run problem:

<html>
  <head>
    <style>
      #container { height: 500px; }
    </style>
  </head>
  <body>
    <div id="container"></div>
    <script type="module" src="main.js"></script>
  </body>
</html>

Embed a Felt map in your container element and use the SDK to read from it:

// main.js
import { Felt } from "@feltmaps/js-sdk";

const felt = await Felt.embed(
  document.querySelector("#container"),
  "FELT_MAP_ID", // Replace with your map's ID
);

const layers = await felt.getLayers();
console.log(`This map has ${layers.length} layers`);

You should see your map load inside the container, with the Felt legend and zoom controls visible. Open the browser console and you should see the layer count logged. If the container stays empty, check that the map ID is correct and that the map's sharing settings allow viewing.

Throughout these docs, code examples assume a controller variable named felt, whether it came from Felt.embed or from the extension environment.

Next steps

General concepts — the mental model: controllers, promises, listeners, and what persists.
Controlling maps — viewports, and connecting to existing iframes.
Embed options — UI controls, initial viewport, private maps.
Integrating with React — React hooks for the SDK, and the React starter repo for a quick start.

PreviousProjects NextGeneral concepts

Last updated 23 days ago

Was this helpful?