1 of 100

JS SDK API Reference

API Reference

To get started:

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

const felt = await Felt.embed(
  document.querySelector("#container"),
  "FELT_MAP_ID",
  {
    uiControls: {
      cooperativeGestures: false,
      fullScreenButton: false,
      showLegend: false,
    },
  }
);
const layers = await map.getLayers();

View FeltController for a complete list of available functions. FeltEmbedOptions enumerates initialization options.

Documents

CHANGELOG

Modules

@feltmaps/js-sdk

1.10.0

Minor Changes

Basemaps

The Basemaps module allows you to control the map's basemap layer, such as getting the current basemap, listing available basemaps, changing the basemap, and being notified when the basemap changes.

Controller

BasemapsController

Interfaces

Type Aliases

Basemap

Basemap: | |

ColorBasemap

Properties

id

id: string

A unique identifier for the basemap.

Remarks

Do not rely on the stability of this ID for Felt basemaps, as they are subject to change.

name

name: string

The name of the basemap.

uiColorScheme

uiColorScheme: "light" | "dark"

The color scheme of the UI that goes with the basemap. It is best to set this to "light" if your basemap is broadly light, and "dark" if your basemap is broadly dark.

type

type: "color"

color

color: string

attribution?

optional attribution: string

The attribution of the basemap, which is shown in the map's UI.

ColorBasemapInput

ColorBasemapInput: Omit<, "id">

CustomTileBasemap

Properties

id

id

CustomTileBasemapInput

CustomTileBasemapInput: Omit<, "id">

FeltBasemap

Properties

id

id

Element

Element: | | | | | | | | |

ElementChangeCallbackParams

The parameters for the and the listeners.

Properties

element

ElementGroup

Properties

id

id: string

A string identifying the element group.

name

name: string

The name of the element group. This is shown in the legend.

caption

caption: null | string

The caption of the element group. This is shown in the legend.

elementIds

elementIds: string[]

The ids of the elements in the element group.

Remarks

You can use these ids to get the full element objects via the method.

visible

visible: boolean

Whether the element group is visible or not.

shownInLegend

shownInLegend: boolean

Whether the element group is shown in the legend or not.

ElementGroupChangeCallbackParams

The parameters for the listener.

Properties

elementGroup

ElementUpdate

ElementUpdate: PlaceElementUpdate | PathElementUpdate | PolygonElementUpdate | CircleElementUpdate | MarkerElementUpdate | HighlighterElementUpdate | TextElementUpdate | NoteElementUpdate | ImageElementUpdate

GetElementGroupsConstraint

The constraints to apply when getting element groups.

Properties

ids?

optional ids: string[]

The ids of the element groups to get.

GetElementsConstraint

The constraints to apply when getting elements.

Properties

ids?

ImageElementCreate

Properties

type

type

ImageElementRead

Properties

id

id

ImageElementUpdate

Properties

id

id

LinkElementRead

Properties

id

id

Interactions

The Interactions module allows you to be notified when the user interacts with the map.

Interactions include clicking and hovering on points and features.

Controller

MapInteractionEvent

The event object passed to the interaction listeners.

Properties

coordinate

coordinate:

The cursor position in world coordinates.

point

point: { x: number; y: number; }

The pixel coordinates of the mouse cursor, relative to the map and measured from the top left corner.

Name

Type

features

features: []

The vector features that are under the cursor.

rasterValues

rasterValues: []

The raster pixel values that are under the cursor.

AggregatedGridConfig

The grid configuration for an aggregated precomputed aggregate value. This requires an attribute property, because the numeric aggregation requires it.

If you just want to count the features in each grid cell, use the instead, where you are not required to specify an attribute.

Used inside .

Properties

AggregationConfig

Defines how to aggregate a value across features in a layer.

Properties

attribute

AggregationMethod

AggregationMethod: "min" | "max" | "avg" | "sum" | "median"

The method to use for the aggregation.

CountGridConfig

The grid configuration for a count-based precomputed aggregate value. Compared to the AggregatedGridConfig, the attribute property is not required, because the count is the same regardless of the attribute.

Used inside GetLayerPrecomputedCalculationParams.

Properties

resolution

resolution: number

The resolution of the grid to use for the precomputed calculation.

type

type: "h3"

The type of grid to use for the precomputed calculation.

method

method: "count"

The method to use for the precomputed calculation, which in this case is always "count".

DataOnlyLayer

A data-only layer doesn't have any geometry, but can be used to join with other layers

Properties

id

FeltTiledVectorSource

FeltTiledVectorSource: { type: "felt"; tileTemplateUrl: string; }

A tiled vector source is a layer that is populated from data the has been uploaded to Felt, and processed into vector tiles.

