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

• Elements

• Interactions

• Layers

• Main

• Misc

• Selection

• Shared

• Tools

• UI

• Viewport

1.9.0

Minor Changes

• 7e4034f: Add support for legendDisplay on the layer

1.8.0

Minor Changes

• 336538b: Improve controller method documentation

Patch Changes

• 7b04db4: Update filter docs

1.7.0

Minor Changes

• f40a75c: Update getPrecomputedAggregates types

• 4c4ebfd: Add UIIframeElement to custom ui panel

• b87393f: Better docs, types and method consistency for Custom Panels API

• aff926a: Return UIPanel on custom panel API methods

• f5ca219: Speed up initial Felt/SDK connection

• 0b06e28: Add support for align and distribute items on grid container

• bd1952f: Merge create and update panel methods and require using createPanelId

• 27cc597: Add UIGridContainerElement to custom ui panel

• f2fcd2a: Add checkbox, radio and toggle controls to custom ui panel

• 15a35a5: Add method getPrecomputedAggregates

• 6ce4a76: Rename UIPanel onClose to onClickClose

• c16c55a: Support disabled on custom ui control option

• 2688f9c: Add UIButtonRowElement to custom ui panel

• 49d8895: Add Custom UI API for action triggers

• 0754363: Add new variants, drop thin variants and add tint prop to UIButtonElement

• 535e539: Include element id on every custom ui callback args

• b848937: Add tool setting to hide/show inspector

• 1e8e6f1: Return UIActionTrigger on custom action trigger API methods

• 2b0f08f: Add Custom UI API for panels

• f73dccf: Remove UIButtonGroupElement from custom ui panel

Patch Changes

• 58bd6dd: Add isDeterministicId to LayerFeature

• 07b27c6: Export bundled controller types file for consumption as single file

• 41e1612: Update getAggregates examples to be correct

• 475c98e: Update getAggregates + MultiAggregationConfig docs

• ea5c7ff: Run patch on prepare, not install

• 4c83cfe: Don't try to patch packages not in dev mode

• 2008356: Documentation improvements

• 2fd720d: Use singular for custom ui types

• a1c6322: Make custom panel API consistent with other methods

1.6.0

Minor Changes

• 160ca6d: Implement getFeatures method on LayersController

• 6a1e536: Widen allowed boundary types

• 56077be: Add setLayerBoundary, getLayerBoundaries, onLayerBoundaryChange

1.5.1

Patch Changes

• ac68984: Update getLayerSchema example

1.5.0

Minor Changes

• d327b46: Add afterCreation option in pin tool settings to control what happens after creating a Place

• 6a66d40: Add updateLayer and expand createLayersFromGeoJson options

• 6504fea: Change documentation for getElementGeoemtry to document Highlighter and Marker functionality, and allow holes in Highlighter geometry

• cf6711e: Make programmatic element CRUD types more accurate

• 4c83c60: Add programmatic element creation, editing and deletion

• 46e8ddc: Add onElementChange and onElementDelete

• 3e87812: Adds APIs to use Felt's drawing tools on read-only maps

• d877a83: Add getFeature for getting a single feature as GeoJSON with full detail geometry

• 7f1d6aa: Add "interaction" to element schema

• cf1dd7c: Improve Text and Note types and docs

• 1f6a386: Add getViewportConstraints and setViewportConstraints methods definition

• b059b70: Add onLayerFiltersChange to allow listening to changes to layer filters, be it ephemeral, style or widget filters that changed.

• 19b41ce: Improve createLayer API

• c20e605: Add setLayerLegendVisibility and setLayerGroupLegendVisibility methods definition

• cbfd3fd: Reject promises when method handlers are invalid

• 0915f48: Add showLayerDataTable and hideLayerDataTable methods

• 9620df9: Change Circle.coordinates for Circle.center

• 63c3042: Add getLayerSchema method

