General concepts

This guide covers the mental model and the common patterns used throughout the Felt SDK. Understanding these once makes every other page predictable.

The Felt controller

Everything you do with the SDK goes through a controller object — named felt in all the examples in these docs. How you get it depends on where your code runs:

• Embeds — your code runs in your page, and the map lives in an iframe. Felt.embed(container, mapId, options) creates the iframe and returns a controller for it. You can also use Felt.connect(iframe.contentWindow) to attach a controller to a Felt iframe you've already placed on the page. See Controlling maps and Embed options.

• Extensions — your code runs inside the Felt app, and receives a ready-made controller: no embedding required. See the extensions documentation.

The controller communicates with the map via message passing, which is why every read is asynchronous (see promises below). The same controller API is available in both contexts.

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

const felt = await Felt.embed(
  document.getElementById("container"),
  FELT_MAP_ID,
);

Session-only vs persisted changes

A crucial rule for building on the SDK: changes made via the SDK are visible only to the current session — they are not saved to the map. This applies to:

• Annotations created with createElement

• Layers created with createLayersFromGeoJson

• Style changes made with setLayerStyle

• Filters set with setLayerFilters

This makes the SDK safe for building per-visitor experiences on shared maps: ten visitors can each see their own filters and drawings without affecting each other or the underlying map. To make persistent changes to a map, use the REST API.

Use of promises

All methods in the Felt SDK are asynchronous and return Promises — writes as well as reads. This means you'll need to use await or .then() when calling them:

const layer = await felt.getLayer("layer-1");
felt.getElements().then(elements => {
  console.log(elements);
});

Getting entities

The SDK follows a consistent pattern for getting entities. For each entity type, there are usually two getters:

1. A singular getter for retrieving one entity by ID:

const layer = await felt.getLayer("layer-1");
const element = await felt.getElement("element-1");

1. A plural getter that accepts constraints for retrieving multiple entities:

const layers = await felt.getLayers({ ids: ["layer-1", "layer-2"] });
const legendItems = await felt.getLegendItems({ layerIds: ["layer-1", "layer-2"] });

The plural getters also allow you to pass no constraints, in which case they'll return all entities of that type:

const layers = await felt.getLayers();
const legendItems = await felt.getLegendItems();

Getters can return null

Singular getters return null when the entity doesn't exist, and plural getters can contain null entries — always check before using the result:

const layer = await felt.getLayer("layer-1");
if (layer) {
  // Layer exists, safe to use
  console.log(layer.visible);
} else {
  console.log("Layer not found");
}

Batch your reads

When you need multiple entities, use the plural methods with constraints rather than making multiple individual calls:

// Better approach
const layers = await felt.getLayers({ ids: ["layer-1", "layer-2"] });

// Less efficient approach
const layer1 = await felt.getLayer("layer-1");
const layer2 = await felt.getLayer("layer-2");

Change listeners

Each entity type has a corresponding change listener method following the pattern on{EntityType}Change:

const unsubscribe = felt.onLayerChange({
  options: { id: "layer-1" },
  handler: ({ layer }) => {
    console.log("Layer updated:", layer);
  }
});

There are also various other setters and getters in the Felt SDK that follow this convention as much as possible. For example, selection:

const selection = await felt.getSelection();
const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    console.log("Selection updated:", selection);
  }
});

And layer filters — note that this particular listener receives the filters value directly, with no wrapper object:

const filters = await felt.getLayerFilters("layer-1");
await felt.setLayerFilters({
  layerId: "layer-1",
  filters: ["name", "eq", "Jane"],
});
const unsubscribe = felt.onLayerFiltersChange({
  options: { layerId: "layer-1" },
  handler: (filters) => console.log(filters.combined),
});

For the full list of listeners and their payloads, see the Events reference.

Cleanup functions

All change listeners return an unsubscribe function that should be called when you no longer need the listener:

const unsubscribe = felt.onLayerChange({
  options: { id: "layer-1" },
  handler: ({ layer }) => {
    console.log("Layer changed:", layer);
  }
});

// Later, when you're done listening:
unsubscribe();

This is particularly important in frameworks like React where you should clean up listeners when components unmount:

useEffect(() => {
  const unsubscribe = felt.onViewportMove({
    handler: (viewport) => {
      console.log("Viewport changed:", viewport);
    }
  });

  // Clean up when the component unmounts
  return () => unsubscribe();
}, []);

Handler and options structure

Change listeners always take a single object parameter containing both options and handler. This structure makes it easier to add new options in the future without breaking existing code:

// Current API
felt.onElementChange({
  options: { id: "element-1" },
  handler: ({ element }) => { /* ... */ }
});

// If we need to add new options later, no breaking changes:
felt.onElementChange({
  options: { 
    id: "element-1",
    newOption: "value" // Can add new options without breaking existing code
  },
  handler: ({ element }) => { /* ... */ }
});

Entity nodes

When dealing with mixed collections of entities (like in selection events), each entity is wrapped in an EntityNode object that includes type information:

felt.onSelectionChange({
  handler: ({ selection }) => {
    selection.forEach(node => {
      console.log(node.type);    // e.g., "element", "layer", "feature", ...
      console.log(node.entity);  // The actual entity object
      
      if (node.type === "element") {
        // TypeScript knows this is an Element
        console.log(node.entity.attributes);
      }
    });
  }
});