FilterExpression

FilterExpression: [null | string, "in" | "ni", null | (null | string | number | boolean)[]] | [null | string, "lt" | "gt" | "le" | "ge" | "eq" | "ne" | "cn" | "nc" | "is" | "isnt", null | string | number | boolean]

FilterLogicGate

FilterLogicGate: "and" | "or"

FilterTernary

FilterTernary: [FilterTernary | FilterExpression | null | boolean, FilterLogicGate, FilterTernary | FilterExpression | null | boolean]

A FilterTernary is a tree structure for combining expressions with logical operators.

When combining three or more conditions, you must use proper nesting rather than a flat list.

Example

GeoJsonDataVectorSource

A GeoJSON data source is a layer that is populated from GeoJSON data, such as from a local file, or programmatically-created data.

Properties

type

type: "geoJsonData"

Identifies this as a GeoJSON data source.

data

data: object

The GeoJSON data for the layer.

This must be a GeoJSON FeatureCollection.

GeoJsonFileVectorSource

A GeoJSON file source is a layer that is populated from a GeoJSON file on your local machine.

This is an input-only type. It is converted to a when passed to .

Properties

GeoJsonUrlVectorSource

A GeoJSON URL source is a layer that is populated from a GeoJSON file at a remote URL.

These sources are ones that have not been uploaded to and processed by Felt, and as such their capabilities are limited.

For instance, they cannot be filtered, nor can statistics be fetched for them.

Properties

GeometryFilter

GeometryFilter: FeltBoundary | PolygonGeometry | MultiPolygonGeometry | LngLatTuple[]

The common type for filtering data by a spatial boundary.

This can be either:

FeltBoundary: a [w, s, e, n] bounding box
PolygonGeometry: a GeoJSON Polygon geometry
MultiPolygonGeometry: a GeoJSON MultiPolygon geometry
LngLatTuple[]: a list of coordinates describing a single ring of a polygon

GetLayerCalculationParams

The parameters for calculating a single aggregate value for a layer, passed to the method.

Type Parameters

Type Parameter

GetLayerCategoriesGroup

A single category from the response from the LayersController.getCategoryData method.

Properties

key

key: string | number | boolean

The category for which the value was calculated.

value

value: null | number

The value calculated for the category, whether a count, sum, average, etc.

null is returned if there are no features in the category as opposed to zero, so as not to confuse with a real zero value from some aggregation.

GetLayerCategoriesParams

The parameters for getting categories from a layer, passed to the method.

Properties

layerId

GetLayerGroupsConstraint

The constraints to apply when getting layer groups.

Properties

ids?

GetLayerHistogramBin

One bin from the response from the LayersController.getHistogramData method.

Properties

min

min: number

The left edge of the bin.

max

max: number

The right edge of the bin.

value

value: number

The number of features in the bin.

GetLayerPrecomputedCalculationParams

The parameters for calculating a single aggregate value for a layer, passed to the LayersController.getPrecomputedAggregates method.

Properties

layerId

layerId: string

The ID of the layer to calculate an aggregate value for.

gridConfig

gridConfig:

The grid configuration to use for the precomputed calculation.

filters?

optional filters:

Attribute filters for the features to include when calculating the aggregate value.

boundary?

optional boundary:

The spatial boundary for the features to include when calculating the aggregate value.

GetLayersConstraint

The constraints to apply when getting layers.

Properties

ids?

optional ids: string[]

The ids of the layers to get.

GetRenderedFeaturesConstraint

Constraints for the `getRenderedFeatures` method. This can include layer constriants, spatial constraints, or both. If no constraints are provided, all rendered features will be returned.

Properties

areaQuery?

optional areaQuery: { coordinates: ; } | { boundary: [number, number, number, number]; }

The area to query for rendered features. This can be specific coordinates or a . If omitted, the entire viewport will be queried.

layerIds?

optional layerIds: string[]

The ids of the layers to get rendered features for.

GridConfig

GridConfig: CountGridConfig | AggregatedGridConfig

Describes the type of grid to use for precomputed aggregate values.

GridType

GridType: "h3"

The type of grid to use for precomputed aggregate values.

Layer

Layer: | |

LayerChangeCallbackParams

The parameters for the listener.

Properties

layer

LayerFilters

The filters that are currently set on a layer.

A layer's filters are the combination of various different places in which filters can be applied.

Properties

LayerGroup

Properties

id

id

LayerGroupChangeCallbackParams

The parameters for the `onLayerGroupChange` listener.

Properties

layerGroup

layerGroup: null |

LayerProcessingStatus

LayerProcessingStatus: "processing" | "completed" | "failed" | "incomplete"