• 69cc0a9: Fix spelling mistake in types

• 87304d8: Fix geometry filter type

• 1f22654: Add screen point to pointer events

• b0e4149: Improves type readability and docs

• 65bf269: Add createLayer and deleteLayer

• 4bd0ae9: Add getMapDetails method definition

• 5f903fb: Update Layer type and createLayerFromGeoJson to separate out Source concept

• 597a8d6: Return coordinates on Circle and Place elements as they are only a single point.

• f2f4289: Add layer stats methods

Patch Changes

• 993fd44: Allow workers to be SDK clients

• 417b8f4: Fixes incorrect value in documentation and updates links to other methods

• 9620df9: Improve element docs

• f0892c4: Improve documentation

• bb79037: Fix per-geometry styling for created layers

1.4.0

Minor Changes

• 555a25a: Add clearSelection method

• 1f5d950: Add option to pass auth token when embedding

1.3.0

Minor Changes

• 4bbde62: Allow setting a note to show with layer filters

1.2.0

Minor Changes

• 7badd4b: Add onMapIdle event

• 41efd53: Add selectFeature method to select feature by layer and feature ID

• 208c492: Add areaQuery param to getRenderedFeatures

1.1.0

Minor Changes

• 5f607ec: Return style with layers, and allow updating layer styles via setLayerStyle

Patch Changes

• 3a8bec8: Fix API reference link in README

1.0.2

Major Changes

• Release v1 of Felt JS SDK

Element: PlaceElementRead | PathElementRead | PolygonElementRead | CircleElementRead | MarkerElementRead | HighlighterElementRead | TextElementRead | NoteElementRead | ImageElementRead | LinkElementRead

The parameters for the `onElementChange` and the `onElementCreate` listeners.

Properties

element

element: null | Element

The new data for the element or null if the element was removed.

isBeingCreated

isBeingCreated: boolean

Whether or not this element is still being created by a drawing tool.

For example, if the user begins drawing a polygon, they need to place multiple points until they've ultimately completed the polygon. All the time they are still placing points, this will be true.

For elements that require text entry (such as Places, Text and Notes) this will be true all the time the user is typing text until the point at which the user finishes, by pressing Escape for example.

If the user is editing an existing element, this will be false.

For elements that are created programmatically, this will be false.

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 `getElements` 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.

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

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

• InteractionsController

Interfaces

• MapInteractionEvent

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

The method to use for the aggregation.

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".

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.

Type declaration

type

type: "felt"

Identifies this as a tiled vector source. Typically, these tiles will have been uploaded to and processed by Felt.

tileTemplateUrl

tileTemplateUrl: string

The template URL used for fetching tiles.

The constraints to apply when getting layer groups.

Properties

ids?

optional ids: string[]

The ids of the layer groups to get.

The parameters for the `onLayerChange` listener.

Properties

layer

layer: null | Layer

The new data for the layer or null if the layer was removed.

GridType: "h3"

The type of grid to use for precomputed aggregate values.

The parameters for the `onLayerGroupChange` listener.

Properties

layerGroup

layerGroup: null | LayerGroup

GridConfig: CountGridConfig | AggregatedGridConfig

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

The constraints to apply when getting element groups.

Properties

ids?

optional ids: string[]

The ids of the element groups to get.

The constraints to apply when getting elements.

Properties

ids?

optional ids: string[]

The ids of the elements to get.

FilterLogicGate: "and" | "or"

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.

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

Properties

attribute

attribute: string

The attribute to use for the aggregation. This must be a numeric attribute.

method

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

The method to use for the aggregation.

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

type

type: "geoJsonUrl"

Identifies this as a GeoJSON URL source.

url

url: string

The remote URL of the GeoJSON file used to populate the layer.

refreshInterval?

optional refreshInterval: null | number

The interval in milliseconds between automatic refreshes of the GeoJSON.

The value must be in the range of 250ms - 5 minutes (300,000ms).

