Drawing elements

The Felt SDK provides two main approaches for creating elements on your maps:

1. Interactive Drawing: Configure and activate drawing tools for users to create elements manually

2. Programmatic Creation: Create and modify elements directly through code

Elements created via the SDK are session-specific - they're not persisted to the map and won't be visible to other users.

Interactive Drawing with Tools

The methods on the ToolsController enable you to programmatically activate drawing tools for your users, as well as setting various options for the tools, such as color, line width, etc.

Use the setTool method to activate a particular tool.

Use the setToolSettings method to configure the options for a specific tool.

Use the onToolChange and onToolSettingsChange to be notified of changes to the above, or read them instantaneously with the getTool and getToolSettings methods.

As the user creates elements with the tools, you can be notified of them being created and updated using the onElementCreate and onElementChange listeners. See Listening for element creation for more details.

Tool types

Tool name	Element Type	Description
pin	Place	Creates a single point on a map, with a symbol and optional label
line	Line	Creates a sequence of straight lines through the points that the user clicks
route	Line	Creates a line that follows the routing logic depending on the mode of transport selected. For instance, walking, driving and cycling routes follow applicable roads and pathways to reach the waypoints the user provides. Flying routes follow great circle paths.
polygon	Polygon	Creates an enclosed area with straight edges
circle	Circle	A circle is defined by its center and radius.
marker	Marker	Freeform drawing with a pen-like rendering. Different sizes can be set for the pen. The geometry produced is in world-space, so as you zoom the map, the pen strokes remain in place.
highlighter	Highlighter	Represents an area of interest, created by drawing with a thick pen. By default, drawing an enclosed shape fills the interior.
text	Text	A label placed on the map with no background color.
note	Note	A label placed on the map with a rectangular background color and either white or black text.

Example

// Configure the line tool
felt.setToolSettings({
  tool: "line",
  strokeWidth: 8,
  color: "#448C2A"
});

// Activate the line tool
felt.setTool("line");

// Later, deactivate the tool
felt.setTool(null);

Programmatic Element Creation

If you want to create elements programatically instead of letting your users draw them interactively on the map, use the methods in the ElementsController.

To create elements, use the createElement method.

To update elements, use the updateElement method.

To delete elements, use the deleteElement method.

When elements are created programatically, they also trigger notifications about the corresponding changes to elements, via onElementCreate, onElementChange and onElementDelete.

Example

// Create a polygon
const polygonElement = await felt.createElement({
  type: "Polygon",
  coordinates: [
    [
      [-122.42, 37.78],
      [-122.41, 37.78],
      [-122.41, 37.77],
      [-122.42, 37.77],
      [-122.42, 37.78]
    ]
  ],
  color: "#FF5733",
  fillOpacity: 0.5
});
​

// Update its properties
await felt.updateElement({
  id: polygonElement.id,
  
  // note that we pass the type here, too in order to get correct
  // TypeScript type-checking and autocompletion.
  type: "Polygon",
  
  color: "#ABC123",
  fillOpacity: 0.5,
  strokeWidth: 2
});

// Finally delete the element
await felt.deleteElement(polygonElement.id)

Retrieving Element geometry

Extract the geometric representation of elements using the getElementGeometry method.

The geometry is returned in GeoJSON geometry format, which can be quite different to the way the element is specified in Felt. For example, Circle elements in Felt have their geometry converted into a polygon, representing the area covered by the circle.

Note: Text, Note, and Image elements do not return geometry as they are considered to annotations rather than true "geospatial" elements.

// Get an element's geometry in GeoJSON format
const geometry = await felt.getElementGeometry("element-1");
console.log(geometry?.type, geometry?.coordinates);

Listening for changes

Every change that is made to the elements on a map results in a call to either onElementCreate, onElementDelete or onElementChange.

// Set up a listener for changes to a polygon
const unsubscribeChange = felt.onElementChange({
  options: { id: polygon.id },
  handler: ({element}) => {
    console.log("Polygon was updated:", element);
  }
});
​
// Set up a listener for deletion
const unsubscribeDelete = felt.onElementDelete({
  options: { id: polygon.id },
  handler: () => {
    console.log("Polygon was deleted");
  }
});
​
// Later, clean up listeners
unsubscribeChange();
unsubscribeDelete();

Listening for element creation

There are two different ways for listening to elements being created, and the one you use depends on how the element is being created, and at what point you want to know about an element's creation.

When the user is creating elements with tools, they are often created in a number of steps, such as drawing a marker stroke or creating a polygon with many vertices.

When you want to know when the user has finished creating the element (e.g. the polygon was closed or the marker stroke ended) then you should use the onElementCreateEnd listener.

When elements are created programatically, they do not trigger the onElementCreateEnd event.

Elements created using Tools or createElement will trigger the onElementCreate event, with an extra property stating whether the element is still being created.

// Listen for any element creation
const unsubscribe = felt.onElementCreate({
  handler: (element) => {
    console.log(`New element created with ID: ${element.id}`);
    
    // Check if the element is still being drawn
    if (element.isBeingCreated) {
      console.log("User is still creating this element");
    }
  }
});

// Or listen for when element creation is completed with a tool
const unsubscribeEnd = felt.onElementCreateEnd({
  handler: ({element}) => {
    console.log(`Element ${element.id} creation finished`);
  }
});

// Later, clean up listeners
unsubscribe();
unsubscribeEnd();

Sample application: sending elements drawn by users to your backend

Here is an example showing the power of the Felt SDK, where in just a few lines of code you can allow your users to draw elements and have them sent to your own backend systems for persistence or analysis.

Assuming you have embedded your Felt map as described in Getting started, and in your own UI you have added a polygon-tool button and a reset-tool button, all you need is the following:

// Set your initial tool settings in a style that suits your application
felt.setToolSettings({
  tool: "polygon",
  strokeWidth: 2,
  color: "#FF5733",
  fillOpacity: 0.3,
});
  
// Activate the tool when the user clicks a button in your UI
​document.getElementById("polygon-tool").addEventListener("click", () => {
  felt.setTool("polygon");
});
​
// Disable the tool when the user clicks a button in your UI
document.getElementById("reset-tool").addEventListener("click", () => {
  felt.setTool(null);
});
​
// Listen for completed polygons
felt.onElementCreateEnd({
  handler: async ({element}) => {
    // get the polygon geometry that the user just drew
    const geometry = await felt.getElementGeometry(element.id);
    
    // send the polygon to your own backend system
    sendToServer(geometry);
  }
});