This describes the processing status of a layer.

The various values are:

processing: The layer has been uploaded or updated and is still processing.
completed: The layer has been processed and can be viewed on the map.
failed: The layer failed to process and cannot be viewed on the map.
incomplete: The layer has not been processed.

LayerSchemaAttribute

LayerSchemaAttribute: LayerSchemaNumericAttribute | LayerSchemaTextAttribute | LayerSchemaBooleanAttribute | LayerSchemaDateAttribute | LayerSchemaDateTimeAttribute

A single attribute from the layer schema.

Remarks

Each feature in a layer has a set of attributes, and these types describe the structure of a single attribute, including things like id, display name, type, and sample values.

LegendItemChangeCallbackParams

The parameters for the listener.

Properties

legendItem

TextElementUpdate

Properties

id

id: string

The unique identifier for the element.

type

type: "Text"

groupId?

optional groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color?

optional color: string

The color of the element in some CSS-like format.

Example

Default

description?

optional description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes?

optional attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

rotation?

optional rotation: number

The rotation of the element in degrees.

Default

scale?

optional scale: number

The relative scale of the element from the default size. This is combined with the zoom to determine the actual size of the element.

Default

zoom?

optional zoom: number

The zoom level at which the element was created. This is combined with the scale to determine the actual size of the element.

When creating an element, if you don't supply this value it defaults to the current zoom of the map when you call createElement.

text?

optional text: string

The text in the element.

align?

optional align: "center" | "left" | "right"

The alignment of the text, either left, center or right.

Default

style?

optional style: "light" | "italic" | "regular" | "caps"

The style of the text, either italic, light, regular or caps.

Default

position?

optional position:

The geographical position of the center of the text element.

CircleElementCreate

Properties

type

type: "Circle"

radius

radius: number

The radius of the circle in meters.

center

center:

The center of the circle.

groupId?

optional groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color?

optional color: string

The color of the element in some CSS-like format.

Example

Default

name?

optional name: null | string

The element's name. For elements that can show a label or text on the map (e.g. a Place or Text element) this is the text that will be shown.

For elements such as Polygons or Paths, the name is what is shown when the element is selected by clicking on it.

description?

optional description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes?

optional attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

imageUrl?

optional imageUrl: null | string

The URL of an image that has been added to the element.

strokeOpacity?

optional strokeOpacity: number

A value between 0 and 1 that describes the opacity of the element's stroke.

Default

strokeWidth?

optional strokeWidth: number

The width of the element's stroke in pixels.

Default

strokeStyle?

optional strokeStyle: "solid" | "dashed" | "dotted"

The style of the element's stroke.

Default

radiusMarker?

optional radiusMarker: boolean

Whether to show a marker on the circle that indicates the radius

Default

radiusDisplayAngle?

optional radiusDisplayAngle: number

The angle at which the control point for setting the radius is displayed, in degrees. When the radiusMarker is true, there is a dotted line rendered from the center of the circle to the control point, and the marker is shown at the midpoint of this line.

Default

radiusDisplayUnit?

optional radiusDisplayUnit: null | "meter" | "kilometer" | "foot" | "mile"

The unit of the radius used when the radiusMarker is true.

A value of null means that the unit matches the user's locale.

Default

fillOpacity?

optional fillOpacity: number

The opacity of the circle's fill.

Default

CircleElementRead

Properties

id

id: string

The unique identifier for the element.

groupId

groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color

color: string

The color of the element in some CSS-like format.

Example

Default

name

name: null | string

The element's name. For elements that can show a label or text on the map (e.g. a Place or Text element) this is the text that will be shown.

For elements such as Polygons or Paths, the name is what is shown when the element is selected by clicking on it.

description

description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes

attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

imageUrl

imageUrl: null | string

The URL of an image that has been added to the element.

strokeOpacity

strokeOpacity: number

A value between 0 and 1 that describes the opacity of the element's stroke.

Default

strokeWidth

strokeWidth: number

The width of the element's stroke in pixels.

Default

strokeStyle

strokeStyle: "solid" | "dashed" | "dotted"

The style of the element's stroke.

Default

type

type: "Circle"

radius

radius: number

The radius of the circle in meters.

radiusMarker

radiusMarker: boolean

Whether to show a marker on the circle that indicates the radius

Default

radiusDisplayAngle

radiusDisplayAngle: number

Default

radiusDisplayUnit

radiusDisplayUnit: null | "meter" | "kilometer" | "foot" | "mile"

The unit of the radius used when the radiusMarker is true.

A value of null means that the unit matches the user's locale.

Default

fillOpacity

fillOpacity: number