If the value is null, the GeoJSON will not be refreshed automatically.

The constraints to apply when getting layers.

Properties

ids?

optional ids: string[]

The ids of the layers to get.

PrecomputedAggregationMethod: "avg" | "max" | "min" | "sum" | "count"

The method to use for the precomputed aggregation.

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.

The RasterBand interface describes the metadata for a raster band, necessary for calculating the encoded raster value from the red, green, and blue values of the pixel.

Properties

base

base: number

Encoding base value as a floating point number

interval

interval: number

Encoding interval as a floating point number

bandIndex

bandIndex: number

1-based index of the band in the raster

The Felt SDK lets you read, create and update elements on the map.

Elements that are created via the SDK are only available to the current session - they are not persisted to the map and not available to other users of the map.

If you want to let your users create elements (as opposed to using the SDK to create them programmatically), you can use the to select and configure the drawing tools in Felt.

Controller

Interfaces

Type Aliases

Element Groups

Elements

The parameters for the listener.

Properties

elementGroup

elementGroup: null |

Properties

type

type: "Image"

coordinates

coordinates: [number, number][][] = MultiLineStringGeometrySchema.shape.coordinates

imageUrl

imageUrl: string

The URL of the image that is rendered in this element

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.

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

opacity?

optional opacity: number

The opacity of the image, between 0 and 1.

Default

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.

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.

type

type: "Image"

imageUrl

imageUrl: string

The URL of the image that is rendered in this element

opacity

opacity: number

The opacity of the image, between 0 and 1.

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

Properties

id

id: string

The unique identifier for the element.

type

type: "Image"

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.

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

coordinates?

optional coordinates: [number, number][][] = MultiLineStringGeometrySchema.shape.coordinates

imageUrl?

optional imageUrl: string

The URL of the image that is rendered in this element

opacity?

optional opacity: number

The opacity of the image, between 0 and 1.

Default

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.

type

type: "Link"

url

url: string

The URL of the link that is rendered in this 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

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.

features

features: []

The vector features that are under the cursor.

rasterValues

rasterValues: []

The raster pixel values that are under the cursor.

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

resolution

resolution: number

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

attribute

attribute: string

The attribute to use for the precomputed calculation.

This must be a numeric attribute;

type

type: "h3"

The type of grid to use for the precomputed calculation.

method

method: "avg" | "max" | "min" | "sum"

The method to use for the precomputed calculation.

One bin from the response from the 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.

A single category from the response from the 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.

All the different sources for boundaries for a layer, including their combined result.

Properties

spatialFilters

spatialFilters: null |

Boundaries set by drawing spatial filters on the map.

When there are multiple spatial filters, they are combined into a multi-polygon.

ephemeral

ephemeral: null |

Boundaries that are set ephemerally by viewers in their own session.

These are the filters that are set when the method is called. There is no way to set these in the Felt UI - they can only be set using the SDK.

combined

combined: null |

The combined result of all the boundaries set on the layer.

Each different source of boundary is intersected to produce the combined result.

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

style

style:

Filters that are set in the layer's style. These are the lowest level of filters, and can only be set by editing the map.

components

components:

Filters that are set in the layer's components, which are interactive elements in the legend. These can be set by viewers for their own session, but their default value can be set by the map creator.

ephemeral

ephemeral:

Filters that are set ephemerally by viewers in their own session.

These are the filters that are set when the method is called. There is no way to set these in the Felt UI - they can only be set using the SDK.

combined

combined:

The combined result of all the filters set on the layer.

The common schema for all attributes.

Properties

id

id: string

The unique identifier for this attribute.

This can be used to fetch statistics, categories, histograms etc. for this attribute via the , , and methods.

displayName

displayName: string

The human-readable name of this attribute.

detailedType

detailedType: string

The specific data type of this attribute, providing more detail than the basic type.

For instance, a numeric attribute might be "INTEGER", "FLOAT, etc.

