FeltController
Last updated
Was this helpful?
JS SDK API Reference
Last updated
Was this helpful?
This is the main interface for interacting with a Felt map.
This interface is composed of the various controllers, each having a different area of responsibility.
All the methods are listed here, but each controller is documented on its own to make it easier to find related methods and events.
.......
getElement(
id:string):Promise<null| >
Get a single element from the map by its id.
id
string
The id of the element you want to get.
Promise<null | >
The requested element.
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 andradius 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.
Text, Note and Image elements do not return geometry, so will return null.
id
string
The id of the element you want to get the geometry of.
Gets elements from the map, according to the constraints supplied. If no constraints are supplied, all elements will be returned.
constraint?
The constraints to apply to the elements returned from the map.
All elements on the map.
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.
Get an element group from the map by its id.
id
string
The requested element group.
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.
constraint?
The constraints to apply to the element groups returned from the map.
The requested element groups.
Hide or show element groups with the given ids.
visibility
Promise<void>
Create a new element on the map.
element
Update an element on the map.
element
deleteElement(
id:string):Promise<void>
Delete an element from the map.
id
string
Promise<void>
Get a single layer from the map by its id.
id
string
The id of the layer you want to get.
The requested layer.
Gets layers from the map, according to the constraints supplied. If no constraints are supplied, all layers will be returned.
constraint?
The constraints to apply to the layers returned from the map.
All layers on the map.
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.
Hide or show layers with the given ids.
visibility
Promise<void>
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.
If the style you set is invalid, you will receive an error explaining the problem in the rejected promise value.
params
{ id: string; style: object; }
-
params.id
string
The id of the layer to set the style for.
params.style
object
The style to set for the layer.
Promise<void>
Hide or show layers with the given ids from the legend.
params
Promise<void>
Adds layers to the map from file or URL sources.
params
The layer groups that were created.
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.
Update a layer by passing a subset of the layer's properties.
params
deleteLayer(
id:string):Promise<void>
Delete a layer from the map by its id.
id
string
Promise<void>
This only works for layers created via the SDK createLayersFromGeoJson method, not layers added via the Felt UI.
Get a layer group from the map by its id.
id
string
The requested layer group.
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.
constraint?
The constraints to apply to the layer groups returned from the map.
The requested layer groups.
Hide or show layer groups with the given ids.
visibility
Promise<void>
Hide or show layer groups with the given ids from the legend.
params
Promise<void>
Allows you to get the state of a single legend item.
id
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.
constraint?
Hide or show legend items with the given identifiers.
visibility
visibility.show?
visibility.hide?
Promise<void>
Get the filters for a layer.
layerId
string
The return type gives you the filters split up into the various sources that make up the overall filters for a layer.
Sets the ephemeral filters for a layer.
params
-
params.layerId
string
The layer that you want to set the filters for.
params.filters
The filters to set for the layer. This will replace any ephemeral filters that are currently set for the layer.
params.note?
string
A note to display on the layer legend when this filter is applied. When the note is shown, a reset button will also be shown, allowing the user to clear the filter.
Promise<void>
Get the spatial boundaries that are filtering a layer.
layerId
string
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.
params
-
params.layerIds
string[]
The ids of the layers to set the boundary for.
params.boundary
The boundary to set for the layer. Passing null clears the ephemeral boundary for the layer.
Promise<void>
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.
params?
The constraints to apply to the features returned from the map.
Get a feature from the map by its ID and layer ID.
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.
params
{ id: string | number; layerId: string; }
params.id
string | number
params.layerId
string
Get a list of layer features.
params
-
params.layerId
string
The ID of the layer to get features from.
params.filters?
Filters to be applied. These filters will merge with layer's own filters.
params.sorting?
Attribute to sort by.
params.boundary?
The spatial boundary to be applied.
params.search?
string
Search term to search by. Search is case-insensitive and looks for matches across all feature properties.
params.pagination?
null | string
Pagination token. It comes from either the previousPage or nextPage properties of the previous response.
The response is an object which contains:
count: the total number of features that match the query.
previousPage & nextPage: The tokens to pass in the pagination param
to navigate between pages.
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.
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.
params
{ id: string | number; layerId: string; }
params.id
string | number
params.layerId
string
Gets values from a layer grouped by a given attribute.
params
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.
Gets a histogram of values from a layer for a given attribute.
params
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.
Calculates a single aggregate value for a layer based on the provided configuration.
T extends "avg" | "max" | "min" | "sum" | "median" | "count"
params
Promise<Record<T, null | number>>
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 no aggregation is specified, it counts features. When an aggregation is provided, it performs that calculation (average, sum, etc.) on the specified attribute.
Get the schema for a layer.
layerId
string
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.
Gets the details of the map.
Gets the current selection as a list of entity identifiers.
Selects a feature on a layer. This will show the feature's popup, modal or sidebar (if configured) and highlight the feature.
params
Promise<void>
clearSelection(
params?: {features:boolean;elements:boolean; }):Promise<void>
Clears the current selection. This clears the selection of
params?
{ features: boolean; elements: boolean; }
The parameters to clear the selection. If this is not provided, both features and elements will be cleared.
params.features?
boolean
Whether to clear the features from the selection.
params.elements?
boolean
Whether to clear the elements from the selection.
Promise<void>
setTool(
tool:null|"text"|"link"|"note"|"pin"|"line"|"route"|"polygon"|"circle"|"marker"|"highlighter"):void
Sets the tool to use for drawing elements on the map.
tool
null | "text" | "link" | "note" | "pin" | "line" | "route" | "polygon" | "circle" | "marker" | "highlighter"
The tool to set.
void
getTool():
Promise<null|"text"|"link"|"note"|"pin"|"line"|"route"|"polygon"|"circle"|"marker"|"highlighter">
Gets the current tool, if any is in use.
Promise<null | "text" | "link" | "note" | "pin" | "line" | "route" | "polygon" | "circle" | "marker" | "highlighter">
The current tool, or null if no tool is in use.
onToolChange(
args: {handler: (tool:null|"text"|"link"|"note"|"pin"|"line"|"route"|"polygon"|"circle"|"marker"|"highlighter") =>void; }):VoidFunction
Listens for changes to the current tool.
args
{ handler: (tool: null | "text" | "link" | "note" | "pin" | "line" | "route" | "polygon" | "circle" | "marker" | "highlighter") => void; }
-
args.handler
(tool: null | "text" | "link" | "note" | "pin" | "line" | "route" | "polygon" | "circle" | "marker" | "highlighter") => void
This callback is called with the current tool whenever the tool changes.
VoidFunction
A function to unsubscribe from the listener
Sets the settings for the current tool.
settings
The settings to set.
void
Gets the settings for the chosen tool
tool
T
The settings for the chosen tool.
Listens for changes to the settings on all tools.
args
args.handler
VoidFunction
A function to unsubscribe from the listener
Updates the UI controls on the embedded map.
controls
The controls to update.
void
Control the on-map UI shown when interacting with features and elements.
If you add your own click, selection or hover handlers you may want to disable various parts of the Felt UI. This method allows you to control the visibility of various parts of the UI that might otherwise be shown when people click or hover on things.
This does not affect selection. That means that selectable features and elements will still be selected when clicked.
options
void
Shows a data table view for the specified layer, optionally sorted by a given attribute.
params?
params.layerId?
string
params.sorting?
Promise<void>
hideLayerDataTable():
Promise<void>
Hides the data table.
Promise<void>
Gets the current state of the viewport.
Moves the map to the specified location.
viewport
void
Gets the current state of the viewport constraints.
Constrains the map viewport so it stays inside certain bounds and/or certain zoom levels.
constraints
void
every constraint is optional
if a constraint is null, it will be removed but keeping the others
if method receives null, it will remove the constraints
Fits the map to the specified bounds.
bounds
void
Adds a listener for when an element is created.
args
-
args.handler
VoidFunction
A function to unsubscribe from the listener
Listens for when a new element is finished being created by a drawing tool.
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.
args
-
args.handler
The handler to call whenever this event fires.
VoidFunction
A function to unsubscribe from the listener
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 programatically.
args
-
args.options
{ id: string; }
-
args.options.id
string
The id of the element to listen for changes to.
args.handler
The handler that is called when the element changes.
VoidFunction
A function to unsubscribe from the listener
onElementDelete(
args: {options: {id:string; };handler: () =>void; }):VoidFunction
Adds a listener for when an element is deleted.
args
{ options: { id: string; }; handler: () => void; }
-
args.options
{ id: string; }
-
args.options.id
string
The id of the element to listen for deletions of.
args.handler
() => void
The handler that is called when the element is deleted.
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when an element group changes.
args
args.options
{ id: string; }
args.options.id
string
args.handler
VoidFunction
A function to unsubscribe from the listener
Allows you to be notified the user clicks on the map.
params
params.handler
VoidFunction
A function to unsubscribe from the listener
Allows you to be notified the user moves the mouse over the map.
params
Params for the listener
params.handler
The handler function
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when a layer changes.
args
-
args.options
{ id: string; }
-
args.options.id
string
The id of the layer to listen for changes to.
args.handler
The handler that is called when the layer changes.
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when a layer group changes.
args
args.options
{ id: string; }
args.options.id
string
args.handler
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when a legend item changes.
args
args.options
args.handler
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when a layer's filters change.
params
params.options
{ layerId: string; }
params.options.layerId
string
params.handler
VoidFunction
A function to unsubscribe from the listener
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.
Adds a listener for when a layer's spatial boundaries change.
params
-
params.options
{ layerId: string; }
-
params.options.layerId
string
The id of the layer to listen for boundary changes on.
params.handler
A function that is called when the boundaries change.
VoidFunction
A function to unsubscribe from the listener
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.
Adds a listener for when the selection changes.
params
params.handler
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when the viewport changes.
args
-
args.handler
This callback is called with the current viewport state whenever the viewport changes.
VoidFunction
A function to unsubscribe from the listener
Adds a listener for when the viewport move ends, which is when the user stops dragging or zooming the map, animations have finished, or inertial dragging ends.
args
args.handler
VoidFunction
A function to unsubscribe from the listener
onMapIdle(
args: {handler: () =>void; }):VoidFunction
Adds a listener for when the map is idle, which is defined as:
No transitions are in progress
The user is not interacting with the map, e.g. by panning or zooming
All tiles for the current viewport have been loaded
Any fade transitions (e.g. for labels) have completed
args
{ handler: () => void; }
args.handler
() => void
VoidFunction
A function to unsubscribe from the listener
readonlyiframe:null|HTMLIFrameElement
The iframe element containing the Felt map, if it is an embedded map.
getElementGeometry(id: string): Promise<null | >
Promise<null | >
getElements(constraint?: ): Promise<(null | )[]>
Promise<(null | )[]>
getElementGroup(id: string): Promise<null | >
Promise<null | >
getElementGroups(constraint?: ): Promise<(null | )[]>
Promise<(null | )[]>
setElementGroupVisibility(visibility: ): Promise<void>
createElement(element: ): Promise<>
Promise<>
updateElement(element: ): Promise<>
Promise<>
getLayer(id: string): Promise<null | >
Promise<null | >
getLayers(constraint?: ): Promise<(null | )[]>
Promise<(null | )[]>
setLayerVisibility(visibility: ): Promise<void>
See the for details on how to read and write styles.
setLayerLegendVisibility(params: ): Promise<void>
createLayersFromGeoJson(params: ): Promise<null | { layerGroup: ; layers: []; }>
Promise<null | { layerGroup: ; layers: []; }>
updateLayer(params: ): Promise<>
Note that not all properties can be updated, so check the type to see which properties can be updated.
Promise<>
getLayerGroup(id: string): Promise<null | >
Promise<null | >
getLayerGroups(constraint?: ): Promise<(null | )[]>
Promise<(null | )[]>
setLayerGroupVisibility(visibility: ): Promise<void>
setLayerGroupLegendVisibility(params: ): Promise<void>
getLegendItem(id: ): Promise<null | >
Promise<null | >
getLegendItems(constraint?: ): Promise<(null | )[]>
Promise<(null | )[]>
setLegendItemVisibility(visibility: { show: []; hide: []; }): Promise<void>
{ show: []; hide: []; }
[]
[]
getLayerFilters(layerId: string): Promise<null | >
Promise<null | >
setLayerFilters(params: { layerId: string; filters: ; note: string; }): Promise<void>
{ layerId: string; filters: ; note: string; }
getLayerBoundaries(layerId: string): Promise<null | >
Promise<null | >
setLayerBoundary(params: { layerIds: string[]; boundary: null | ; }): Promise<void>
Set the boundary for one or more layers.
{ layerIds: string[]; boundary: null | ; }
null |
getRenderedFeatures(params?: ): Promise<[]>
Promise<[]>
getFeature(params: { id: string | number; layerId: string; }): Promise<null | >
The response is a object, which does not include the geometry of the feature.
Promise<null | >
getFeatures(params: { layerId: string; filters: ; sorting: ; boundary: ; search: string; pagination: null | string; }): Promise<{ features: []; count: number; previousPage: null | string; nextPage: null | string; }>
{ layerId: string; filters: ; sorting: ; boundary: ; search: string; pagination: null | string; }
Promise<{ features: []; count: number; previousPage: null | string; nextPage: null | string; }>
features: list of objects, which does not include
the geometry of the feature but it does include its bounding box.
getGeoJsonFeature(params: { id: string | number; layerId: string; }): Promise<null | >
Promise<null | >
getCategoryData(params: ): Promise<[]>
Promise<[]>
getHistogramData(params: ): Promise<[]>
Promise<[]>
getAggregates<T>(params: <T>): Promise<Record<T, null | number>>
<T>
getLayerSchema(layerId: string): Promise<>
Promise<>
getMapDetails(): Promise<>
Promise<>
getSelection(): Promise<[]>
Promise<[]>
selectFeature(params: ): Promise<void>
setToolSettings(settings: ): void
getToolSettings<T>(tool: T): Promise<[T]>
T extends keyof
Promise<[T]>
onToolSettingsChange(args: { handler: (settings: ) => void; }): VoidFunction
{ handler: (settings: ) => void; }
(settings: ) => void
updateUiControls(controls: ): void
setOnMapInteractionsUi(options: ): void
showLayerDataTable(params?: { layerId: string; sorting: ; }): Promise<void>
{ layerId: string; sorting: ; }
getViewport(): Promise<>
Promise<>
setViewport(viewport: ): void
getViewportConstraints(): Promise<null | >
Promise<null | >
setViewportConstraints(constraints: null | Partial<>): void
null | Partial<>
fitViewportToBounds(bounds: ): void
onElementCreate(args: { handler: (change: ) => void; }): VoidFunction
{ handler: (change: ) => void; }
(change: ) => void
The handler that is called when an element is created. This will fire when elements are created programatically, 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.
onElementCreateEnd(args: { handler: (params: { element: ; }) => void; }): VoidFunction
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.
{ handler: (params: { element: ; }) => void; }
(params: { element: ; }) => void
onElementChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction
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.
{ options: { id: string; }; handler: (change: ) => void; }
(change: ) => void
onElementGroupChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction
{ options: { id: string; }; handler: (change: ) => void; }
(change: ) => void
onPointerClick(params: { handler: (event: ) => void; }): VoidFunction
{ handler: (event: ) => void; }
(event: ) => void
onPointerMove(params: { handler: (event: ) => void; }): VoidFunction
{ handler: (event: ) => void; }
(event: ) => void
onLayerChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction
{ options: { id: string; }; handler: (change: ) => void; }
(change: ) => void
onLayerGroupChange(args: { options: { id: string; }; handler: (change: ) => void; }): VoidFunction
{ options: { id: string; }; handler: (change: ) => void; }
(change: ) => void
onLegendItemChange(args: { options: ; handler: (change: ) => void; }): VoidFunction
{ options: ; handler: (change: ) => void; }
(change: ) => void
onLayerFiltersChange(params: { options: { layerId: string; }; handler: (change: ) => void; }): VoidFunction
{ options: { layerId: string; }; handler: (change: ) => void; }
(change: ) => void
onLayerBoundariesChange(params: { options: { layerId: string; }; handler: (boundaries: null | ) => void; }): VoidFunction
{ options: { layerId: string; }; handler: (boundaries: null | ) => void; }
(boundaries: null | ) => void
onSelectionChange(params: { handler: (change: { selection: []; }) => void; }): VoidFunction
{ handler: (change: { selection: []; }) => void; }
(change: { selection: []; }) => void
onViewportMove(args: { handler: (viewport: ) => void; }): VoidFunction
{ handler: (viewport: ) => void; }
(viewport: ) => void
onViewportMoveEnd(args: { handler: (viewport: ) => void; }): VoidFunction
{ handler: (viewport: ) => void; }
(viewport: ) => void