The opacity of the circle's fill.

Default

center

center:

The center of the circle.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

CircleElementUpdate

Properties

id

id: string

The unique identifier for the element.

type

type: "Circle"

groupId?

optional groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color?

optional color: string

The color of the element in some CSS-like format.

Example

Default

name?

optional name: null | string

The element's name. For elements that can show a label or text on the map (e.g. a Place or Text element) this is the text that will be shown.

For elements such as Polygons or Paths, the name is what is shown when the element is selected by clicking on it.

description?

optional description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes?

optional attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

imageUrl?

optional imageUrl: null | string

The URL of an image that has been added to the element.

strokeOpacity?

optional strokeOpacity: number

A value between 0 and 1 that describes the opacity of the element's stroke.

Default

strokeWidth?

optional strokeWidth: number

The width of the element's stroke in pixels.

Default

strokeStyle?

optional strokeStyle: "solid" | "dashed" | "dotted"

The style of the element's stroke.

Default

radius?

optional radius: number

The radius of the circle in meters.

radiusMarker?

optional radiusMarker: boolean

Whether to show a marker on the circle that indicates the radius

Default

radiusDisplayAngle?

optional radiusDisplayAngle: number

Default

radiusDisplayUnit?

optional radiusDisplayUnit: null | "meter" | "kilometer" | "foot" | "mile"

The unit of the radius used when the radiusMarker is true.

A value of null means that the unit matches the user's locale.

Default

fillOpacity?

optional fillOpacity: number

The opacity of the circle's fill.

Default

center?

optional center:

The center of the circle.

NoteElementRead

Properties

id

id: string

The unique identifier for the element.

groupId

groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color

color: string

The color of the element in some CSS-like format.

Example

Default

description

description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes

attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

rotation

rotation: number

The rotation of the element in degrees.

Default

scale

scale: number

The relative scale of the element from the default size. This is combined with the zoom to determine the actual size of the element.

Default

zoom

zoom: number

The zoom level at which the element was created. This is combined with the scale to determine the actual size of the element.

When creating an element, if you don't supply this value it defaults to the current zoom of the map when you call createElement.

text

text: string

The text in the element.

align

align: "center" | "left" | "right"

The alignment of the text, either left, center or right.

Default

style

style: "light" | "italic" | "regular" | "caps"

The style of the text, either italic, light, regular or caps.

Default

name

name: string

The text shown in the element, which is identical to the text property.

Remarks

This is added for consistency with other elements that have a name property.

type

type: "Note"

widthScale

widthScale: number

position

position:

The geographical position of the center of the note element.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

PathElementRead

Properties

id

id: string

The unique identifier for the element.

groupId

groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color

color: string

The color of the element in some CSS-like format.

Example

Default

name

name: null | string

The element's name. For elements that can show a label or text on the map (e.g. a Place or Text element) this is the text that will be shown.

For elements such as Polygons or Paths, the name is what is shown when the element is selected by clicking on it.

description

description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes

attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

imageUrl

imageUrl: null | string

The URL of an image that has been added to the element.

strokeOpacity

strokeOpacity: number

A value between 0 and 1 that describes the opacity of the element's stroke.

Default

strokeWidth

strokeWidth: number

The width of the element's stroke in pixels.

Default

strokeStyle

strokeStyle: "solid" | "dashed" | "dotted"

The style of the element's stroke.

Default

type

type: "Path"

distanceMarker

distanceMarker: boolean

Whether a distance marker is shown at the midpoint of the path.

Default

routingMode

routingMode: null | "driving" | "cycling" | "walking" | "flying"

Whether this represents a route, and if so, what mode of transport is used.

If this is null, the path is not considered to be a route, so while it can have a distanceMarker, it will does not have a start or end cap.

Default

endCaps

endCaps: boolean

Whether or not to show Start and End caps on the path. This is only available if the routingMode is set.

Default

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

PathElementUpdate

Properties

id

id: string

The unique identifier for the element.

type

type: "Path"

groupId?

optional groupId: null | string

The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null.

color?

optional color: string

The color of the element in some CSS-like format.

Example

Default

name?

optional name: null | string

The element's name. For elements that can show a label or text on the map (e.g. a Place or Text element) this is the text that will be shown.

For elements such as Polygons or Paths, the name is what is shown when the element is selected by clicking on it.

description?

optional description: null | string

Text describing the element, which is shown in an element's popup when it is selected.

Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown.

attributes?

optional attributes: Record<string, unknown>

A set of key-value pairs that can be used to store arbitrary data about the element.

This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data.

interaction?

optional interaction: "default" | "locked"

Whether the element is interactive.

The default interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool.