distinctCount

distinctCount: number

The number of distinct values present for this attribute across all features.

GeometryFilter: | | | []

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

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

type

type: "geoJsonFile"

Identifies this as a GeoJSON file source.

file

file: File

The GeoJSON file for the layer.

The schema that describes the structure of the features in a layer.

Remarks

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.

Properties

featureCount

featureCount: number

The total number of features in the layer.

attributes

attributes: []

Array of attribute schemas describing the properties available on features in this layer.

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

Properties

layerId

layerId: string

The ID of the layer to get categories from.

attribute

attribute: string

The attribute to use for categorization.

limit?

optional limit: number

The maximum number of categories to return.

filters?

optional filters:

Attribute filters for the features to include when calculating the categories.

boundary?

optional boundary:

The spatial boundary for the features to include when calculating the categories.

values?

optional values:

Configuration for filtering and aggregating values while preserving the full set of categories in the results.

This is particularly useful when you want to compare different subsets of data while maintaining consistent categories. For example:

• Show all building types in a city, but only count recent buildings in each type

• Keep all neighborhood categories but only sum up residential square footage

Unlike top-level filters which affect both what categories appear AND their values, filters in this configuration only affect the values while keeping all possible categories in the results.

The schema for a text attribute on a layer.

Properties

id

id: string

The unique identifier for this attribute.

This can be used to fetch statistics, categories, histograms etc. for this attribute via the , , and methods.

displayName

displayName: string

The human-readable name of this attribute.

detailedType

detailedType: string

The specific data type of this attribute, providing more detail than the basic type.

For instance, a numeric attribute might be "INTEGER", "FLOAT, etc.

distinctCount

distinctCount: number

The number of distinct values present for this attribute across all features.

type

type: "text"

Indicates this is a text attribute.

sampleValues

sampleValues: { value: string; count: number; }[]

A small sample of string values for this attribute and their frequency.

The source of a raster layer's data.

Properties

imageTileTemplateUrl

imageTileTemplateUrl: string

A URL template for fetching image tiles for the raster.

encodedTileTemplateUrl

encodedTileTemplateUrl: string

A URL template for fetching encoded tiles for the raster.

The encoded raster value can be calculated from the red, green, and blue values of the pixel using the following formula:

or

bands

bands: []

List of encoded raster bands

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

Type Parameters

Properties

layerId

layerId: string

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

aggregation

aggregation: <T>

Specifies how to aggregate values within each category or bin. When omitted, features are counted. When specified, the chosen calculation (avg, sum, etc.) is performed on the specified attribute.

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.

Layer: | |

The value you need to pass to

Properties

id

id: string

The id of the layer to update.

shownInLegend?

optional shownInLegend: boolean

Changes whether the layer is shown in the legend.

legendDisplay?

optional legendDisplay: "default" | "nameOnly"

Changes the layer's legend display mode.

See for more details.

name?

optional name: string

Changes the name of the layer.

caption?

optional caption: string

Changes the caption of the layer.

description?

optional description: string

Changes the description of the layer.

bounds?

optional bounds: [number, number, number, number]

Changes the bounds of the layer.

style?

optional style: object

The style of the layer.

source?

optional source: | |

Updates the source of the layer.

Only layers that have a GeoJSON source can have their source udpated.

For URL sources, if you pass the same URL again it will cause the data to be refreshed.

Constraints for the 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.

Properties

type

type: "Highlighter"

coordinates

coordinates: LngLatTuple[][][]

A multipolygon describing the area that is highlighted.

If renderHoles is set to false, only the outer ring of each polygon will be rendered, filling in the area inside the highlighted region.

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

"#ABC123";
"rgb(255, 0, 0)";
"hsl(200, 100%, 50%)";

Default

"#C93535"

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

"default"

renderHoles?

optional renderHoles: boolean

Whether to render the holes of the highlighted area.