If the interaction mode is locked, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident.

Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes.

Default

imageUrl?

optional imageUrl: null | string

The URL of an image that has been added to the element.

strokeOpacity?

optional strokeOpacity: number

A value between 0 and 1 that describes the opacity of the element's stroke.

Default

strokeWidth?

optional strokeWidth: number

The width of the element's stroke in pixels.

Default

strokeStyle?

optional strokeStyle: "solid" | "dashed" | "dotted"

The style of the element's stroke.

Default

distanceMarker?

optional distanceMarker: boolean

Whether a distance marker is shown at the midpoint of the path.

Default

routingMode?

optional routingMode: null | "driving" | "cycling" | "walking" | "flying"

Whether this represents a route, and if so, what mode of transport is used.

If this is null, the path is not considered to be a route, so while it can have a distanceMarker, it will does not have a start or end cap.

Default

endCaps?

optional endCaps: boolean

Whether or not to show Start and End caps on the path. This is only available if the routingMode is set.

Default

coordinates?

optional coordinates: [][]

ElementsController

The Elements controller allows you to get information about the elements on the map, and make changes to their visibility.

Extended by

FeltController

Methods

getElement()

getElement(id: string): Promise<null | >

Get a single element from the map by its id.

Use this method when you know the specific ID of an element and want to retrieve its current state. This is more efficient than getting all elements and filtering.

Parameters

Parameter

Type

Description

Returns

Promise<null | >

A promise that resolves to the requested element, or null if not found.

Example

getElementGeometry()

getElementGeometry(id: string): Promise<null | >

Get the geometry of an element in GeoJSON geometry format.

For most element types, the geometry returned is based on the coordinates property of the element, with some differences:

For Circle elements, the geometry is a Polygon drawn from the center and radius properties.
Path elements become MultiLineString geometries.
Marker elements return a MultiLineString of the path traced by the user as they drew the marker. Note that this is not the polygon formed by filled-in "pen" stroke, which doesn't exactly follow the path traced by the user as it is smoothed and interpolated to create a continuous line.

Use this method when you need the geometric representation of an element for spatial analysis or visualization purposes.

Parameters

Parameter

Type

Description

Returns

Promise<null | >

A promise that resolves to the element's geometry in GeoJSON format, or null if the element has no geometry.

Example

getElements()

getElements(constraint?: ): Promise<(null | )[]>

Gets elements from the map, according to the constraints supplied. If no constraints are supplied, all elements will be returned.

Use this method to retrieve multiple elements, optionally filtered by constraints. This is useful for bulk operations or when you need to analyze all elements on the map.

Parameters

Parameter

Type

Description

Returns

Promise<(null | )[]>

A promise that resolves to an array of elements, ordered by the order specified in Felt.

Remarks

The elements in the map, ordered by the order specified in Felt. This is not necessarily the order that they are drawn in, as Felt draws points above lines and lines above polygons, for instance.

Example

getElementGroup()

getElementGroup(id: string): Promise<null | >

Get an element group from the map by its id.

Element groups allow you to organize related elements together and control their visibility as a unit.

Parameters

Parameter

Type

Description

Returns

Promise<null | >

A promise that resolves to the requested element group, or null if not found.

Example

getElementGroups()

getElementGroups(constraint?: ): Promise<(null | )[]>

Gets element groups from the map, according to the filters supplied. If no constraints are supplied, all element groups will be returned in rendering order.

Use this method to retrieve multiple element groups, optionally filtered by constraints. This is useful for bulk operations on element groups.

Parameters

Parameter

Type

Description

Returns

Promise<(null | )[]>

A promise that resolves to an array of element groups in rendering order.

Example

setElementGroupVisibility()

setElementGroupVisibility(visibility: ): Promise<void>

Hide or show element groups with the given ids.

Use this method to control the visibility of multiple element groups at once. This is more efficient than hiding/showing individual elements.

Parameters

Parameter

Type

Description

Returns

Promise<void>

A promise that resolves when the visibility changes are applied.

Example

createElement()

createElement(element: ): Promise<>

Create a new element on the map.

Use this method to programmatically create elements on the map. Elements created via the SDK are only available to the current session and are not persisted.

Parameters

Parameter

Type

Description

Returns

Promise<>

A promise that resolves to the created element.

Example

updateElement()

updateElement(element: ): Promise<>

Update an element on the map. The element type must be specified.

Use this method to modify existing elements. You can update properties like coordinates, styling, and metadata.

Parameters

Parameter

Type

Description

Returns

Promise<>

A promise that resolves to the updated element.

Example

deleteElement()

deleteElement(id: string): Promise<void>

Delete an element from the map.

Use this method to remove elements from the map. This operation cannot be undone.

Parameters

Parameter

Type

Description

Returns

Promise<void>

A promise that resolves when the element is deleted.

Example

Events

onElementCreate()

onElementCreate(args: { handler: (change: ) => void; }): VoidFunction

Adds a listener for when an element is created.

This will fire when elements are created programmatically, or when the user starts creating an element with a drawing tool.

When the user creates an element with a drawing tool, it can begin in an invalid state, such as if you've just placed a single point in a polygon.

You can use the isBeingCreated property to determine if the element is still being created by a drawing tool.

If you want to know when the element is finished being created, you can use the listener.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener.

Example

onElementCreateEnd()

onElementCreateEnd(args: { handler: (params: { element: ; }) => void; }): VoidFunction

Listens for when a new element is finished being created by a drawing tool.

This differs from the listener, which fires whenever an element is first created. This fires when the user finishes creating an element which could be after a series of interactions.

For example, when creating a polygon, the user places a series of points then finishes by pressing Enter or Escape. Or when creating a Place element, they add the marker, type a label, then finally deselect the element.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener.

Example

onElementChange()

onElementChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction

Adds a listener for when an element changes.

This will fire when an element is being edited, either on the map by the user or programmatically.

Like the listener, this will fire when an element is still being created by a drawing tool.

You can check the property to determine if the element is still being created by a drawing tool.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener.

Example

onElementDelete()

onElementDelete(args: { options: { id: string; }; handler: () => void; }): VoidFunction

Adds a listener for when an element is deleted.

Use this to react to element deletions, such as cleaning up related data or updating your application state.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener.

Example

onElementGroupChange()

onElementGroupChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction

Adds a listener for when an element group changes.

Use this to react to changes in element groups, such as when elements are added to or removed from groups.

Parameters

Parameter

Type

Returns

VoidFunction

A function to unsubscribe from the listener.

Example

LayersController

The Layers controller allows you to get information about the layers on the map, and make changes to their visibility.

Layers can be organised into groups, and their groups can also have their visibility toggled.

Extended by

FeltController

Methods

getLayer()

getLayer(id: string): Promise<null | >

Get a single layer from the map by its id.

Parameters

Parameter

Type

Description

Returns

Promise<null | >

The requested layer.

Example

getLayers()

getLayers(constraint?: ): Promise<(null | )[]>

Gets layers from the map, according to the constraints supplied. If no constraints are supplied, all layers will be returned.

Parameters

Parameter

Type

Description

Returns

Promise<(null | )[]>

All layers on the map.

Remarks

The layers in the map, ordered by the order specified in Felt. This is not necessarily the order that they are drawn in, as Felt draws points above lines and lines above polygons, for instance.

Example

setLayerVisibility()

setLayerVisibility(visibility: ): Promise<void>

Hide or show layers with the given ids.

Parameters

Parameter

Type

Returns

Promise<void>

Example

setLayerStyle()

setLayerStyle(params: { id: string; style: object; }): Promise<void>

Set the style for a layer using FSL, the Felt Style Language.

Changes are only for this session, and not persisted. This is useful to make temporary changes to a layer's style, such as to highlight a particular layer or feature.

See the for details on how to read and write styles.

If the style you set is invalid, you will receive an error explaining the problem in the rejected promise value.

Parameters

Parameter

Type

Description

Returns

Promise<void>

Example

setLayerLegendVisibility()

setLayerLegendVisibility(params: ): Promise<void>

Hide or show layers with the given ids from the legend.

Parameters

Parameter

Type

Returns

Promise<void>

Example

createLayersFromGeoJson()

createLayersFromGeoJson(params: ): Promise<null | { layerGroup: ; layers: []; }>

Adds layers to the map from file or URL sources.

Parameters

Parameter

Type

Returns

Promise<null | { layerGroup: ; layers: []; }>

The layer groups that were created.

Remarks

This allows you to add temporary layers to the map that don't depend on any processing by Felt. This is useful for viewing data from external sources or remote files.

Example

updateLayer()

updateLayer(params: ): Promise<>

Update a layer by passing a subset of the layer's properties.

Note that not all properties can be updated, so check the type to see which properties can be updated.

Parameters

Parameter

Type

Returns

Promise<>

Example

deleteLayer()

deleteLayer(id: string): Promise<void>

Delete a layer from the map by its id.

Parameters

Parameter

Type

Returns

Promise<void>

Remarks

This only works for layers created via the SDK createLayersFromGeoJson method, not layers added via the Felt UI.

Example

duplicateLayer()

duplicateLayer(id: string): Promise<>

Duplicate a layer from the map by its id.