Default

false

opacity?

optional opacity: number

The opacity of the highlighter, between 0 and 1.

Default

0.5

Properties

type

type: "Marker"

coordinates

coordinates: LngLatTuple[][]

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

"#ABC123";
"rgb(255, 0, 0)";
"hsl(200, 100%, 50%)";

Default

"#C93535"

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

"default"

opacity?

optional opacity: number

The opacity of the marker, between 0 and 1.

Default

1

size?

optional size: number

The size of the marker, used in conjunction with the zoom to determine the actual size of the marker.

Default

10

zoom?

optional zoom: number

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

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

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

"#ABC123";
"rgb(255, 0, 0)";
"hsl(200, 100%, 50%)";

Default

"#C93535"

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.

type

type: "Marker"

opacity

opacity: number

The opacity of the marker, between 0 and 1.

Default

1

size

size: number

The size of the marker, used in conjunction with the zoom to determine the actual size of the marker.

Default

10

zoom

zoom: number

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

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

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

"default"

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]

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: GridConfig

The grid configuration to use for the precomputed calculation.

filters?

optional filters: Filters

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

boundary?

optional boundary: GeometryFilter

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

The schema for a boolean attribute on a layer.

Properties

id

id: string

The unique identifier for this attribute.

This can be used to fetch statistics, categories, histograms etc. for this attribute via the LayersController.getCategoryData, LayersController.getHistogramData, and LayersController.getAggregates methods.

displayName

displayName: string

The human-readable name of this attribute.

detailedType

detailedType: string

The specific data type of this attribute, providing more detail than the basic type.

For instance, a numeric attribute might be "INTEGER", "FLOAT, etc.

distinctCount

distinctCount: number

The number of distinct values present for this attribute across all features.

type

type: "boolean"

Indicates this is a boolean attribute.

sampleValues

sampleValues: { value: boolean; count: number; }[]

A representative sample of boolean values for this attribute and their frequency.

Properties

id

id: string

A string identifying the layer group.

name

name: string

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

caption

caption: null | string

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

layerIds

layerIds: string[]

The ids of the layers in the layer group.

Remarks

You can use these ids to get the full layer objects via the `getLayers` method.

visible

visible: boolean

Whether the layer group is visible or not.

shownInLegend

shownInLegend: boolean

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

bounds

bounds: null | [number, number, number, number]

The bounding box of the layer group in [west, south, east, north] order.

FeltBoundary

The schema for a date attribute on a layer.

Properties

id

id: string

The unique identifier for this attribute.

This can be used to fetch statistics, categories, histograms etc. for this attribute via the LayersController.getCategoryData, LayersController.getHistogramData, and LayersController.getAggregates methods.

displayName

displayName: string

The human-readable name of this attribute.

detailedType

detailedType: string

The specific data type of this attribute, providing more detail than the basic type.

For instance, a numeric attribute might be "INTEGER", "FLOAT, etc.

distinctCount

distinctCount: number

The number of distinct values present for this attribute across all features.

type

type: "date"

Indicates this is a date attribute.

min

min: string

The earliest date present for this attribute in truncated ISO8601 format (YYYY-MM-DD).

max

max: string

The latest date present for this attribute in truncated ISO8601 format (YYYY-MM-DD).

sampleValues

sampleValues: { value: string; count: number; }[]

A representative sample of date values for this attribute and their frequency.

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.

A raster pixel value for a specific layer.

Properties

value

value: number

The value of the pixel.

layerId

layerId: string

The ID of the layer that the pixel belongs to.

categoryName

categoryName: null | string

The name of the category that the pixel belongs to.

color

color: null | { r: number; g: number; b: number; a: number; }

The color of the pixel. Each value is between 0 and 255.

The identifier for a legend item. It is a compound key of the layer to which the legend item belongs and the legend item's own id.

Properties

id

id: string

The id of the legend item.

layerId

layerId: string

The id of the layer the legend item belongs to.

The parameters for the `onLegendItemChange` listener.

Properties

legendItem

legendItem: null | LegendItem

The new data for the legend item or null if the legend item was removed.

The schema for a numeric attribute on a layer.

Properties

id

id: string

The unique identifier for this attribute.

This can be used to fetch statistics, categories, histograms etc. for this attribute via the LayersController.getCategoryData, LayersController.getHistogramData, and LayersController.getAggregates methods.

displayName

displayName: string

The human-readable name of this attribute.

detailedType

detailedType: string

The specific data type of this attribute, providing more detail than the basic type.

For instance, a numeric attribute might be "INTEGER", "FLOAT, etc.

distinctCount

distinctCount: number

The number of distinct values present for this attribute across all features.

type

type: "numeric"

Indicates this is a numeric attribute.

sampleValues

sampleValues: { value: number; count: number; }[]

A small sample of values for this attribute and their frequency.

min

min: number

The minimum value present for this attribute across all features.

max

max: number

The maximum value present for this attribute across all features.

Constraints for legend items. If nothing is passed, all legend items will be returned.

Properties

ids?

optional ids: { id: string; layerId: string; }[]

Array of legend item identifiers to constrain by.

layerIds?

optional layerIds: string[]

Array of layer ids to constrain legend items by.

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

// A simple filter with a single condition
const filter = [
  ["AREA", "gt", 30_000],
  "and",
  ["COLOR", "eq", "red"]
]

// A complex filter with multiple conditions
const filter = [
  ["AREA", "gt", 30_000],
  "and",
  [
    ["COLOR", "eq", "red"],
    "or",
    ["TYPE", "eq", "residential"]
  ]
]

Defines how to aggregate a value across features in a layer with multiple aggregations returned at once.

Type Parameters

Properties

methods

methods: T[]

The operations to use on the values from the features in the layer

attribute?

optional attribute: string

The attribute ID to use for the aggregation when aggregations other than "count" are used.

This can be omitted if the only aggregation is "count", but must be a numeric attribute otherwise.

Use getLayerSchema to get the attributes available for a layer.

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.

type

type: "Highlighter"

renderHoles

renderHoles: boolean

Whether to render the holes of the highlighted area.

Default

opacity

opacity: number

The opacity of the highlighter, between 0 and 1.

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

Properties

id

id: string

The unique identifier for the element.

type

type: "Marker"

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

opacity?

optional opacity: number

The opacity of the marker, between 0 and 1.

Default

size?

optional size: number

The size of the marker, used in conjunction with the zoom to determine the actual size of the marker.

Default

zoom?

optional zoom: number

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

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

coordinates?

optional coordinates: [][]

Properties

type

type: "Text"

text

text: string

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.

align?

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

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

Default

style?

optional style: "italic" | "light" | "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.

If this is omitted, the text will be placed at the center of the current viewport.

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: "Polygon"

fillOpacity

fillOpacity: number

The opacity of the polygon's fill, between 0 and 1.

Default

areaMarker

areaMarker: boolean

Whether to show an area marker on the polygon.

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

Properties

id

id: string

The unique identifier for the element.

type

type: "Polygon"

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

fillOpacity?

optional fillOpacity: number

The opacity of the polygon's fill, between 0 and 1.

Default

areaMarker?

optional areaMarker: boolean

Whether to show an area marker on the polygon.

Default

coordinates?

optional coordinates: [][]

Properties

type

type: "Polygon"

coordinates

coordinates: [][]

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

fillOpacity?

optional fillOpacity: number

The opacity of the polygon's fill, between 0 and 1.

Default

areaMarker?

optional areaMarker: boolean

Whether to show an area marker on the polygon.

Default

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.

type

type: "Place"

symbol

symbol: string

The symbol that is rendered for the Place.