Parameters

Parameter

Type

Returns

Promise<>

The duplicated layer.

Remarks

This will create an ephemeral copy of the layer, just for the duration of the session. The duplicated layer will not be persisted to the map.

Example

getLayerGroup()

getLayerGroup(id: string): Promise<null | >

Get a layer group from the map by its id.

Parameters

Parameter

Type

Returns

Promise<null | >

The requested layer group.

Example

getLayerGroups()

getLayerGroups(constraint?: ): Promise<(null | )[]>

Gets layer groups from the map, according to the constraints supplied. If no constraints are supplied, all layer groups will be returned in rendering order.

Parameters

Parameter

Type

Description

Returns

Promise<(null | )[]>

The requested layer groups.

Example

setLayerGroupVisibility()

setLayerGroupVisibility(visibility: ): Promise<void>

Hide or show layer groups with the given ids.

Parameters

Parameter

Type

Returns

Promise<void>

Example

setLayerGroupLegendVisibility()

setLayerGroupLegendVisibility(params: ): Promise<void>

Hide or show layer groups with the given ids from the legend.

Parameters

Parameter

Type

Returns

Promise<void>

Example

getLegendItem()

getLegendItem(id: ): Promise<null | >

Allows you to get the state of a single legend item.

Parameters

Parameter

Type

Returns

Promise<null | >

Example

getLegendItems()

getLegendItems(constraint?: ): Promise<(null | )[]>

Allows you to obtain the state of several legend items, by passing in constraints describing which legend items you want.

If you do not pass any constraints, you will receive all legend items.

Parameters

Parameter

Type

Returns

Promise<(null | )[]>

Example

setLegendItemVisibility()

setLegendItemVisibility(visibility: { show: []; hide: []; }): Promise<void>

Hide or show legend items with the given identifiers.

Parameters

Parameter

Type

Returns

Promise<void>

Example

getLayerFilters()

getLayerFilters(layerId: string): Promise<null | >

Get the filters for a layer.

Parameters

Parameter

Type

Returns

Promise<null | >

Remarks

The return type gives you the filters split up into the various sources that make up the overall filters for a layer.

Example

setLayerFilters()

setLayerFilters(params: { layerId: string; filters: ; note: string; }): Promise<void>

Sets the ephemeral filters for a layer.

Parameters

Parameter

Type

Description

Returns

Promise<void>

Example

getLayerBoundaries()

getLayerBoundaries(layerId: string): Promise<null | >

Get the spatial boundaries that are filtering a layer.

Parameters

Parameter

Type

Returns

Promise<null | >

Remarks

The return type gives you the boundaries split up into the various sources that make up the overall boundary for a layer.

The combined boundary is the intersection of the other sources of boundaries.

Example

setLayerBoundary()

setLayerBoundary(params: { layerIds: string[]; boundary: null | ; }): Promise<void>

Set the boundary for one or more layers.

Parameters

Parameter

Type

Description

Returns

Promise<void>

Example

getRenderedFeatures()

getRenderedFeatures(params?: ): Promise<[]>

Get the features that are currently rendered on the map in the viewport.

Note that this is explicitly about the features that are rendered, which isn't necessarily a complete list of all the features in the viewport. This is because of the way features are tiled: at low zoom levels or high feature densities, many features are omitted from what is rendered on the screen.

Parameters

Parameter

Type

Description

Returns

Promise<[]>

Example

getFeature()

getFeature(params: { id: string | number; layerId: string; }): Promise<null | >

Get a feature from the map by its ID and layer ID.

The response is a object, which does not include the geometry of the feature.

You may want to use this when you don't need the geometry of a feature, but you know the ID of the feature you need.

Parameters

Parameter

Type

Returns

Promise<null | >

Example

getFeatures()

getFeatures(params: { layerId: string; filters: ; sorting: ; boundary: ; search: string; pagination: null | string; pageSize: number

Get a list of layer features.

Parameters

Parameter

Type

Description

Returns

Promise<{ features: []; count: number; previousPage: null | string; nextPage: null | string; }>

The response is an object which contains:

features: list of objects, which does not include the geometry of the feature but it does include its bounding box.
count: the total number of features that match the query.
previousPage & nextPage: The tokens to pass in the pagination

Remarks

This list is paginated in sets of 20 features for each page. In order to paginate between pages, the response includes previousPage and nextPage that are tokens that should be sent in the pagination params for requesting sibling pages.

Text search is case-insensitive and looks for matches across all feature properties.

Example

getGeoJsonFeature()

getGeoJsonFeature(params: { id: string | number; layerId: string; }): Promise<null | >

Get a feature in GeoJSON format from the map by its ID and layer ID.

The response is a GeoJSON Feature object with the complete geometry of the feature. Note that for some very large geometries, the response may take a long time to return, and may return a very large object.

Parameters

Parameter

Type

Returns

Promise<null | >

Example

getCategoryData()

getCategoryData(params: ): Promise<[]>

Gets values from a layer grouped by a given attribute.

Parameters

Parameter

Type

Returns

Promise<[]>

Remarks

Groups features in your layer by unique values in the specified attribute and calculates a value for each group. By default, this value is the count of features in each group.

You can apply filters in two ways:

At the top level (using boundary and filters), which affects both what categories are included and how values are calculated
In the values configuration, which only affects the values but keeps all categories

This two-level filtering is particularly useful when you want to compare subsets of data while maintaining consistent categories. For example, you might want to show the distribution of all building types in a city, but only count buildings built after 2000 in each category.

Example

getHistogramData()

getHistogramData(params: ): Promise<[]>

Gets a histogram of values from a layer for a given attribute.

Parameters

Parameter

Type

Returns

Promise<[]>

Remarks

Creates bins (ranges) for numeric data and counts how many features fall into each bin, or returns aggregated values for each bin.

You can control how the bins are created using the steps parameter, choosing from several methods like equal intervals, quantiles, or natural breaks (Jenks), or passing in the step values directly if you know how you want to bin the data.

Like getCategoryData, you can apply filters in two ways:

At the top level (using boundary and filters), which affects both how the bins are calculated and what features are counted in each bin
In the values configuration, which only affects what gets counted but keeps the bin ranges the same

This is particularly useful when you want to compare distributions while keeping consistent bin ranges. For example, you might want to compare the distribution of building heights in different years while using the same height ranges.

Example

getAggregates()

getAggregates<T>(params: <T>): Promise<Record<T, null | number>>

Calculates a single aggregate value for a layer based on the provided configuration.

Type Parameters

Type Parameter

Parameters

Parameter

Type

Returns

Promise<Record<T, null | number>>

Remarks

Performs statistical calculations on your data, like counting features or computing averages, sums, etc. You can focus your calculation on specific areas or subsets of your data using boundaries and filters.

When you request an aggregation other than count, you must specify an attribute to aggregate on.

Example

getPrecomputedAggregates()

getPrecomputedAggregates(params: ): Promise<{ avg: null | number; max: null | number; min: null | number; sum: null

Calculates aggregates for spatial cells of a layer.

Parameters

Parameter

Type

Returns

Promise<{ avg: null | number; max: null | number; min: null | number; sum: null | number; count: null

Remarks

Performs statistical calculations on spatial cells of a layer, returning min, max, avg, sum, and count. You can focus your calculation on specific areas or subsets of your data using boundaries and filters. When using the count method, an attribute is not required.

Example

getLayerSchema()

getLayerSchema(layerId: string): Promise<>

Get the schema for a layer.

Parameters

Parameter

Type

Returns

Promise<>

Remarks

The schema describes the structure of the data in a layer, including the attributes that are available on the features in the layer.

This can be useful to build generic UIs that need to know the structure of the data in a layer, such as a dropdown to choose an attribute.

Example

Events

onLayerChange()

onLayerChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction

Adds a listener for when a layer changes.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener

Example

onLayerGroupChange()

onLayerGroupChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction

Adds a listener for when a layer group changes.

Parameters

Parameter

Type

Returns

VoidFunction

A function to unsubscribe from the listener

Example

onLegendItemChange()

onLegendItemChange(args: { options: ; handler: (change: ) => void; }): VoidFunction

Adds a listener for when a legend item changes.

Parameters

Parameter

Type

Returns

VoidFunction

A function to unsubscribe from the listener

Example

onLayerFiltersChange()

onLayerFiltersChange(params: { options: { layerId: string; }; handler: (change: ) => void; }): VoidFunction

Adds a listener for when a layer's filters change.

Parameters

Parameter

Type

Returns

VoidFunction

A function to unsubscribe from the listener

Remarks

This event fires whenever any type of filter changes on the layer, including ephemeral filters set via the SDK, style-based filters, or filters set through the Felt UI via Components.

Example

onLayerBoundariesChange()

onLayerBoundariesChange(params: { options: { layerId: string; }; handler: (boundaries: null | ) => void; }): VoidFunction

Adds a listener for when a layer's spatial boundaries change.

Parameters

Parameter

Type

Description

Returns

VoidFunction

A function to unsubscribe from the listener

Remarks

This event fires whenever any type of spatial boundary changes on the layer, including ephemeral boundaries set via the SDK or boundaries set through the Felt UI via Spatial filter components.