This can be an emoji by using colon-enclosed characters (e.g. ":smiley:") or one of the symbols available in Felt's symbol library.

You can see the available symbols in the Felt UI when editing a Place by hovering a symbol and converting the tooltip to kebab-case. For example, the "Oil barrel" symbol is oil-barrel.

frame

frame: null | "frame-circle" | "frame-square"

The frame that is rendered around the Place's symbol. This is only available for non-emoji symbols.

hideLabel

hideLabel: boolean

Whether the element's label is hidden on the map. This allows you to add a name to the element and can show in popups, but not have it visible on the map.

This will also hide the faint placeholder label that is shown when an editable Place is selected.

Default

coordinates

coordinates:

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

A LayerFeature is a single geographical item in a layer.

It is intended to be a lightweight object that contains the properties of a feature, but not the geometry. It is returned by methods like and , and as part of the methods in the

The geometry can be obtained via the method, which returns a object.

Properties

id

id: string | number

The identifier of the feature, unique within the layer.

isDeterministicId

isDeterministicId: boolean

Whether the id is deterministic.

Remarks

If the id is deterministic, it means that the id can be used to reference the feature in the layer and therefore in all the SDK feature-related methods.

When the id is not deterministic, the feature cannot be referenced on SDK methods like or .

For layers created and processed on Felt servers, the feature IDs are deterministic because Felt ensures every feature is correctly identified in vector tiles. This cannot be guaranteed for layers created using a GeoJSON source on the SDK (see ) where the ID will only be deterministic if GeoJSON features have an id property.

layerId

layerId: string

The identifier of the layer that the feature belongs to.

geometryType

geometryType: "Polygon" | "MultiPolygon" | "LineString" | "MultiLineString" | "Point" | "MultiPoint" | string & {}

The type of geometry of the feature.

Remarks

Because LayerFeatures can be read from tiled features, it's possible that this geometryType won't match the geometry.type of the returned by .

For example, this may return LineString but the full feature is a MultiLineString, or, similarly Polygon here may be a MultiPolygon in the full feature.

As a result, you should treat this property as being indicative only.

bbox

bbox: undefined | [number, number, number, number]

The bounding box of the feature.

Remarks

Because LayerFeatures can be read from tiled features and considering that feature geometry can go through multiple tiles, it's possible that this is not the complete bounding box of the feature.

properties

properties:

The properties of the feature, as a bag of attributes.

LegendDisplay: "default" | "nameOnly"

Describes how the layer is displayed in the legend.

There are two display modes:

1. Default:

   • Shows layer name and caption

   • Shows representation of the layer's viz (e.g. color swatches, proportional symbols)

1. Name-only (compact display):

   • Shows only layer name and caption

   • Hides representation of the layer's viz

Properties

type

type: "Circle"

radius

radius: number

The radius of the circle in meters.

center

center: LngLatTuple

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

"#ABC123";
"rgb(255, 0, 0)";
"hsl(200, 100%, 50%)";

Default

"#C93535"

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

"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

1

strokeWidth?

optional strokeWidth: number

The width of the element's stroke in pixels.

Default

2

strokeStyle?

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

The style of the element's stroke.

Default

"solid"

radiusMarker?

optional radiusMarker: boolean

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

Default

false

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

90

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

null

fillOpacity?

optional fillOpacity: number

The opacity of the circle's fill.

Default

0.25

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

"#ABC123";
"rgb(255, 0, 0)";
"hsl(200, 100%, 50%)";

Default

"#C93535"

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

1

strokeWidth

strokeWidth: number

The width of the element's stroke in pixels.

Default

2

strokeStyle

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

The style of the element's stroke.

Default

"solid"

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

false

radiusDisplayAngle

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

90

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

null

fillOpacity

fillOpacity: number

The opacity of the circle's fill.

Default

0.25

center

center: LngLatTuple

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

"default"

Properties

id

id: string

The unique identifier for the element.

type

type: "Circle"