Felt JS SDK

My Felt app

{/* the map container — remember to give it a height in your CSS */}

{/* a component that uses the Felt controller */}

); } ```

useFeltEmbed implementation

```typescript import { Felt, FeltController, FeltEmbedOptions, Layer, } from "@feltmaps/js-sdk"; import React from "react"; export function useFeltEmbed(mapId: string, embedOptions: FeltEmbedOptions) { const [felt, setFelt] = React.useState(null); const hasLoadedRef = React.useRef(false); const mapRef = React.useRef(null); React.useEffect(() => { async function loadFelt() { if (hasLoadedRef.current) return; if (!mapRef.current) return; hasLoadedRef.current = true; const felt = await Felt.embed(mapRef.current, mapId, embedOptions); setFelt(felt); } loadFelt(); }, []); return { felt, mapRef, }; } ``` A few things worth knowing about this hook: * The `hasLoadedRef` guard exists because React's Strict Mode runs effects twice in development — without it you would embed two iframes. * The hook embeds once for the component's lifetime: changing `mapId` after mount won't re-embed. If you need to switch maps, remount the component (for example with a `key={mapId}` prop).

### Getting live data A common use case for building apps on Felt is to be notified when entities are updated. The main example of this is when you want to change the visibility of say a layer, and have your own UI reflect that change. Rather than keeping track of the visibility of entities yourself, you can use the Felt SDK to listen for changes to the visibility of entities. Here is an example of how you might do this for layers assuming you already have a reference to a `Layer` object, e.g. from calling `felt.getLayers()`: ```typescript export function useLiveLayer(felt: FeltController, initialLayer: Layer) { // start with the layer we were given const [currentLayer, setLayer] = React.useState(initialLayer); // listen for changes to the layer and update our state accordingly // (onLayerChange returns its unsubscribe function, so returning it // from the effect cleans up the listener on unmount) React.useEffect(() => { return felt.onLayerChange({ options: { id: initialLayer.id }, handler: ({ layer }) => setLayer(layer), }); }, [felt, initialLayer.id]); // return the live layer return currentLayer; } ``` # Map interactions and viewport The Felt SDK provides methods to control the map's viewport (the visible area of the map) and handle user interactions like clicking and hovering on the viewport. ## Working with the viewport ### Getting viewport state You can get the current viewport state using `getViewport()`: ```typescript const viewport = await felt.getViewport(); console.log(viewport.center); // { latitude: number, longitude: number } console.log(viewport.zoom); // number ``` ### Setting the viewport There are two main ways to set the viewport: moving to a specific point, or fitting to bounds. #### Moving to a point Use `setViewport()` to move the map to a specific location: ```typescript felt.setViewport({ center: { latitude: 37.7749, longitude: -122.4194 }, zoom: 12 }); ``` #### Fitting to bounds Use `fitViewportToBounds()` to adjust the viewport to show a specific rectangular area: ```typescript felt.fitViewportToBounds({ bounds: [ west, // minimum longitude south, // minimum latitude east, // maximum longitude north // maximum latitude ] }); ``` ### Responding to viewport changes To stay in sync with viewport changes, use the `onViewportMove` method: ```typescript const unsubscribe = felt.onViewportMove({ handler: (viewport) => { console.log("New center:", viewport.center); console.log("New zoom:", viewport.zoom); } }); // Clean up when done unsubscribe(); ``` ## Map interactions ### Click events Listen for click events on the map using `onPointerClick`: ```typescript const unsubscribe = felt.onPointerClick({ handler: (event) => { // Location of the click console.log("Click location:", event.coordinate); // Features under the click console.log("Clicked features:", event.features); // The pixel coordinates of the cursor, measured from the top left corner of the map DOM element. console.log("Screen coordinates:", event.point); // Values from raster layers under the pointer. // Always an array - empty when no raster layers are hit. for (const {value, categoryName, color, layerId} of event.rasterValues) { console.log("Raster value:", value, categoryName); } } }); ``` ### Hover events Track mouse movement over the map using `onPointerMove`: ```typescript const unsubscribe = felt.onPointerMove({ handler: (event) => { // Current mouse location console.log("Mouse location:", event.coordinate); // Features under the cursor console.log("Hovered features:", event.features); // The pixel coordinates of the cursor, measured from the top left corner of the map DOM element. console.log("Screen coordinates:", event.point); // Values from raster layers under the pointer. // Always an array - empty when no raster layers are hit. for (const {value, categoryName, color, layerId} of event.rasterValues) { console.log("Raster value:", value, categoryName); } } }); ``` ## Best practices 1. **Cleanup**: Always store and call unsubscribe functions when you're done listening for events: ```typescript const unsubscribe = felt.onPointerMove({ handler: (event) => { // Handle event... } }); // Later, when you're done: unsubscribe(); ``` 2. **Throttling**: For pointer move events, consider throttling your handler if you're doing expensive operations: ```typescript import { throttle } from "lodash"; felt.onPointerMove({ handler: throttle((event) => { // Handle frequent mouse moves... }, 100) // Limit to once every 100ms }); ``` By using these viewport controls and interaction handlers, you can create rich, interactive experiences with your Felt map. # Working with selection The Felt SDK provides functionality for reading the current selection state and selecting features on the map programmatically. This is useful for building interactive experiences that respond to data analysis or user interactions. ## Selecting features Features are individual data points within layers. You can select features programmatically using the [`selectFeature()`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#selectfeature) method. **Only one feature can be selected at a time** - selecting a new feature will replace the current selection. ```typescript await felt.selectFeature({ id: "feature-123", layerId: "buildings-layer" }); ``` The [`selectFeature()`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#selectfeature) method accepts options to control the selection behavior: ```typescript await felt.selectFeature({ id: "feature-123", layerId: "buildings-layer", showPopup: false, // Whether to show the feature popup (default: true) fitViewport: { maxZoom: 15 } // Fit viewport to feature with zoom limit }); ``` * `showPopup` (boolean, default: `true`) - Whether to display the feature information popup * `fitViewport` (boolean | `{ maxZoom: number }`, default: `true`) - Whether to fit the viewport to the feature. Can be `true`, `false`, or an object with `maxZoom` to limit the zoom level used. ## Reading selection You can get the current selection state using [`getSelection()`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#getselection). This returns an array of [`EntityNode`](https://developers.felt.com/js-sdk-api-reference/selection/entitynode) objects, each representing a selected entity. The selection can include various types of entities at the same time, such as annotations and features: ```typescript const selection = await felt.getSelection(); console.log(`${selection.length} items selected`); selection.forEach(node => { switch(node.type) { case 'feature': console.log('Selected feature:', node.entity.id, 'from layer:', node.entity.layerId); break; case 'element': console.log('Selected element:', node.entity.name || node.entity.type); break; } }); ``` ## Clearing selection Remove current selections using [`clearSelection()`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#clearselection): ```typescript // Clear all selections await felt.clearSelection(); // Clear specific types of selections await felt.clearSelection({ features: true, // Clear feature selections elements: false // Keep element selections }); ``` ## Reacting to selection changes To stay in sync with selection changes, use the [`onSelectionChange()`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#onselectionchange) method: ```typescript const unsubscribe = felt.onSelectionChange({ handler: ({ selection }) => { // selection is an array of EntityNode objects console.log("Selected entities:", selection); // Check what's selected selection.forEach(node => { console.log("Entity type:", node.type); console.log("Entity ID:", node.entity.id); }); } }); // Don't forget to clean up when you're done unsubscribe(); ``` ## Best practices 1. **Clean up listeners**: Always store and call the unsubscribe function when you no longer need to listen for selection changes: ```typescript const unsubscribe = felt.onSelectionChange({ handler: ({ selection }) => { // Handle selection... } }); // Later, when you're done: unsubscribe(); ``` 2. **Handle empty selection**: Remember that the selection array might be empty if nothing is selected: ```typescript const unsubscribe = felt.onSelectionChange({ handler: ({ selection }) => { if (selection.length === 0) { console.log("Nothing is selected"); return; } // Handle selection... } }); ``` By following these patterns, you can build robust interactions based on what users select in your Felt map. # Hiding and showing The Felt SDK provides methods to control the visibility of various entities like layers, layer groups, annotation groups, and legend items. These methods are designed to efficiently handle bulk operations. ## Understanding visibility requests All visibility methods use a consistent structure that allows both showing and hiding entities in a single call: ```typescript { show?: string[], // IDs of entities to show hide?: string[] // IDs of entities to hide } ``` ### Layers Control visibility of layers using `setLayerVisibility`: ```typescript felt.setLayerVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] }); ``` ### Layer groups Control visibility of layer groups using `setLayerGroupVisibility`: ```typescript felt.setLayerGroupVisibility({ show: ["group-1", "group-2"], hide: ["group-3"] }); ``` ### Annotation groups Similarly, control annotation group visibility with `setElementGroupVisibility`: ```typescript felt.setElementGroupVisibility({ show: ["points-group"], hide: ["lines-group", "polygons-group"] }); ``` ### Legend items Legend items require both a layer ID and an item ID to identify them. Use `setLegendItemVisibility`: ```typescript felt.setLegendItemVisibility({ show: [ { layerId: "layer-1", id: "item-1" }, { layerId: "layer-1", id: "item-2" } ], hide: [ { layerId: "layer-1", id: "item-3" } ] }); ``` ## Common use cases ### Focusing on a single layer To focus on a single layer by hiding all others, first get all layers and then use their IDs: ```typescript const layers = await felt.getLayers(); const targetLayerId = "important-layer"; felt.setLayerVisibility({ show: [targetLayerId], hide: layers .map(layer => layer?.id) .filter(id => id && id !== targetLayerId) }); ``` ### Toggling visibility When implementing a toggle, you can use empty arrays for the operation you don't need: ```typescript function toggleLayer(layerId: string, visible: boolean) { felt.setLayerVisibility({ show: visible ? [layerId] : [], hide: visible ? [] : [layerId] }); } ``` ## Best practices 1. **Batch operations**: Use a single call with multiple IDs rather than making multiple calls: ```typescript // Better approach felt.setLayerVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3", "layer-4"] }); // Less efficient approach felt.setLayerVisibility({ show: ["layer-1"] }); felt.setLayerVisibility({ show: ["layer-2"] }); felt.setLayerVisibility({ hide: ["layer-3"] }); felt.setLayerVisibility({ hide: ["layer-4"] }); ``` 2. **Omit unused properties**: When you only need to show or hide, omit the unused property rather than including it with an empty array: ```typescript // Do this felt.setLayerVisibility({ show: ["layer-1"] }); ``` # Working with layers The Felt SDK allows you to add GeoJSON data to your maps from various sources: * Remote URLs * Local files * Programmatically generated GeoJSON data GeoJSON layers created via the SDK are temporary and session-specific - they're not permanently added to the map and won't be visible to other users. When creating a GeoJSON layer, you can specify different styles for each geometry type (Point, Line, Polygon) that might be found in the source. Each geometry type will create its own layer. It's important to note that GeoJSON layers added via the SDK have limited capabilities compared to regular Felt layers - they cannot be filtered, nor can statistics be fetched for them. ## Creating GeoJSON layers Use the [`createLayersFromGeoJson`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#createlayersfromgeojson) method to add GeoJSON layers to your map. This method accepts different source types depending on where your GeoJSON data comes from. ### From a URL To create a layer from a GeoJSON file at a remote URL: ```javascript const layerResult = await felt.createLayersFromGeoJson({ source: { type: "geoJsonUrl", url: "https://example.com/data/neighborhoods.geojson", // Optional: Auto-refresh every 30 seconds refreshInterval: 30000 }, name: "Neighborhoods", caption: "Neighborhood boundaries for the city", // Optional description: "This layer shows the official neighborhood boundaries" // Optional }); if (layerResult) { console.log("Created layer group:", layerResult.layerGroup); console.log("Created layers:", layerResult.layers); } ``` ### From a local file To create a layer from a GeoJSON file on the user's device: ```javascript // Assuming you have a File object from a file input const fileInput = document.getElementById('geojson-upload'); const file = fileInput.files[0]; const layerResult = await felt.createLayersFromGeoJson({ source: { type: "geoJsonFile", file: file }, name: "User Uploaded Data" }); if (layerResult) { // Store the layer ID for later reference const layerId = layerResult.layers[0].id; } ``` ### From GeoJSON data To create a layer from GeoJSON data that you've generated or processed in your application. This approach is useful when you need to dynamically generate GeoJSON data based on user interactions or other app states: ```javascript const geojsonData = { type: "FeatureCollection", features: [ { type: "Feature", geometry: { type: "Point", coordinates: [-122.4194, 37.7749] }, properties: { name: "San Francisco", population: 874961 } }, // Additional features... ] }; const layerResult = await felt.createLayersFromGeoJson({ source: { type: "geoJsonData", data: geojsonData }, name: "Dynamic Points" }); ``` ## Styling by geometry type When creating GeoJSON layers, you can specify different styles for each geometry type that might be found in your data. The SDK will create separate layers for each geometry type: ```javascript const layerResult = await felt.createLayersFromGeoJson({ name: "Styled Features", source: { type: "geoJsonUrl", url: "https://example.com/data/mixed-features.geojson" }, geometryStyles: { Point: { paint: { color: "red", size: 8 } }, Line: { paint: { color: "blue", size: 4 }, config: { labelAttribute: ["name"] }, label: { minZoom: 0 } }, Polygon: { paint: { color: "green", strokeColor: "darkgreen", fillOpacity: 0.5 } } } }); ``` Each style should be a valid [FSL](/felt-style-language/getting-started) (Felt Style Language) style. If you don't specify styles, Felt will apply default styles based on the geometry type. ## Deleting layers To remove a GeoJSON layer: ```javascript await felt.deleteLayer("layer-1"); ``` Note that this only works for layers created via the SDK's `createLayersFromGeoJson` method, not for layers added through the Felt UI. ## Refreshing GeoJSON layers For GeoJSON layers created from URLs, you can set automatic refreshing: **At Creation Time**: By setting the `refreshInterval` parameter when creating the layer. The `refreshInterval` parameter is optional and specifies how frequently (in milliseconds) the layer should be automatically refreshed from the URL. Valid values range from 250ms to 5 minutes (300,000ms). If set to `null` or omitted, the layer won't refresh automatically. ```javascript const layerResult = await felt.createLayersFromGeoJson({ source: { type: "geoJsonUrl", url: "https://example.com/data/realtime-sensors.geojson", refreshInterval: 60000 // Refresh every minute }, name: "Live Sensor Data" }); ``` **Manual refresh**: Replace the `source` property of any layer you have created, using the [`updateLayer`](https://developers.felt.com/js-sdk-api-reference/layers/layerscontroller#updatelayer) method to update the source data: ```javascript await felt.updateLayer({ id: layer.id, source: { type: "geoJsonData", data: updatedFeatureCollection, }, }); ``` # Layer filters The Felt SDK allows you to filter which features are visible in a layer using expressions that evaluate against feature properties. Filters can come from different sources and are combined to determine what's visible. Note that filters only work on layers that have been uploaded to and processed by Felt — layers created at runtime with [`createLayersFromGeoJson`](/js-sdk/working-with-layers) cannot be filtered. By understanding how filters work and combine, you can create dynamic views of your data that respond to user interactions and application state. ## Understanding filter sources Layer filters can come from multiple sources, which are combined to create the final filter: 1. **Style filters**: Set by the map creator in the Felt UI 2. **Component filters**: Set through interactive legend components 3. **Ephemeral filters**: Set temporarily through the SDK You can inspect these different filter sources using `getLayerFilters`: ```typescript const filters = await felt.getLayerFilters("layer-1"); console.log(filters.style); // Base filters from the layer style console.log(filters.components); // Filters from legend components console.log(filters.ephemeral); // Filters set through the SDK console.log(filters.combined); // The final result of combining all filters ``` ## Setting filters Use `setLayerFilters` to apply ephemeral filters to a layer: ```typescript felt.setLayerFilters({ layerId: "layer-1", filters: ["POPULATION", "gt", 1000000] }); ``` This replaces any ephemeral filters currently set on the layer. You can also pass an optional `note` — a message shown on the layer legend while the filter is applied, along with a reset button that lets the user clear it: ```typescript felt.setLayerFilters({ layerId: "layer-1", filters: ["POPULATION", "gt", 1000000], note: "Showing cities with over 1M residents", }); ``` ### Filter operators The following operators are available: * Comparison: `lt` (less than), `gt` (greater than), `le` (less than or equal), `ge` (greater than or equal), `eq` (equal), `ne` (not equal) * Text: `cn` (contains), `nc` (does not contain) * Boolean: `and`, `or` * Lookup: `in` (contained in list), `ni` (not contained in list) * Null checks: `is` / `isnt` (match against `null`) See [the filters block](/felt-style-language/style-definition-blocks/the-filters-block) for more details on filter operators. ### Compound filters You can combine multiple conditions using boolean operators: ```typescript felt.setLayerFilters({ layerId: "layer-1", filters: [ ["POPULATION", "gt", 1000000], "and", ["COUNTRY", "eq", "USA"] ] }); ``` ## Practical example: Filtering by selected feature Here's a common use case where we filter a layer to show only features that match a property of a selected feature: ```typescript // Listen for selection changes felt.onSelectionChange({ handler: async ({ selection }) => { // Find the first selected feature const selectedFeature = selection.find(node => node.type === "feature"); if (selectedFeature) { // Get the state code from the selected feature const stateCode = selectedFeature.entity.properties.STATE_CODE; // Filter the counties layer to show only counties in the selected state felt.setLayerFilters({ layerId: "counties-layer", filters: ["STATE_CODE", "eq", stateCode] }); } else { // Clear the filter when nothing is selected felt.setLayerFilters({ layerId: "counties-layer", filters: null }); } } }); ``` ## Best practices 1. **Clear filters**: Set filters to `null` to remove them entirely: ```typescript felt.setLayerFilters({ layerId: "layer-1", filters: null }); ``` 2. **Check existing filters**: Remember that your ephemeral filters combine with existing style and component filters: ```typescript const filters = await felt.getLayerFilters("layer-1"); // Check if there are any style filters before adding ephemeral ones if (filters.style) { console.log("This layer already has style filters"); } ``` 3. **Type safety**: Use TypeScript to ensure your filter expressions are valid: ```typescript import type { Filters } from "@feltmaps/js-sdk"; const filter: Filters = ["POPULATION", "gt", 1000000]; felt.setLayerFilters({ layerId: "layer-1", filters: filter }); ``` # Building custom charts The Felt SDK provides powerful methods to analyze your geospatial data and transform it into informative visualizations. You can calculate statistics on entire datasets or focus on specific areas using boundaries and filters, allowing you to create custom charts that reveal insights about your spatial data. Statistics are available for layers that have been uploaded to and processed by Felt — layers created at runtime with [`createLayersFromGeoJson`](/js-sdk/working-with-layers) cannot be queried for statistics. ## Data analysis methods The SDK offers three complementary approaches to analyze your map data: ### 1. Aggregates: single statistics Calculate individual values (count, sum, average, etc.) across your dataset or a filtered subset. If no aggregation method is provided, the count is returned. ```javascript // Count all residential buildings const residentialCount = await felt.getAggregates({ layerId: "buildings", filters: ["type", "eq", "residential"] }); // returns { count: 427 } // Calculate average home value in a specific neighborhood const avgHomeValue = await felt.getAggregates({ layerId: "buildings", boundary: [-122.43, 47.60, -122.33, 47.62], // neighborhood boundary aggregation: { method: "avg", attribute: "assessed_value" } }); // returns { avg: 652850.32 } ``` ### 2. Categories: group by values Group features by unique attribute values and calculate statistics for each group. ```javascript // Basic grouping: Count of buildings by type const buildingsByType = await felt.getCategoryData({ layerId: "buildings", attribute: "type" }); /* returns: [ { value: "residential", count: 427 }, { value: "commercial", count: 82 }, { value: "mixed-use", count: 38 }, { value: "industrial", count: 15 } ] */ ``` ### 3. Histograms: group by numeric ranges Create bins for numeric data and calculate statistics for each range. ```javascript // Basic histogram: Building heights in 5 natural break bins const buildingHeights = await felt.getHistogramData({ layerId: "buildings", attribute: "height", steps: { type: "jenks", count: 5 } }); /* returns: [ { min: 0, max: 20, count: 175 }, { min: 20, max: 50, count: 203 }, { min: 50, max: 100, count: 142 }, { min: 100, max: 200, count: 36 }, { min: 200, max: 500, count: 6 } ] */ ``` ## Working with filters You can apply filters in two powerful ways: 1. **At the top level** - Affects both which data is included and how values are calculated 2. **In the values configuration** - Only affects the calculated values while keeping all categories/bins This two-level filtering is especially useful for creating comparative visualizations while maintaining consistent groupings. ### Advanced filtering examples **Comparing building types by floor area (Categories)** ```javascript // Advanced: Show all building types, but only sum floor area of recent buildings const recentBuildingAreaByType = await felt.getCategoryData({ layerId: "buildings", attribute: "type", values: { filters: ["year_built", "ge", 2000], aggregation: { method: "sum", attribute: "floor_area" } } }); /* returns: [ { value: "residential", sum: 1250000 }, { value: "commercial", sum: 750000 }, { value: "mixed-use", sum: 350000 }, { value: "industrial", sum: 120000 } ] */ ``` **Comparing building heights across time periods (Histograms)** ```javascript // Compare old vs new buildings using the same height ranges const oldBuildingHeights = await felt.getHistogramData({ layerId: "buildings", attribute: "height", steps: [0, 20, 50, 100, 200, 500], values: { filters: ["year_built", "lt", 1950] } }); /* returns: [ { min: 0, max: 20, count: 96 }, { min: 20, max: 50, count: 104 }, { min: 50, max: 100, count: 37 }, { min: 100, max: 200, count: 12 }, { min: 200, max: 500, count: 1 } ] */ const newBuildingHeights = await felt.getHistogramData({ layerId: "buildings", attribute: "height", steps: [0, 20, 50, 100, 200, 500], // Same ranges as above values: { filters: ["year_built", "ge", 1950] } }); /* returns: [ { min: 0, max: 20, count: 79 }, { min: 20, max: 50, count: 99 }, { min: 50, max: 100, count: 105 }, { min: 100, max: 200, count: 24 }, { min: 200, max: 500, count: 5 } ] */ ``` **Comparing neighborhood density (Aggregates)** ```javascript // Find average residential density across different neighborhoods const downtownDensity = await felt.getAggregates({ layerId: "buildings", boundary: [-122.335, 47.600, -122.330, 47.610], // downtown boundary filters: ["type", "eq", "residential"], aggregation: { method: "avg", attribute: "units_per_acre" } }); // returns { avg: 124.7 } const suburbanDensity = await felt.getAggregates({ layerId: "buildings", boundary: [-122.200, 47.650, -122.150, 47.700], // suburban boundary filters: ["type", "eq", "residential"], aggregation: { method: "avg", attribute: "units_per_acre" } }); // returns { avg: 8.2 } ``` ## Interactive visualization example Here's how you might integrate these analysis methods with an interactive chart: ```javascript // Create a pie chart showing building type distribution async function createBuildingTypePieChart() { // Get data for the chart const data = await felt.getCategoryData({ layerId: "buildings", attribute: "type" }); // Render pie chart (using a hypothetical chart library) const chart = renderPieChart(data, { valuePath: "count", labelPath: "value", onSliceClick: handleSliceClick }); return chart; } // Handle user interaction with the chart async function handleSliceClick(slice) { const buildingType = slice.label; // Apply filter to highlight this building type on the map await felt.setLayerFilters({ layerId: "buildings", filters: ["type", "eq", buildingType], note: `Showing ${buildingType} buildings only` }); // Get additional statistics for this building type const stats = await felt.getAggregates({ layerId: "buildings", filters: ["type", "eq", buildingType], aggregation: { method: "avg", attribute: "year_built" } }); // Update the UI with these statistics updateStatsPanel(`Average ${buildingType} year built: ${Math.round(stats.avg)}`); } // Initialize the chart when the page loads createBuildingTypePieChart(); ``` This example demonstrates how a user clicking on a pie chart slice could apply a filter to the map, highlighting only the buildings of that type. It also shows how you could fetch additional statistics based on the user's selection to enrich the visualization experience. # Drawing annotations {% hint style="info" %} #### Note: Annotations were previously referred to as Elements. References have been updated in the app and documentation, while REST API endpoint and JS SDK method naming remain unchanged. {% endhint %} The Felt SDK provides two main approaches for creating annotations on your maps: 1. **Interactive Drawing**: Configure and activate drawing tools for users to create annotations manually 2. **Programmatic Creation**: Create and modify annotations directly through code Annotations created via the SDK are session-specific - they're not persisted to the map and won't be visible to other users. ## Interactive drawing with tools The methods on the [`ToolsController`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller) enable you to programmatically activate drawing tools for your users, as well as setting various options for the tools, such as color, line width, etc. Use the [`setTool`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#settool) method to activate a particular tool. Use the [`setToolSettings`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#settoolsettings) method to configure the options for a specific tool. Use the [`onToolChange`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#ontoolchange) and [`onToolSettingsChange`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#ontoolsettingschange) to be notified of changes to the above, or read them instantaneously with the [`getTool`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#gettool) and [`getToolSettings`](https://developers.felt.com/js-sdk-api-reference/tools/toolscontroller#gettoolsettings) methods. As the user creates annotations with the tools, you can be notified of them being created and updated using the [`onElementCreate`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementcreate) and [`onElementChange`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementchange) listeners. See [#listening-for-annotation-creation](#listening-for-annotation-creation "mention") for more details. ### Tool types

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

### Example ```javascript // Configure the line tool felt.setToolSettings({ tool: "line", strokeWidth: 8, color: "#448C2A" }); // Activate the line tool felt.setTool("line"); // Later, deactivate the tool felt.setTool(null); ``` ## Programmatic annotation creation If you want to create annotations programmatically instead of letting your users draw them interactively on the map, use the methods in the [`ElementsController`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller). To create annotations, use the [`createElement`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#createelement) method. To update annotations, use the [`updateElement`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#updateelement) method. To delete annotations, use the [`deleteElement`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#deleteelement) method. When annotations are created programmatically, they also trigger notifications about the corresponding changes to annotations, via `onElementCreate`, `onElementChange` and `onElementDelete`. ### Example ```javascript // Create a polygon const polygonElement = await felt.createElement({ type: "Polygon", coordinates: [ [ [-122.42, 37.78], [-122.41, 37.78], [-122.41, 37.77], [-122.42, 37.77], [-122.42, 37.78] ] ], color: "#FF5733", fillOpacity: 0.5 }); // Update its properties await felt.updateElement({ id: polygonElement.id, // note that we pass the type here, too in order to get correct // TypeScript type-checking and autocompletion. type: "Polygon", color: "#ABC123", fillOpacity: 0.5, strokeWidth: 2 }); // Finally delete the element await felt.deleteElement(polygonElement.id) ``` ## Retrieving annotation geometry Extract the geometric representation of annotations using the [`getElementGeometry`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#getelementgeometry) method. The geometry is returned in GeoJSON geometry format, which can be quite different to the way the annotation is specified in Felt. For example, `Circle` annotations in Felt have their geometry converted into a polygon, representing the area covered by the circle. **Note:** Text, Note, and Image annotations do not return geometry as they are considered screen annotations rather than true "geospatial" annotations. ```javascript // Get an element's geometry in GeoJSON format const geometry = await felt.getElementGeometry("element-1"); console.log(geometry?.type, geometry?.coordinates); ``` ## Listening for changes Every change that is made to the annotations on a map results in a call to either [`onElementCreate`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementcreate), [`onElementDelete`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementdelete) or [`onElementChange`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementchange). ```javascript // Set up a listener for changes to a polygon const unsubscribeChange = felt.onElementChange({ options: { id: polygonElement.id }, handler: ({element}) => { console.log("Polygon was updated:", element); } }); // Set up a listener for deletion const unsubscribeDelete = felt.onElementDelete({ options: { id: polygonElement.id }, handler: () => { console.log("Polygon was deleted"); } }); // Later, clean up listeners unsubscribeChange(); unsubscribeDelete(); ``` ### Listening for annotation creation There are two different ways for listening to annotations being created, and the one you use depends on how the annotation is being created, and at what point you want to know about an annotation's creation. When the user is creating annotations with tools, they are often created in a number of steps, such as drawing a marker stroke or creating a polygon with many vertices. When you want to know when the user has *finished* creating the annotation (e.g. the polygon was closed or the marker stroke ended) then you should use the [`onElementCreateEnd`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementcreateend) listener. When annotations are created programmatically, they do not trigger the [`onElementCreateEnd`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementcreateend) event. Annotations created using Tools *or* [`createElement`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#createelement) will trigger the [`onElementCreate`](https://developers.felt.com/js-sdk-api-reference/elements/elementscontroller#onelementcreate) event, with an extra property stating whether the annotation is still being created. ```javascript // Listen for any element creation const unsubscribe = felt.onElementCreate({ handler: ({ element, isBeingCreated }) => { console.log(`New element created with ID: ${element?.id}`); // Check if the element is still being drawn if (isBeingCreated) { console.log("User is still creating this element"); } } }); // Or listen for when element creation is completed with a tool const unsubscribeEnd = felt.onElementCreateEnd({ handler: ({element}) => { console.log(`Element ${element.id} creation finished`); } }); // Later, clean up listeners unsubscribe(); unsubscribeEnd(); ``` ## Sample application: sending annotations drawn by users to your backend Here is an example showing the power of the Felt SDK, where in just a few lines of code you can allow your users to draw annotations and have them sent to your own backend systems for persistence or analysis. Assuming you have embedded your Felt map as described in [Getting started](/js-sdk/getting-started), and in your own UI you have added a `polygon-tool` button and a `reset-tool` button, all you need is the following: ```javascript // Set your initial tool settings in a style that suits your application felt.setToolSettings({ tool: "polygon", strokeWidth: 2, color: "#FF5733", fillOpacity: 0.3, }); // Activate the tool when the user clicks a button in your UI document.getElementById("polygon-tool").addEventListener("click", () => { felt.setTool("polygon"); }); // Disable the tool when the user clicks a button in your UI document.getElementById("reset-tool").addEventListener("click", () => { felt.setTool(null); }); // Listen for completed polygons felt.onElementCreateEnd({ handler: async ({element}) => { // get the polygon geometry that the user just drew const geometry = await felt.getElementGeometry(element.id); // send the polygon to your own backend system sendToServer(geometry); } }); ``` # UI components ## Action triggers and custom panels The Felt SDK enables you to extend Felt maps with custom UI components that integrate seamlessly with the native interface. These extensions allow you to add interactive controls and custom workflows directly within the map experience. ### UI extension points Felt provides two primary ways to add custom UI to your maps:

**Action Triggers** appear as buttons in the left sidebar and provide quick access to custom actions. Think of them as shortcuts that users can click to trigger specific functionality in your application. **Custom Panels** appear in the right sidebar and offer a full canvas for complex UI. These panels can contain forms, controls, and interactive elements that work together to create sophisticated user experiences. ### Action triggers Action triggers are simple button controls that execute custom functions when clicked. They're perfect for actions that don't require additional user input - like applying filters, running calculations, or enabling an interaction mode. ```javascript await felt.createActionTrigger({ actionTrigger: { label: "Check solar potential", onTrigger: async () => { // Enable polygon tool to allow a user to select a region await felt.setTool("polygon"); // ... }, } }); ``` ### Custom panels Custom panels provide a structured way to build complex UI within Felt. Each panel consists of three main sections that serve different purposes: #### Panel structure

**Header** - Contains the panel title, and an optional close button. **Body** - Houses the main interactive elements like forms, selectors, and content areas. This is where users spend most of their time interacting with your custom functionality. **Footer** - Typically contains primary action buttons like "Save", "Cancel", or "Apply". This creates a consistent pattern users expect from dialog-style interfaces. The footer sticks to the bottom of the panel, with a divider separating it from the body. #### Getting started with panels Create a panel by first generating an ID, then specifying its contents. You can control where panels appear using the `initialPlacement` parameter. When `onClickClose` is specified, a close button will be rendered in the header. ```javascript const panelId = await felt.createPanelId(); await felt.createOrUpdatePanel({ panel: { id: panelId, title: "Add report", body: [ { type: "Select", placeholder: "Choose a neighborhood", options: [{ label: "Downtown", value: "downtown" }] }, { type: "Select", placeholder: "Choose a severity", options: [{ label: "Low", value: "low" }, { label: "High", value: "high" }] }, { type: "TextInput", placeholder: "Email", onBlur: storeEmail }, ], footer: [ { type: "ButtonRow", align: "end", items: [ { type: "Button", label: "Back", variant: "transparent", tint: "default", onClick: handleBack }, { type: "Button", label: "Done", variant: "filled", tint: "primary", onClick: handleDone } ] } ], onClickClose: async () => { // Clean up await felt.deletePanel(panelId); } }, initialPlacement: { at: "start" } // Optional: control panel positioning }); ``` ### Panel elements Custom panels support a variety of interactive and display elements that can be combined to create rich user experiences:

#### Text elements [Text elements](https://developers.felt.com/js-sdk-api-reference/ui/uitextelement) display formatted content and support full Markdown rendering, allowing you to include headings, lists, links, and formatting within your panels. ```javascript { type: "Text", content: "**Welcome!** This is a *formatted* text element with [links](https://felt.com).", } ``` #### TextInput elements [TextInput](https://developers.felt.com/js-sdk-api-reference/ui/uitextinputelement) elements allow users to enter custom values like names, descriptions, or numeric parameters. ```javascript { type: "TextInput", placeholder: "First name", value: "", onChange: (args) => { console.log("New value:", args.value); }, } ``` #### Control elements Control elements allow users to choose from predefined options:

Available control elements include [**Select**](https://developers.felt.com/js-sdk-api-reference/ui/uiselectelement), [**CheckboxGroup**](https://developers.felt.com/js-sdk-api-reference/ui/uicheckboxgroupelement), [**RadioGroup**](https://developers.felt.com/js-sdk-api-reference/ui/uiradiogroupelement), and [**ToggleGroup**](https://developers.felt.com/js-sdk-api-reference/ui/uitogglegroupelement). Each element supports similar properties: ```javascript // Select dropdown { type: "Select", // or "CheckboxGroup" | "RadioGroup" | "ToggleGroup" label: "Year", options: [ { value: "2025", label: "2025" }, { value: "2024", label: "2024" }, ], value: "", onChange: (args) => { console.log("Selected:", args.value); } } ``` #### Button elements [Button elements](https://developers.felt.com/js-sdk-api-reference/ui/uibuttonelement) trigger actions and come in different styles to communicate their importance and effect. Buttons can have different variants (filled, outlined, and transparent) and tints (primary, accent, danger and default):

Primary filled buttons highlight the most important action in a context. Use sparingly - typically one per panel section. ```javascript { type: "Button", label: "Submit", variant: "filled", // "transparent" | "outlined" tint: "primary", // "default" | "accent" | "danger" onClick: async () => { // Handle button click } } ``` #### Button rows Group related buttons together to create clear action hierarchies:

[Button rows](https://developers.felt.com/js-sdk-api-reference/ui/uibuttonrowelement) automatically handle spacing and alignment, ensuring your panels look polished and consistent. ```javascript { type: "ButtonRow", align: "end", items: [ { type: "Button", label: "Clear", variant: "transparent", tint: "default", onClick: handleClear }, { type: "Button", label: "Send report", variant: "filled", tint: "primary", onClick: handleSend } ] } ``` #### Grid elements [The grid element](https://developers.felt.com/js-sdk-api-reference/ui/uigridcontainerelement) helps organize elements within panels to create complex layouts. It uses a `grid` property that follows the same syntax as the CSS shorthand grid property, and includes `verticalAlignment` and `horizontalDistribution` properties for precise control over layout positioning.

```javascript { type: "Grid", grid: "auto-flow / 2fr 1fr", // CSS grid shorthand verticalAlignment: "start", horizontalDistribution: "stretch", items: [ { type: "Text", content: "![image](https://example.com/image1.png)" }, { type: "Text", content: "![image](https://example.com/image2.png) \n ![image](https://example.com/image3.png)" }, ] } ``` #### iframe elements [iframe elements](https://developers.felt.com/js-sdk-api-reference/ui/uiiframeelement) allow you to embed external content by providing a URL to charts, dashboards, or other web applications directly within your panels. ```javascript { type: "Iframe", url: "https://example.com/dashboard", height: 400, } ``` #### Divider elements Divider elements provide visual separation between sections of content in your panels. ```javascript { type: "Divider", } ``` ### Panel state management #### Creating and updating panels A panel is identified by its ID, which must be created using [`createPanelId`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#createpanelid). Custom IDs are not supported to prevent conflicts with other panels.\ \ Use [`createOrUpdatePanel`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#createorupdatepanel) for most panel scenarios. This declarative method lets you specify what the panel should contain, and it handles both creating new panels and updating existing ones with the same API call. ```javascript const panelId = await felt.createPanelId(); const greetingElement = { id: "greeting", type: "Text", content: "Hello" }; // Initial state await felt.createOrUpdatePanel({ panel: { id: panelId, title: "My Panel", body: [greetingElement] } }); // Update using destructuring await felt.createOrUpdatePanel({ panel: { id: panelId, title: "My Panel", body: [{ ...greetingElement, content: "Hello World" }] } }); ``` #### Targeted panel element updates Use [`updatePanelElements`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#updatepanelelements) for granular control when you want to modify individual elements. Elements need IDs to be targeted for updates. You can also use [`createPanelElements`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#createpanelelements) to add elements and [`deletePanelElements`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller#deletepanelelements) to remove elements by their IDs. ```javascript const panelId = await felt.createPanelId(); // Create panel with multiple elements await felt.createOrUpdatePanel({ panel: { id: panelId, title: "Data Panel", body: [ { id: "status-text", type: "Text", content: "Ready" }, { id: "layer-select", type: "Select", label: "Choose Layer", options: [ { value: "layer1", label: "Population" }, { value: "layer2", label: "Income" } ] } ] } }); // Update only the text element await felt.updatePanelElements({ panelId, elements: [{ element: { id: "status-text", type: "Text", content: "Processing data..." } }] }); // Add a new element to the panel await felt.createPanelElements({ panelId, elements: [{ element: { id: "progress-text", type: "Text", content: "Progress: 50%" }, container: "body", placement: { at: "end" } }] }); // Remove an element from the panel await felt.deletePanelElements({ panelId, elements: ["progress-text"] }); ``` # Events reference Every listener on the Felt controller follows the same pattern: you pass a `handler` (and sometimes an `options` object scoping the listener to a specific entity), and the call returns an unsubscribe function. ```typescript const unsubscribe = felt.onLayerChange({ options: { id: "layer-1" }, handler: ({ layer }) => console.log(layer.bounds), }); // ...later, when you no longer need the listener unsubscribe(); ``` Always call the unsubscribe function when your UI unmounts or the listener is no longer needed. ## Viewport and map state | Listener | Scoping options | Handler receives | | ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ | | `onViewportMove` | — | `ViewportState` — fires continuously during movement, including during animations and inertia. | | `onViewportMoveEnd` | — | `ViewportState` — fires once when dragging, zooming, animations, and inertia have finished. | | `onMapIdle` | — | Nothing. Fires when the map is fully idle: no transitions, no interaction, all tiles loaded, fades complete. | | `onBasemapChange` | — | `Basemap` — the new basemap. | ## Annotations (elements) | Listener | Scoping options | Handler receives | | ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onElementCreate` | — | `{ element: Element \| null, isBeingCreated: boolean }` — fires repeatedly while the user draws (`isBeingCreated: true`), then a final time with `isBeingCreated: false`. | | `onElementCreateEnd` | — | `{ element: Element }` — fires once, when creation is finished. | | `onElementChange` | `{ id }` | `{ element: Element \| null, isBeingCreated: boolean }` — `element` is `null` if it was removed. | | `onElementDelete` | `{ id }` | Nothing. | | `onElementGroupChange` | `{ id }` | `{ elementGroup: ElementGroup \| null }` | ## Layers and legends | Listener | Scoping options | Handler receives | | ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `onLayerChange` | `{ id }` | `{ layer: Layer \| null }` | | `onLayerGroupChange` | `{ id }` | `{ layerGroup: LayerGroup \| null }` | | `onLegendItemChange` | `{ id, layerId }` | `{ legendItem: LegendItem \| null }` | | `onLayerFiltersChange` | `{ layerId }` | `LayerFilters` — the bare filters object (`{ style, components, ephemeral, combined }`), with no wrapper. See [Layer filters](/js-sdk/layer-filters). | | `onLayerBoundariesChange` | `{ layerId }` | `LayerBoundaries \| null` | ## Pointer and selection | Listener | Scoping options | Handler receives | | ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onPointerClick` | — | `MapInteractionEvent` — `{ coordinate, point, features, rasterValues }`. `features` and `rasterValues` are arrays (empty when nothing is under the pointer). | | `onPointerMove` | — | `MapInteractionEvent` | | `onSelectionChange` | — | `{ selection: EntityNode[] }` — see [Working with selection](/js-sdk/working-with-selection). | ## Tools | Listener | Scoping options | Handler receives | | ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------ | | `onToolChange` | — | `ToolType \| null` — the newly selected tool, or `null` when no tool is active. | | `onToolSettingsChange` | — | `ToolSettingsChangeEvent` — a discriminated union: check the `tool` field to narrow to that tool's settings. | For payload type details, follow each method's entry in the [API reference](https://developers.felt.com/js-sdk-api-reference). # Sample application This is a sample application showing how to use the Felt SDK to build an app with the following features: * listing the map's layers * toggling layer visibility * moving the viewport to center it on predefined city locations

The commented code in its entirety is shown below. ```html Felt JS SDK

``` # Examples Explore examples of what you can build with the Felt SDK. These examples showcase different approaches to creating interactive map experiences - from extensions that run directly within Felt to embedded maps in custom applications. ## Extensions Extensions run directly within Felt maps, giving you immediate access to all SDK functionality. Here are some examples built using AI assistance: ### Commuter patterns Visualize transportation patterns by drawing lines to destination counties on click. Features travel mode options and filtering capabilities to analyze commuting data across different regions. View the map [here](https://felt.com/map/Commuting-patterns-EPs9A4ShcT8i0pErry2vayB).

### Neighborhood comparison Compare neighborhoods side-by-side with automated analysis of land use patterns. This tool helps users understand demographic and geographic differences between areas. View the map [here](https://felt.com/map/Compare-Neighborhoods-Yn2fUt8fQJKBp9A29ARlOvED).

### Animated data Bring geographic data to life with animations showing the flow of the Mississippi River Basin from headwaters to the Gulf of Mexico, demonstrating how to create compelling temporal visualizations. View the map [here](https://felt.com/map/Mississippi-River-Basin-Animation-PBTjZpYDQHabIOpuZeADcD).

### Story map Guide users through agricultural regions with an interactive narrative experience that combines storytelling with geographic exploration. View the map [here](https://felt.com/map/CropScape-Explorer-8mXNgodOTty9BHKEgP7m9CLA).

## Embedded maps Embed Felt maps in your own applications and control them with the SDK. Here are some examples built with React and hosted on CodeSandbox: ### Rooftop solar potential This interactive application leverages the Tool API to enable users to draw custom geometries that retrieve filtered GeoJSON data from an ESRI FeatureService. The application creates a dynamically styled GeoJSON layer to visualize solar potential data, helping users identify optimal locations for solar installations. View the app and code [here](https://7wvdgn.csb.app/).

### Sales dashboard Create powerful business intelligence tools by combining Felt's layer statistics with popular charting libraries. This example demonstrates how to build interactive visualizations that leverage layer filters. View the app and code [here](https://ydx2p7.csb.app/).

### Custom legend with nested folders Enhance map usability with a custom legend that extracts and uses [FSL](/felt-style-language/getting-started) styling information to generate SVG icons. The code demonstrates how to build a nested folder structure with visibility toggles using layer filters, providing a pattern for organizing complex data layers. View the app and code [here](https://x7ycff.csb.app/).

### Inset maps Build comprehensive multi-view dashboards by embedding multiple Felt maps on a single page. This example demonstrates how to create synchronized map views that communicate with each other, enabling users to simultaneously view different geographic contexts or zoom levels of the same data. View the app and code [here](https://wm6k24.csb.app/).

### Lens map Create engaging interactive experiences with customizable map lenses that reveal different data layers or styling as users explore. This technique allows for compelling before/after comparisons or the ability to highlight specific data attributes within a defined area. View the app and code [here](https://84mwly.csb.app/).

### Isochrones Provides a pattern for integrating third-party geospatial APIs with Felt maps. This example demonstrates how to make API requests based on annotation geometry and map interactions, process the returned data, and visualize isochrones as dynamic layers. View the app and code [here](https://t7x4rl.csb.app/).

# Getting started The Felt Style Language (FSL) is a JSON-based specification for styling data layers in Felt — comparable to the Mapbox Style Spec, but at the layer level. A single JSON object describes how a layer is drawn (`paint`), labeled (`label`), classified (`config`), and presented in popups and legends. ## Where you use FSL The same style object works in three places: * **In the Felt app** — open a layer's overflow menu and choose `Actions > Edit style language` to view and edit the layer's FSL directly. (The neighbouring `Actions > Edit styles` opens the visual style editor, which has no JSON view.) * **Via the REST API** — read a layer's `style` field and update it with [`POST /update_style`](/rest-api/styling-layers). * **Via the JS SDK** — apply session-only style changes with [`setLayerStyle`](https://developers.felt.com/js-sdk-api-reference/layers/layerscontroller#setlayerstyle). ## Your first style Every style needs a `version` and a `type`. Here is a complete, minimal style that draws a point layer in green with a visible stroke: ```json { "version": "2.3.1", "type": "simple", "config": {}, "paint": { "color": "#28A745", "size": 8, "strokeColor": "auto", "strokeWidth": 1 }, "legend": {}, "label": {}, "popup": {} } ``` Paste this into `Actions > Edit style language` on any point layer and the points turn green immediately. From here, styling is incremental: change `"type"` to `"categorical"` or `"numeric"` to drive color or size from your data, add `steps` or `categories` to `config`, and swap literal colors for [`@palette` shortcuts](/felt-style-language/colors-and-palettes). ## Anatomy of a style | Key | Purpose | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | The FSL version the style is written against. Use `"2.3.1"` (current). Older versions are accepted and migrated automatically. | | `type` | The visualization type: `simple`, `categorical`, `numeric`, `heatmap`, `h3`, or `hillshade`. See [Types of visualizations](/felt-style-language/types-of-visualizations). | | `config` | Data configuration: which attribute drives the visualization, class breaks, categories, aggregation. See [The config block](/felt-style-language/style-definition-blocks/the-config-block). | | `paint` | How geometries and pixels are drawn: colors, sizes, strokes, opacity, icons. See [The paint block](/felt-style-language/style-definition-blocks/the-paint-block). | | `label` | Feature labels: fonts, halos, placement, zoom range. See [The label block](/felt-style-language/style-definition-blocks/the-label-block). | | `popup` | What clicking a feature shows. See [The popup block](/felt-style-language/style-definition-blocks/the-popup-block). | | `attributes` | Display names and number formatting for attributes. See [The attributes block](/felt-style-language/style-definition-blocks/the-attributes-block). | | `filters` | Which features are visible. See [The filters block](/felt-style-language/style-definition-blocks/the-filters-block). | | `legend` | Legend labels. See [Legends](/felt-style-language/legends). | ## Explore the language ### Style definition blocks Learn how to define and configure the code blocks that compose the Felt Style Language {% content-ref url="/pages/ia98n0VZ2bW0rDUZjF49" %} [Style definition blocks](/felt-style-language/style-definition-blocks) {% endcontent-ref %} ### Types of visualizations Learn about visualization types, including simple, categorical, numeric (color by & size by), heatmaps, H3, and raster (imagery, numeric, categorical, and hillshade). {% content-ref url="/pages/t1uG4exfWZRod1VeBRFi" %} [Types of visualizations](/felt-style-language/types-of-visualizations) {% endcontent-ref %} ### Colors, icons & classification Shared building blocks referenced throughout the language: smart `"auto"` colors and named palettes, the icon catalog, and the classification methods used to turn numbers into classes. {% content-ref url="/pages/T2CzLFRxCIMHaz4WjYm8" %} [Colors & palettes](/felt-style-language/colors-and-palettes) {% endcontent-ref %} {% content-ref url="/pages/x4VFtWKNEKYOiqWp7dAQ" %} [Icons](/felt-style-language/icons) {% endcontent-ref %} {% content-ref url="/pages/fdqlMScWxZO7qFHImPxT" %} [Classification methods](/felt-style-language/classification-methods) {% endcontent-ref %} ### Zoom-based styling Vary paint and label properties with the map's zoom level using interpolators. {% content-ref url="/pages/wSQReOdXoeF1OhZv1hts" %} [Zoom-based styling](/felt-style-language/zoom-based-styling) {% endcontent-ref %} ### Legends Details on how to customize legends on a per-layer basis. {% content-ref url="/pages/1fKJtssIMYNDGoHaGUKl" %} [Legends](/felt-style-language/legends) {% endcontent-ref %} ### Errors Definitions for errors raised when validating the Felt Style Language. {% content-ref url="/pages/X4xQjPoTGzipaOEgV5zN" %} [Errors](/felt-style-language/errors) {% endcontent-ref %} ### Examples A compact gallery with one worked example per visualization type. {% content-ref url="/pages/BXFcwzVszq56jUVsZcNT" %} [Examples](/felt-style-language/examples) {% endcontent-ref %} # Style definition blocks ### The shape of a style definition A style in its most basic form contains a version definition but it can be extended to define how we want geometry and labels to show on the map, how the legend should look like, what information is shown in popups and the formatting used when displaying feature properties. The table below describes which properties can be used in the style definition.

Field name	Description
`version`	Mandatory. Defines which version this style adheres to. The current version is `"2.3.1"`.
`type`	Optional. One of simple, categorical, numeric, heatmap, h3, or (for raster) hillshade. Defaults to simple.
`config`	Optional. A block that contains some configuration options to be used across the style. Learn more.
`paint`	Optional. An object (or array of objects) that defines how the data will be drawn. Learn more.
`label`	Optional. An object that defines how the labels will be drawn. Learn more.
`legend`	Optional. Defines how this layer will be shown on the layer panel. Learn more.
`popup`	Optional. Defines how the popup is shown and what’s included. Learn more.
`attributes`	Optional. Defines how attributes are shown both in the popup and the table. Learn more.
`filters`	Optional. A data filter definition that defines which data will be rendered. Learn more.

All of these keys are siblings at the top level of the object — none are nested inside another: ```json { "version": "2.3.1", "type": "simple", "config": {}, "paint": {}, "label": {}, "legend": {}, "popup": {} } ``` {% hint style="info" %} The block that controls how geometry and raster pixels are drawn is named `paint`. (Some earlier drafts of this guide referred to it as `style`.) {% endhint %} # The config block The config block contains configuration options for a given visualization. These are the fields that each config block can contain: | Field name | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aggregation` | Optional, for [H3](/felt-style-language/types-of-visualizations/h3) visualizations. How points are aggregated within each cell: `"count"` (default), `"sum"`, `"mean"`, `"min"`, or `"max"`. All values except `"count"` also require `numericAttribute`. | | `band` | Optional. Used in raster numeric visualizations. The raster band (1-indexed) to read data from — a number, or an array of band numbers for multiband styling. | | `baseBinLevel` | Used in [H3](/felt-style-language/types-of-visualizations/h3) visualizations. The [H3 cell resolution](https://h3geo.org/docs/core-library/restable/) (0–15). Country-scale ≈ 3–4, city-scale ≈ 6–7. Sets the cell size when `binMode` is `"fixed"`; in the zoom-adaptive modes it serves as the reference resolution that `steps` values are scaled against. | | `binMode` | Used in [H3](/felt-style-language/types-of-visualizations/h3) visualizations. `"fixed"` (default; uses `baseBinLevel` at all zooms) or the zoom-adaptive modes `"low"`, `"medium"`/`"auto"`, and `"high"` — low means larger hexagons, high means smaller ones. | | `categoricalAttribute` | Mandatory for vector categorical visualizations. The attribute that contains the categorical values that will be used. (Raster categorical layers classify raw pixel values instead and omit this field.) | | `categories` | Mandatory for a categorical visualization. Either an explicit array of category values, or a shortcut: `{"type": "top", "count": N}` for the N most common values, `{"type": "bottom", "count": N}` for the N least common, or `{"type": "all"}` (raster) for every unique pixel value. | | `labelAttribute` | Optional. Defines which dataset attribute or attributes to use for labeling. If multiple values are provided, the first available one will be used. | | `method` | Optional. Used in multiband raster numeric visualizations. Maps a spectral index (NDVI/NDMI/NDWI) to its band assignments. See [Raster visualizations](/felt-style-language/types-of-visualizations/raster). | | `noData` | Optional. Used in raster visualizations. A value or array of values that won’t be shown (e.g. `[-9999]` for voids, `[0]` for no-data). | | `numericAttribute` | Mandatory for a numeric visualization. The attribute that contains the numeric values used. | | `otherOrder` | Optional. Used in categorical visualizations. It can be set to either "below" or "above" to make features that do not match any of the defined categories render below or above the other ones. The default position is "below". | | `outOfRangeValues` | Optional. Used in raster numeric visualizations. `"color"` clamps out-of-range pixels to the nearest class color; `"hide"` makes them transparent. | | `rasterResampling` | Optional. Used in raster numeric (and tinted hillshade) visualizations — not valid for categorical rasters, which always resample nearest. `"nearest"` preserves exact pixel values; `"linear"` smoothly interpolates (use for continuous imagery/elevation). Set it explicitly rather than relying on a default. | | `showOther` | Optional. Used in categorical visualizations. If set to true it shows all features that do not match any defined category and adds an extra entry as the last item in the legend. | | `steps` | Used by numeric, H3, and tinted-hillshade visualizations. Either an explicit array of break points (at least two values), or a [classification](/felt-style-language/classification-methods) shortcut such as `{"type": "jenks", "count": 5}` or `{"type": "continuous"}`. | ## Examples `config` is always an object. The examples below show the config block in isolation. {% code title="Categorical config — explicit categories" %} ```json "config": { "labelAttribute": ["Wikipedia", "faa"], "categoricalAttribute": "faa", "categories": ["faa-code-1", "faa-code-2", "faa-code-3"], "showOther": true, "otherOrder": "above" } ``` {% endcode %} {% code title="Categorical config — top-N shortcut" %} ```json "config": { "categoricalAttribute": "surface", "categories": {"type": "top", "count": 5}, "showOther": true } ``` {% endcode %} {% code title="Vector numeric config — automatic classification" %} ```json "config": { "numericAttribute": "percentage", "steps": {"type": "jenks", "count": 5} } ``` {% endcode %} {% code title="Raster numeric config — single band" %} ```json "config": { "band": 1, "steps": {"type": "continuous"}, "noData": [-9999], "rasterResampling": "nearest" } ``` {% endcode %} {% code title="H3 config — aggregate points into hexes" %} ```json "config": { "aggregation": "sum", "numericAttribute": "capacity_mw", "baseBinLevel": 4, "binMode": "medium", "steps": {"type": "quantiles", "count": 5} } ``` {% endcode %} # The paint block {% hint style="info" %} The paint block defines how feature geometries and raster pixels are rendered. {% endhint %} Color properties (`color`, `strokeColor`) accept a literal color or a `@palette` shortcut, and `strokeColor` additionally accepts the smart keyword `"auto"` — see [Colors & palettes](/felt-style-language/colors-and-palettes). Point layers can be drawn as icons via `iconImage` — see [Icons](/felt-style-language/icons). For data-driven (`categorical`, `numeric`, `h3`) visualizations, paint properties may be arrays, one value per category/class. Properties common to all visualization types. | | Type | Default | Description | | ------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isClickable` | boolean | true | Optional. A flag to tell if features should be clickable | | `isHoverable` | boolean | false | Optional. A flag to tell if features should be hoverable | | `isSandwiched` | boolean | false | Optional. A flag to tell if features affected by this visualization need to be rendered below the basemap road and water layers. Only applies to polygon features, point and line features are already rendered on top of the basemap | | `maxZoom` | number | 24 | Optional. The maximum zoom level at which the visualization will be shown | | `minZoom` | number | 0 | Optional. The minimum zoom level at which the visualization will be shown | | `renderAsLines` | boolean | false | Optional. Decides if a polygon dataset should be rendered as lines thus making them render above the basemap. Note that using this requires that the style uses line properties instead of polygon ones. | | `paintPropertyOverrides` | `object` | | Optional. An escape hatch: raw [MapLibre](https://maplibre.org/maplibre-style-spec/) `paint` or `layout` properties applied to the generated layer. Keys that are not valid for the underlying MapLibre layer type are silently ignored. Also available on the `label` block. See [here](https://help.felt.com/layers/styling/vector-layers#maplibre-style-overrides) for more. | ## Simple visualizations The following properties are available for the `simple` type of visualization

	Type	Applies to	Description
`color`	string \| Interpolator	Points, lines and polygons	Optional. The color to be used
`dashArray`	number[]	Lines	Optional. The dash line definition — an array of dash/gap lengths with an even number of entries, e.g. `[2, 1]`
`highlightColor`	string	Points, lines and polygons	Optional. The color to be used when a feature is selected
`highlightStrokeColor`	string	Points, lines and polygons	Optional. The stroke color to be used when a feature is selected
`highlightStrokeWidth`	number \| Interpolator	Points and polygons	Optional. The stroke width when a feature is selected
`lineCap`	`"butt"` \| `"round"` \| `"square"`\| Interpolator	Lines	Optional. The shape used to draw the end points of lines
`lineJoin`	`"bevel"` \| `"round"`\| `"miter"`\| Interpolator	Lines	Optional. The shape used to join two line segments when they meet
`opacity`	number \| Interpolator	Points, lines and polygons	Optional. The opacity to use from 0 to 1
`size`	number \| Interpolator	Points and lines	Optional. Point radius or line width in pixels
`strokeColor`	string \| Interpolator \| `auto`	Points and polygons	Optional. Stroke color
`strokeWidth`	number \| Interpolator	Points and polygons	Optional. Stroke width in pixels

See [default values](#default-values) for the default values of these attributes on each geometry type. ## Categorical and numeric visualizations `categorical` and `numeric` visualizations use the same `color`, `opacity`, `size`, `strokeColor`, `strokeWidth`, and line properties listed above (`highlightColor`/`highlightStrokeColor` are simple-only). The difference is that each property may be an **array**: a single value applies to every category/class, or one value per category/class. See the [categorical](/felt-style-language/types-of-visualizations/categorical-visualizations) and [numeric](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size) pages for worked examples. ## Icon properties (points) When a point layer should be drawn as icons instead of circles, set `iconImage` in the paint block. The icon takes on the layer's `color` and `size`. See [Icons](/felt-style-language/icons) for the full catalog and examples.

	Type	Description
`iconImage`	string \| string[]	An icon slug, or an emoji as `"emoji::name:"`. Array form assigns an icon per category/class.
`iconFrame`	`"none"` \| `"frame-circle"` \| `"frame-square"`	A frame drawn behind built-in icons (not emojis).
`iconRotation`	number \| string	Rotation in degrees, or a column name to rotate by.
`iconHideOnZoom`	number	Zoom level below which icons render as plain points.

## Paint arrays (casing & layered rendering) The `paint` property can be an **array of paint objects** for layered rendering. The layers render last-to-first (the last entry is the bottom layer, the first is on top). This is most often used for road-style casing: a wide dark outline beneath a narrower colored fill. ```json { "version": "2.3.1", "type": "simple", "paint": [ {"color": "#3B82F6", "size": 4, "opacity": 1.0, "lineCap": "round", "lineJoin": "round"}, {"color": "#1E3A5F", "size": 8, "opacity": 1.0, "lineCap": "round", "lineJoin": "round"} ], "legend": {} } ``` Paint arrays work on all geometries but are most useful for line casing. ## Label block reference Label rendering is configured separately, in the `label` block. See [The label block](/felt-style-language/style-definition-blocks/the-label-block) for the full property reference, defaults, and placement-by-geometry guidance. ## Default values

Name	Points	Polygons	Lines
`color`	"#EE4D5A"	"#826DBA"	"#4CC8A3"
`highlightColor`	"#EA3891"	"#EA3891"	"#EA3891"
`highlightStrokeColor`	"#EA3891"	"#EA3891"	"#EA3891"
`dashArray`	-	-
`lineCap`	-	-	"round"
`lineJoin`	-	-	"round"
`opacity`	0.9	0.8	1
`isSandwiched`	-	false	-
`size`	4	-	2
`strokeColor`	"#F9F8Fb"	"#777777"	-
`strokeWidth`	1	1	-

# The label block {% hint style="info" %} The label block defines how feature labels are rendered. {% endhint %} These are the properties available to define label rendering. Point and line features are labeled directly; polygon labels are anchored at each polygon's centroid (or along lines with `renderAsLines`). | | Type | Applies to | Description | | ---------------- | --------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `color` | string \| auto \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators) | Points and lines | Optional. The label color | | `fontFamily` | string | Points and lines | Optional. The font family to use | | `fontSize` | number \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators) | Points and lines | Optional. The font size in pixels | | `fontStyle` | "normal" \| "italic" | Points and lines | Optional. The font style (case-insensitive). Values other than italic render as normal | | `fontWeight` | number | Points and lines | Optional. The font weight | | `haloColor` | string \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators) | Points and lines | Optional. The label halo color | | `haloWidth` | number \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators) | Points and lines | Optional. The label halo width in pixels | | `justify` | "auto" \| "left" \| "right" \| "center" | Points and lines | Optional. Text justification for multi-line labels | | `letterSpacing` | number | Points and lines | Optional. Horizontal spacing behaviour between text characters | | `lineHeight` | number | Points and lines | Optional. Sets the height of a line box | | `maxLineChars` | number \| [Interpolator](/felt-style-language/zoom-based-styling/interpolators) | Points and lines | Optional. Defines the max number of characters before a line break | | `maxZoom` | number | Points and lines | Optional. The maximum zoom level at which the label will be shown. Defaults to 24 | | `minZoom` | number | Points and lines | Optional. The minimum zoom level at which the label will be shown. Defaults to 24 (see note below) | | `offset` | \[number, number] \| number | Points and lines | Optional. In the case of points, this value must be an array of two numeric offsets that will be applied on the positive X and Y axis defined by the label placement (i.e. an offset of \[3,4] with a label placement of NE moves the label 3pixels to the right and 4 pixels above of the anchor point. An offset of \[3,4] with a label placement of SW moves the label 3pixels to the left and 4 pixels below of the anchor point). In case of lines, this value is a single number that moves the label following the label position (i.e. an offset of 3 with a label position of Above will move the label 3 pixels above the line following the line normal. An offset of 3 with a label position of Below will mode the label 3 pixels under the line following the line normal) | | `padding` | number | Points and lines | Optional. Adds invisible padding around the label that's used to compute label collisions | | `placement` | string\[] \| "auto" \| string | Points and lines | Optional. On points: an array of placements to try (`"N"`, `"NE"`, `"E"`, `"SE"`, `"S"`, `"SW"`, `"W"`, `"NW"`, `"Center"`) or `"auto"`; if all placements collide with existing labels, the label is not shown. On lines: a single placement relative to the line — `"Above"`, `"Center"` or `"Below"` | | `renderAsLines` | boolean | Polygons | Optional. Renders labels along lines instead of using the centroids | | `repeatDistance` | number | Lines | Optional. The distance in pixels between label repetitions on a line | | `textTransform` | "none" \| "uppercase" \| "lowercase" | Points and lines | Optional. Specifies how to capitalize the label | | `isClickable` | boolean | Points, Lines and Polygons | Optional. A flag to tell if labels should be clickable | | `isHoverable` | boolean | Points, Lines and Polygons | Optional. A flag to tell if labels should be hoverable | In addition, lines support `maxAngle` (number, default `30`) — the maximum angle in degrees for text following a curved line. See [default values](#default-values) of these attributes on each label type. ## Placement by geometry `placement` is shaped differently depending on the geometry being labeled: * **Points:** an array of compass directions to try, e.g. `["E"]` (right of the point), `["E", "W"]`, or `["Center"]`. Felt uses the first placement that doesn't collide. * **Lines:** a single string relative to the line — `"Above"`, `"Center"`, or `"Below"`. Tune `repeatDistance` (pixels between repeated labels) and `maxAngle` for curved text. * **Polygons:** `["Center"]` places the label at the polygon's centroid. {% hint style="info" %} Prefer `"color": "auto"` and `"haloColor": "auto"` so labels stay legible across themes and basemaps. See [Colors & palettes](/felt-style-language/colors-and-palettes). {% endhint %} If using a `categorical` or `numeric` visualization, the properties above may be arrays. If there's a single value in the array, that value is used in all categories. If there are as many values as `categories`, the corresponding value will be used for each category. You can see an example of a `categorical` viz [here](/felt-style-language/types-of-visualizations/categorical-visualizations). ## Default values

Name	Points	Lines	Centroids
`color`	"#333333"	"#333333"	"#333333"
`fontFamily`	"Atlas Grotesk LC"	"Atlas Grotesk LC"	"Atlas Grotesk LC"
`fontSize`	13	13	13
`fontStyle`	"Normal"	"Normal"	"Normal"
`fontWeight`	500	400	500
`haloColor`	"#fbfcfb"	"#fbfcfb"	"#fbfcfb"
`haloWidth`	1	1	1
`justify`	"auto"	"auto"	"auto"
`letterSpacing`	0	0	0
`lineHeight`	1.2	1.2	1.2
`maxLineChars`	10	-	10
`maxAngle`	-	30	-
`maxZoom`	24	24	24
`minZoom`	24	24	24
`offset`	[8, 8]	0	-
`padding`	2	1	0
`placement`	"auto"	"Above"	"Center"
`repeatDistance`	-	250	-
`textTransform`	"none"	"none"	"none"

{% hint style="info" %} The default `minZoom` and `maxZoom` are both 24 — an empty range, which is how labels are hidden by default. To show labels, set a real zoom range on the label block. {% endhint %} # The popup block The popup block contains information on how the popup is displayed and which attributes to show. These are the fields that each popup block can contain:

Field name	Description
`type`	Optional. `"attributes"` (default), `"iframe"`, or `"html"`.
`titleAttribute`	Optional. The attribute (or attributes) used to title the popup if available.
`imageAttribute`	Optional. The attribute that will be used to populate the popup image if available.
`popupLayout`	Optional. One of `"table"` or `"list"`. The way the popup shows its contents. Defaults to `"table"`.
`popupLocation`	Optional. Where the popup appears: `"onMap"`, `"leftSidebar"`, `"rightSidebar"`, or `"modal"`.
`headerLayout`	Optional. `"standard"`, `"compact"`, or `"none"`.
`keyAttributes`	Optional. A list of attributes to show in the popup following the order defined here. If it’s not defined, only attributes with a value will show. If it’s defined, all listed attributes show even when the selected feature doesn’t include them.
`url`	Iframe popups only. The URL to embed; supports the `{{column_name}}` template syntax.
`width`	`iframe` and `html` popups only. The popup width in pixels.
`height`	`iframe` and `html` popups only. The popup height in pixels.

{% code title="Example of a popup block" %} ```json "popup": { "titleAttribute": "name", "keyAttributes": ["osm_id", "highway", "ref", "place"], "popupLayout": "list", "popupLocation": "onMap", "headerLayout": "standard" } ``` {% endcode %} ## Iframe and HTML popups An `iframe` popup embeds external content. Use the template syntax `{{column_name}}` (or `{{['Column Name']}}` for names with spaces) to inject feature values into the URL or HTML. An `html` popup renders a rich HTML template that is authored and stored with the layer in the Felt app — the FSL block only sets `"type": "html"` plus the common fields above; the template itself is not part of the style. {% code title="Iframe popup" %} ```json "popup": { "type": "iframe", "url": "https://example.com/details/{{id}}", "popupLocation": "modal", "width": 600, "height": 800 } ``` {% endcode %} ## H3 aggregation attributes [H3](/felt-style-language/types-of-visualizations/h3) hexes show **aggregated** values rather than raw feature attributes, so their popups reference special attribute names: * `"felt:cluster_size"` — number of features in the hex * `"felt:sum:column"`, `"felt:mean:column"`, `"felt:min:column"`, `"felt:max:column"` — aggregates of `column` ```json "popup": { "titleAttribute": "felt:sum:revenue", "keyAttributes": ["felt:cluster_size", "felt:mean:revenue", "felt:max:revenue"] } ``` # The attributes block The attributes block contains information on how attributes will be shown both on the popup and the table. Each attribute definition can contain the following properties:

Field name	Description
`displayName`	Optional. How this attribute will be shown in different parts of the Felt UI.
`format`	Optional. A numbro object that encodes how numeric fields should be shown.

{% code title="Example of an attributes block" %} ```json "attributes": { "faa": { "displayName": "FAA Code", "format": { "mantissa": 0, "thousandSeparated": true } }, "wikipedia": {"displayName": "Wikipedia"} } ``` {% endcode %} ## The `format` object `format` accepts any valid [numbro format object](https://numbrojs.com/format.html) — common keys include `mantissa` (decimal places), `thousandSeparated`, `average` (compact notation like `1.2M`), `output` (`"percent"`, `"currency"`), and `prefix`/`postfix`. The object is validated by numbro itself, so anything numbro accepts is valid. Felt adds one extra key on top of numbro: `unit`, for displaying measurements. Supported values: `meter`, `kilometer`, `foot`, `mile`, `square_meter`, `hectare`, `square_kilometer`, `square_foot`, `acre`, `square_mile`, and the adaptive `auto-distance` and `auto-area`. ```json "attributes": { "parcel_area": { "displayName": "Parcel area", "format": {"mantissa": 1, "unit": "auto-area"} } } ``` # The filters block The filters block contains information on how the layer is being filtered before displaying. In order for a feature to be shown on the map it must evaluate the filter expression to `true`. Filters are written using a JSON infix notation that looks like one of `[identifier, operator, operand]`, `true` or `false` . * Valid identifiers are either a feature property or a nested expression. * Valid operators are: * `"lt"` – Less than * `"gt"` – Greater than * `"le"` – Less than or equal to * `"ge"` – Greater than or equal to * `"eq"` – Equal to * `"ne"` – Not equal to * `"and"` – And, cast to boolean * `"or"` – Or, cast to boolean * `"cn"` – Contains the operand, cast to string * `"nc"` – Does not contain the operand, cast to string * `"in"` – Contained in the operand list * `"ni"` – Not contained in the operand list * `"is"` – Used to match against null values * `"isnt"` – Used to match against null values * Operands are: * A numerical value, a string value, a boolean value * An array of numerical, string, or boolean values, a shorthand expanded to these patterns: * Input 1: `[id, "in", [element1, …, elementN]]` * Expansion 1: `id` is equal (`"eq"`) to one or more of the elements * Input 2: `[id, "ni", [element1, …, elementN]]` * Expansion 2: `id` is not equal (`"ne"`) to any of the elements * Not defined for operators other than `"in"` and `"ni"` * A nested expression * In cases of type mismatch cast the identifier value to the operand’s type * Type casting applies element-wise to lists with `"in"` and `"ni"` operators {% code title="Example of a filter block that filters out features with a value less than 50000 on the acres property" %} ```json "filters": ["acres", "lt", 50000] ``` {% endcode %} {% code title="Example of a more complex filter block" %} ```json "filters": [["acres", "ge", 50000], "and", ["acres", "le", 70000]] ``` {% endcode %} ## Behavior notes * **Case & diacritics:** `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `cn`, and `nc` compare strings case-insensitively and diacritic-insensitively. `["status", "eq", "active"]` matches `"Active"` and `"ACTIVE"`. * **`in` / `ni` are case-sensitive**, unlike the operators above, and do per-element type coercion (`["id", "in", [5]]` matches a string `"5"`). `in` with an empty array always returns false; `ni` with an empty array always returns true. * **Null handling:** use `is` / `isnt` only for null/existence checks (with `null` as the value) — not for value equality. Most other operators yield null (and filter the feature out) when the column is missing or null. * **Type coercion:** the left-hand value is cast to match the right-hand type, so `["score", "eq", 100]` matches whether the column stores `100` or `"100"`. ## Common patterns There is no single "between" operator — combine two comparisons: ```json "filters": [["temperature", "ge", 0], "and", ["temperature", "le", 100]] ``` Check that a value exists and is non-empty: ```json "filters": [["name", "isnt", null], "and", ["name", "ne", ""]] ``` **Three or more conditions must be written as nested pairs, not a flat list:** ```jsonc // WRONG: [a, "and", b, "and", c] // RIGHT: "filters": [["a", "eq", 1], "and", [["b", "eq", 2], "or", ["c", "eq", 3]]] ``` # Types of visualizations The `type` field chooses how a layer's data is turned into a picture. Pick the type that matches your data and message: | Type | Use it for | Works on | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------- | | [Simple](/felt-style-language/types-of-visualizations/simple-visualizations) | One uniform style for every feature; raster imagery as-is | Points, lines, polygons, raster | | [Categorical](/felt-style-language/types-of-visualizations/categorical-visualizations) | Color (or icon) by a discrete category | Points, lines, polygons, raster | | [Numeric](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size) | Vary color or size by a numeric value (choropleths, proportional symbols) | Points, lines, polygons, raster | | [Heatmaps](/felt-style-language/types-of-visualizations/heatmaps) | Point density as a smooth surface | Points | | [H3](/felt-style-language/types-of-visualizations/h3) | Aggregate points into hexagonal bins | Points | | [Raster](/felt-style-language/types-of-visualizations/raster) | Imagery, single/multiband numeric, categorical, and hillshade | Raster | Each page lists the geometry types it applies to, the properties that matter, and worked examples. For the values you'll plug into these styles, see [Colors & palettes](/felt-style-language/colors-and-palettes), [Icons](/felt-style-language/icons), and [Classification methods](/felt-style-language/classification-methods). # Simple visualizations Simple visualizations are those that show each feature in a vector dataset using the same style or the image as it is in raster ones. Simple visualizations must define `"type": "simple"` and a single value for each supported style and label properties. ### Example The Airports layer in Felt is an example of a simple visualization using a vector dataset ![](/files/wctwlswQb42X461OVWtv) and is defined by the following style: ```json { "attributes": { "ele": {"displayName": "Elevation (meters)"}, "faa": {"displayName": "FAA Code"}, "iata": {"displayName": "IATA Code"}, "icao": {"displayName": "ICAO Code"}, "name": {"displayName": "Name"}, "name_en": {"displayName": "Name (EN)"}, "wikipedia": {"displayName": "Wikipedia entry"} }, "config": {"labelAttribute": ["name_en", "name"]}, "filters": [["name", "isnt", null], "and", ["name", "ne", ""]], "label": { "color": "hsl(40,30%,40%)", "fontSize": {"linear": [[12, 12], [20, 20]]}, "fontStyle": "Normal", "fontWeight": 400, "haloColor": "hsl(40,20%,85%)", "haloWidth": 1.5, "justify": "auto", "letterSpacing": 0.1, "lineHeight": 1.2, "maxLineChars": 10, "maxZoom": 23, "minZoom": 10, "offset": [8, 0], "padding": 10, "placement": ["E", "W"] }, "legend": {}, "paint": { "color": "hsl(40,30%,80%)", "highlightColor": "#EA3891", "highlightStrokeColor": "#EA3891", "highlightStrokeWidth": {"linear": [[3, 0], [20, 2]]}, "isSandwiched": false, "opacity": 1, "size": {"linear": [[3, 1], [20, 6]]}, "strokeColor": "hsl(40,20%,55%)", "strokeWidth": {"linear": [[3, 0.5], [20, 2]]} }, "version": "2.3.1" } ``` {% hint style="info" %} The `{"linear": [[zoom, value], …]}` objects used for `size`, `fontSize`, and `strokeWidth` above are **interpolators** — values that change with zoom level. See [Zoom-based styling](/felt-style-language/zoom-based-styling) and [Interpolators](/felt-style-language/zoom-based-styling/interpolators) for the full syntax; plain numbers work anywhere an interpolator does. {% endhint %} Raster layers can also use `simple` to display imagery as-is — see [Raster visualizations](/felt-style-language/types-of-visualizations/raster). ### More patterns **Icon markers (points).** Set `iconImage` to draw points as icons; the icon takes the layer's `color` and `size`. See [Icons](/felt-style-language/icons) for the full catalog. ```json { "version": "2.3.1", "type": "simple", "filters": ["status", "in", ["active"]], "paint": { "iconImage": "hospital", "iconFrame": "frame-circle", "color": "#E74C3C", "size": 4, "opacity": 0.9, "isClickable": true, "isHoverable": true }, "legend": {} } ``` **Road-style casing (lines).** A [paint array](/felt-style-language/style-definition-blocks/the-paint-block#paint-arrays-casing-and-layered-rendering) renders last-to-first, so the wider casing layer goes second (underneath) and the narrower fill goes first (on top). ```json { "version": "2.3.1", "type": "simple", "config": {"labelAttribute": ["name"]}, "paint": [ {"color": "#FFFFFF", "size": 4, "lineCap": "round", "lineJoin": "round", "isClickable": true}, {"color": "#374151", "size": 8, "lineCap": "round", "lineJoin": "round"} ], "label": { "color": "auto", "haloColor": "auto", "haloWidth": 2, "placement": "Above", "minZoom": 12 }, "legend": {} } ``` # Categorical visualizations Categorical visualizations use a categorical attribute and the categories within it to apply styling to discrete categories of the attribute. (On raster datasets, categories are raw pixel values instead — see [Raster visualizations](/felt-style-language/types-of-visualizations/raster).) Categorical visualizations are defined using `"type": "categorical"` and, for every supported style and label property used, either a single value that will apply to all categories or an array of different values for each category. You can list the `categories` explicitly, or use a shortcut when you don't know the exact values: `{"type": "top", "count": N}` keeps the N most common values (vector), and `{"type": "all"}` covers every unique pixel value (raster). When `showOther: true` is combined with an **explicit** `categories` array, paint/label arrays need **N + 1** values — the extra one styles the "Other" bucket. For colors, prefer a [`@palette`](/felt-style-language/colors-and-palettes) shortcut over a hand-built array. ### Example The Global Power Plants layer in Felt is an example of a categorical layer on a vector dataset ![](/files/DK11QRpkbreaYa33GkZ5) and is defined by the following style ```json { "version": "2.3.1", "type": "categorical", "config": { "categoricalAttribute": "primary_fuel", "categories": ["Solar", "Hydro", "Wind", "Gas", "Coal", "Oil", "Nuclear"], "showOther": false }, "legend": {"displayName": {}}, "attributes": { "capacity_mw": {"displayName": "Capacity (MW)"}, "name": {"displayName": "Name"}, "primary_fuel": {"displayName": "Primary Fuel"} }, "paint": { "color": [ "#E5C550", "#7AB6C2", "#AB71A4", "#CC615C", "#AD7B68", "#EB9360", "#DEA145" ], "isSandwiched": false, "opacity": 1, "size": [{"linear": [[3, 1.5], [20, 8]]}] } } ``` Notice that we are saying that the `primary_fuel` data attribute will be used to categorize elements and that the possible values of that attribute that we are interested in are `"Solar"`, `"Hydro"`, `"Wind"`, `"Gas"`, `"Coal"`, `"Oil"` and `"Nuclear"` (colors are assigned in the same order). Also notice that we are defining either a single value that will apply to all categories (i.e. `size`) or a value for each category (i.e. `color`) ### More patterns **Palette shortcut + "top N".** When you don't know the exact category values, let Felt pick the most common ones and color them from a categorical palette: ```json { "version": "2.3.1", "type": "categorical", "config": { "categoricalAttribute": "fuel_type", "categories": {"type": "top", "count": 10}, "showOther": true }, "paint": { "color": "@catPalette4", "size": 4, "strokeColor": "auto", "strokeWidth": 1, "opacity": 0.9, "isClickable": true }, "legend": {"displayName": "auto"} } ``` **A different icon per category.** `iconImage` and the paint arrays follow the same N (or N + 1 with `showOther`) pattern as `color`: ```json { "version": "2.3.1", "type": "categorical", "config": { "categoricalAttribute": "facility_type", "categories": ["hospital", "school", "fire_station"], "showOther": true }, "paint": { "iconImage": ["hospital", "school", "fire", "dot"], "iconFrame": "frame-circle", "color": ["#E74C3C", "#3498DB", "#E67E22", "#95A5A6"], "size": 4, "opacity": 0.9, "isClickable": true }, "legend": { "displayName": { "hospital": "Hospitals", "school": "Schools", "fire_station": "Fire Stations" } } } ``` **Styling "Other" separately.** With `showOther: true`, the trailing array element targets the "Other" bucket — here it is made smaller and more transparent than the named categories: ```json { "version": "2.3.1", "type": "categorical", "config": { "categoricalAttribute": "status", "categories": ["active", "pending", "closed"], "showOther": true }, "paint": { "color": ["#22C55E", "#F59E0B", "#EF4444", "#9CA3AF"], "size": [8, 8, 8, 4], "opacity": [0.9, 0.9, 0.9, 0.5], "strokeColor": "auto", "strokeWidth": 1 }, "legend": {"displayName": "auto"} } ``` {% hint style="info" %} Lines support color variation per category but not per-category icons. For categorical **polygons**, color is the only visual variable — keep to 5–7 categories so large filled areas stay distinguishable. Lines can still use a [paint array](/felt-style-language/style-definition-blocks/the-paint-block#paint-arrays-casing-and-layered-rendering) for casing under each colored category. {% endhint %} # Numeric visualizations (color & size) Numeric visualizations use a numeric attribute to either vary colors or sizes between ranges of values and are defined in FSL with `"type": "numeric"`. {% hint style="info" %} Vary **color** *or* **size**, not both at once — pick the single visual variable that best carries your message. Color reads as a choropleth; size reads as proportional symbols ("bigger = more"). Polygons support color only. {% endhint %} Ranges are calculated across discrete steps using a classification method, or on a continuous scale between an attribute’s min and max values. See [Classification methods](/felt-style-language/classification-methods) for the full list (jenks, quantiles, equal-intervals, stddev, geo-intervals, continuous) and how to express `steps`. #### **Color** Color `numeric` values in your data using the `color` property. **Stepped color** This map shows the percent of renter occupied housing units by US county. Each county is colored according to the step of ranges it falls into using a sequential color palette where light colors are assigned to low values and darker colors for high values. ![Map link: Percent renter occupied housing by county](/files/gSpDmSsTRydhufstabFB) The style for this map is defined * with the visualization `type: numeric` * `numericAttribute: "Renter occupied (%)"` and the computed `steps` using Jenks Natural Breaks over 5 classes * the sequential `@galaxy` palette, which Felt expands to one color per class — light colors for low values, dark for high ```json { "version": "2.3.1", "type": "numeric", "config": { "numericAttribute": "Renter occupied (%)", "steps": {"type": "jenks", "count": 5} }, "paint": { "color": "@galaxy", "opacity": 0.9, "strokeColor": "auto", "strokeWidth": 0.5, "isSandwiched": true }, "legend": {"displayName": "auto"} } ``` **Continuous Color** The map below shows average accumulated precipitation in the State of California between the years 1900 - 1960 and is colored along a continuous range between the min and max of the precipitation values. ![Map link: Average annual precipitation](/files/w4X6jCav1RrMyUMtb6b2) In this case, the numeric style is applied using a continuous method. * In the `config` block, `numericAttribute: PRECIP` uses the `{"type": "continuous"}` steps shortcut, so values scale across the attribute's full min–max range * The `color` property uses the sequential `@purpYl` palette, whose colors are interpolated to give each precipitation value a unique color ```json { "version": "2.3.1", "type": "numeric", "config": { "numericAttribute": "PRECIP", "steps": {"type": "continuous"} }, "paint": { "color": "@purpYl", "opacity": 0.9, "strokeColor": "auto", "strokeWidth": 0, "isClickable": false, "isSandwiched": true }, "legend": {"displayName": "auto"} } ``` {% hint style="info" %} *Any time there are fewer colors than values in a numeric style, they are interpolated in the (*[*hcl color space*](https://en.wikipedia.org/wiki/HCL_color_space)*).* {% endhint %} Numeric color also works on raster datasets, using `band` instead of `numericAttribute` — see [Raster visualizations](/felt-style-language/types-of-visualizations/raster). #### Size Size `numeric` values in your point or line data using the `size` property. **Stepped size** The map below shows earthquakes over the past year sized with 5 manually defined steps. ![](/files/7XOY3rNidIYKIMtYW2U8) In this case, the numeric style is applied using a classed method. * In the `config` block, the `numericAttribute: mag` has manually-defined `steps` for 5 classes * The `size` property has an array of five sizes, one for each defined class ```json { "version": "2.3.1", "type": "numeric", "config": {"numericAttribute": "mag", "steps": [4.5, 5.5, 6, 7, 7.5, 8.2]}, "legend": {"displayName": "auto"}, "paint": { "size": [5, 10, 12, 14, 16], "color": "hsl(0, 13%, 45%)", "opacity": 0.9, "strokeColor": "hsl(0, 13%, 88%)", "strokeWidth": 1.5 } } ``` *Map link:* [*Earthquakes Stepped Size*](https://felt.com/map/FSL-doc-Earthquakes-Stepped-Size-CQriP6TDT1enA5G6uNhU9CB?lat=-7.797738\&lon=-64.51902\&zoom=4) **Continuous size** The map below shows tonnes of corn that have been exported from Ukraine since August 2022 under the [UN’s Black Sea Grain Initiative](https://www.un.org/en/black-sea-grain-initiative). The symbol size for each country is proportionate to its value in the data. ![Map link: Black Sea Grain Initiative](/files/kDhnjDUGyMVhMYnR2tun) To do this the min and max `steps` from the `numericAttribute: tonnes` are interpolated to be proportionately sized between a min and max point size — `size:[5,48]` ```json { "version": "2.3.1", "type": "numeric", "config": { "steps": [33000, 2344684], "numericAttribute": "tonnes", "labelAttribute": ["category"] }, "label": { "minZoom": 1, "color": "#5a5a5a", "fontSize": 14, "fontStyle": "Normal", "fontWeight": 500, "haloColor": "#d0d0d0", "haloWidth": 1.5, "offset": [8, 0] }, "legend": {"displayName": {"0": "2.34M", "1": "714.65K", "2": "33K"}}, "paint": { "size": [5, 48], "color": "hsl(22, 78%, 65%)", "opacity": 0.9, "strokeColor": "hsl(22, 78%, 88%)", "strokeWidth": 1.5 } } ``` #### Notes on `steps`, `color`, and `size` * **Let Felt compute breaks** when you don't have the data in front of you: `"steps": {"type": "jenks", "count": 5}`. Provide explicit breaks (`[0, 3, 5, 7, 9]`) when you know the values you want. See [Classification methods](/felt-style-language/classification-methods). * **Classed arrays** carry one value per class. With `N` break points you get `N − 1` classes, so explicit `color`/`size` arrays need `N − 1` entries. * **Continuous `size`** is written as `[min, max]` (e.g. `[3, 30]`) and scales smoothly; proportional-symbol sizes typically range 3–30 px for points. On **lines**, `size` is width in pixels (typically 1–20 px), not a radius. * **Continuous size legends** use inverted indices for historical reasons: `"0"` labels the maximum value, `"1"` the midpoint, and `"2"` the minimum (as in the example above). Continuous **color** legends run the intuitive way: `"0"` is the minimum. See [Legends](/felt-style-language/legends). * **Icons can vary by value too** — set `iconImage` and let `size` (or `color`) carry the numeric variable: ```json { "version": "2.3.1", "type": "numeric", "config": {"numericAttribute": "beds", "steps": {"type": "jenks", "count": 4}}, "paint": { "iconImage": "hospital", "iconFrame": "frame-circle", "color": "#E74C3C", "size": [3, 4, 5, 6], "opacity": 0.9, "isClickable": true }, "legend": {"displayName": "auto"} } ``` # Heatmaps Heatmaps are used to visualize the density of points on a map. Heatmaps work on point layers only, and show concentration rather than individual feature values — if you need to read a specific attribute, use a [numeric](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size) visualization instead. The `config` block must be empty (`{}`), and heatmaps support no popups or labels. Heatmap visualizations are defined using `"type": "heatmap"` and allow the following properties to be set: | Field name | Type | Default | Typical range | Description | | ----------- | ------ | ----------- | ------------- | --------------------------------------------------------------------------------------------------------------- | | `color` | string | `"@geyser"` | — | A [heatmap palette](/felt-style-language/colors-and-palettes#heatmap-palettes) name, from less density to more. | | `size` | number | 10 | 1–30 px | Radius of influence in pixels. Larger = smoother, smaller = more detailed. | | `intensity` | number | 0.5 | 0.1–3.0 | How quickly density saturates. Higher = more contrast. | | `opacity` | number | 0.9 | 0–1 | Transparency. | Tune `size` for the zoom you expect to view at — larger at low zoom, smaller at high zoom. This is an example of a heatmap visualization ![](/files/C2vt8DBqzgRiZC3rorOO) defined with the following visualization ```json { "version": "2.3.1", "type": "heatmap", "config": {}, "legend": {"displayName": {"0": "Low", "1": "High"}}, "paint": {"color": "@purpYlPink", "size": 10, "intensity": 0.2} } ``` # H3 H3 visualization is a way to aggregate point data into a grid of H3 cells. H3 visualizations are defined using `"type": "h3"` . They generally share the same properties and behaviors as [color range visualizations for polygons](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size). Properties of specific relevance to H3 are: | Field name | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aggregation` | The aggregation method that will be used on points within each cell. Supported values are `count` (default), `sum`, `min`, `max`, and `mean` . | | `binMode` | `fixed` (default), `low`, `medium`, `high`, or `auto`. `fixed` keeps the cell resolution constant at all zooms; the other modes pick a resolution from the current zoom, where `low` produces larger hexagons and `high` smaller ones (`auto` behaves like `medium`). | | `baseBinLevel` | Required. If `binMode` is `fixed`, this is the [H3 cell resolution](https://h3geo.org/docs/core-library/restable/) that the map will use. H3 cells vary from resolution 0 (largest) to resolution 15 (smallest). In the zoom-adaptive modes, this is the reference resolution used for calculating class breaks — you will get best results choosing a resolution that matches the `fixed` resolution you would choose for the most commonly-viewed zoom of your map. | | `numericAttribute` | The numeric column to aggregate. Required unless `aggregation` is `count` , in which case the column choice is irrelevant. | This is an example of an H3 visualization

defined with the following style ```json { "config": { "steps": {"type": "quantiles", "count": 5}, "aggregation": "sum", "binMode": "fixed", "baseBinLevel": 3, "numericAttribute": "capacity_mw" }, "paint": {"color": "@riverine"}, "type": "h3", "version": "2.3.1", "label": {}, "legend": {"displayName": "auto"} } ``` `aggregation: "count"` doesn't need a `numericAttribute` — it counts the points in each cell: ```json { "version": "2.3.1", "type": "h3", "config": { "aggregation": "count", "baseBinLevel": 4, "binMode": "medium", "steps": {"type": "continuous"} }, "paint": {"color": "@galaxy", "opacity": 0.85, "strokeColor": "auto", "strokeWidth": 1}, "legend": {"displayName": "auto"} } ``` ### Aggregation popups H3 cells display **aggregated** values, not raw feature attributes. Their popups reference special attribute names — `"felt:cluster_size"` for the feature count, and `"felt:sum:column"`, `"felt:mean:column"`, `"felt:min:column"`, `"felt:max:column"` for aggregates. If no `popup` is provided, Felt auto-generates sensible stats from the aggregation type. See [the popup block](/felt-style-language/style-definition-blocks/the-popup-block#h3-aggregation-attributes). ```json { "version": "2.3.1", "type": "h3", "config": { "numericAttribute": "revenue", "aggregation": "sum", "baseBinLevel": 5, "binMode": "medium", "steps": {"type": "jenks", "count": 5} }, "paint": {"color": "@copper", "opacity": 0.85, "strokeColor": "auto", "strokeWidth": 1, "isClickable": true}, "popup": { "titleAttribute": "felt:sum:revenue", "keyAttributes": ["felt:cluster_size", "felt:mean:revenue", "felt:min:revenue", "felt:max:revenue"] }, "attributes": {"revenue": {"displayName": "Revenue ($)", "format": {"thousandSeparated": true, "mantissa": 0}}}, "legend": {"displayName": "auto"} } ``` {% hint style="info" %} H3 cells are rendered as polygons, so `size` has no effect on them — control cell size with `baseBinLevel` (H3 resolution) and `binMode` (how that resolution adapts to zoom). The `attributes` block renames the **source column**, so `"revenue"` makes a popup entry read "Sum of Revenue ($)". {% endhint %} # Raster visualizations Raster layers are styled with one of five `type` values. They share a common set of `config` options and **never support popups or labels**. | Mode | `type` | Use it for | | ------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------- | | [Image](#image-simple) | `simple` | Display the raster as-is (satellite, aerial, base tiles) | | [Numeric — single band](#numeric-single-band) | `numeric` | Classify one band (elevation, temperature, a hazard index) | | [Numeric — multiband / raster algebra](#numeric-multiband-raster-algebra) | `numeric` | Compute a spectral index (NDVI, NDMI, NDWI) from several bands | | [Categorical](#categorical) | `categorical` | Discrete pixel classes (land cover, soil types) | | [Hillshade](#hillshade) | `hillshade` | Relief shading from elevation, optionally tinted | ## Shared `config` options | Option | Notes | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `band` | Which band to read (1-indexed). Numeric/hillshade. | | `steps` | Classification — see [Classification methods](/felt-style-language/classification-methods). `{"type": "continuous"}` for smooth, or breaks like `[0, 500, 1000]`. | | `method` | Spectral-index formula and band mapping (multiband only). | | `categories` | Categorical only — `{"type": "all"}` for every pixel value, or an explicit array. | | `noData` | Value(s) to exclude, e.g. `[-9999]` for voids or `[0]` for no-data. | | `rasterResampling` | Numeric and tinted hillshade only — categorical rasters reject it (they always resample nearest). `"nearest"` keeps exact pixel values; `"linear"` interpolates (use for continuous imagery/elevation). | | `outOfRangeValues` | `"color"` clamps to the nearest class color; `"hide"` makes them transparent. | In `paint`, `color` takes a [raster palette](/felt-style-language/colors-and-palettes#raster-palettes) or an explicit color array, plus `opacity` and `isSandwiched` (render below basemap water/roads). ## Image (simple) Renders the image with no classification — just `opacity` and resampling. ```json { "version": "2.3.1", "type": "simple", "config": {}, "paint": {"opacity": 0.93, "isSandwiched": false} } ``` ## Numeric — single band Classify one band. Prefer `continuous` for smooth data (elevation, temperature); use breaks for discrete groups (hazard levels). ```json { "version": "2.3.1", "type": "numeric", "config": { "band": 1, "steps": {"type": "continuous"}, "noData": [-9999], "rasterResampling": "linear" }, "paint": {"color": "@mplVirdis", "opacity": 1, "isSandwiched": false}, "legend": {"displayName": "auto"} } ``` A style is **classed** when `steps` has more than two break points — the color array then needs one entry per class (`N` break points produce `N − 1` classes; extra colors are ignored). With exactly two steps (`[min, max]`, as below), the style is **continuous**: the whole color array is interpolated smoothly across the range: ```json { "version": "2.3.1", "type": "numeric", "config": {"band": 1, "steps": [-154.46, 7987.46]}, "legend": {"displayName": {"0": "-154.46", "1": "7.99K"}}, "paint": { "opacity": 1, "isSandwiched": false, "color": ["#454b9f", "#2d79a4", "#18a2a9", "#8cc187", "#e5d96c", "#eab459", "#ef8b45", "#e66250", "#db2d5e"] } } ``` ## Numeric — multiband (raster algebra) Compute a derived index from multiple bands before classifying. The `config.method` names the index and maps its inputs to band numbers, and `band` lists every band used. Supported indices: * **NDVI** — `(NIR − R) / (NIR + R)`, vegetation health. Requires `NIR`, `R`. * **NDMI** — `(NIR − SWIR) / (NIR + SWIR)`, moisture. Requires `NIR`, `SWIR`. * **NDWI** — `(G − NIR) / (G + NIR)`, water. Requires `G`, `NIR`. Band numbers are 1-indexed and sensor-specific (Landsat 8/9: R=4, G=3, NIR=5, SWIR=6 · Sentinel-2: R=4, G=3, NIR=8, SWIR=11). ```json { "version": "2.3.1", "type": "numeric", "config": { "method": {"NDVI": {"NIR": 5, "R": 4}}, "band": [5, 4], "steps": {"type": "continuous"}, "noData": [0], "rasterResampling": "nearest", "outOfRangeValues": "hide" }, "paint": {"color": "@cbRedYlGrn", "opacity": 1, "isSandwiched": false}, "legend": {"displayName": "auto"} } ``` NDVI output ranges from −1 (water/bare) to 1 (dense vegetation); classify it with explicit breaks (e.g. `[-1, -0.2, 0, 0.2, 0.4, 0.6, 1]`) for labelled classes. Good starting points: NDVI → `[-0.5, 0.5]` with `@cbRedYlGrn`; NDWI → `[-0.5, 0.25]` and NDMI → `[-0.5, 0.5]` with `@feltVibrant`. ## Categorical Raster categories are **raw pixel values** (integers), so there is no `categoricalAttribute`. Use `{"type": "all"}` when you don't know the values, or an explicit array when you do, with one color per value. Don't set `rasterResampling` here — categorical rasters always use nearest resampling automatically (the property is rejected on this type), since linear interpolation would blend category codes into invalid values. ```json { "version": "2.3.1", "type": "categorical", "config": {"categories": [1, 2, 3, 4, 5]}, "paint": { "color": ["#228B22", "#4682B4", "#DAA520", "#8B4513", "#808080"], "opacity": 0.85, "isSandwiched": true }, "legend": { "displayName": {"1": "Forest", "2": "Water", "3": "Cropland", "4": "Bare Soil", "5": "Urban"} } } ``` For raster categorical, use the [vector categorical palettes](/felt-style-language/colors-and-palettes#categorical-distinct-colors) (`@catPalette1`…`@catPalette7`). A fully-transparent class can be expressed as `"rgba(0, 0, 0, 0)"`. ## Hillshade Simulates light and shadow on terrain. **Plain** hillshade is grayscale relief (`config` carries just `band`; `paint` carries `source` and `intensity`). **Tinted** hillshade overlays a hypsometric color ramp — add `steps` to `config` and `color` to `paint`; only do this when elevation coloring is wanted. | Paint property | Default | Notes | | -------------- | ------- | ----------------------------------------------------------------------------- | | `source` | 315 | Light azimuth in degrees (0 = North, 90 = East). 315 (northwest) is standard. | | `intensity` | 0.5 | Shadow intensity 0–1; higher = more dramatic relief. | | `color` | — | Raster palette or color array (tinted only), low → high elevation. | ```json { "version": "2.3.1", "type": "hillshade", "config": {"band": 1}, "paint": {"source": 315, "intensity": 0.5, "isSandwiched": true}, "legend": {} } ``` Tinted, classifying elevation like any numeric raster (use `rasterResampling: "linear"` and `noData` for voids): ```json { "version": "2.3.1", "type": "hillshade", "config": { "band": 1, "steps": {"type": "quantiles", "count": 6}, "noData": [-9999], "rasterResampling": "linear" }, "paint": {"color": "@terrain", "source": 315, "intensity": 0.5, "isSandwiched": true}, "legend": {"displayName": "auto"} } ``` # Colors & palettes Colors appear throughout the Felt Style Language — in `paint` (`color`, `strokeColor`), in `label` (`color`, `haloColor`), and in legends. There are three ways to express a color: 1. **A literal color** — a hex, HSL, or RGB string. 2. **A smart color** — the keyword `"auto"`, which Felt resolves to a contrasting color at render time. 3. **A palette shortcut** — a named, multi-color ramp like `@galaxy`, used by data-driven (categorical, numeric, heatmap, H3) visualizations. ## Literal colors Any of these string formats are accepted wherever a single color is expected: ```json { "color": "#3B82F6", "strokeColor": "hsl(217, 80%, 40%)", "haloColor": "rgb(38, 113, 0)" } ``` `rgba(...)` is also supported and is handy for fully-transparent fills (for example, a transparent "Other"/background class in a categorical raster: `"rgba(0, 0, 0, 0)"`). ## Smart color: `"auto"` `"auto"` computes a contrasting color automatically, based on the current map theme and the colors around it. It keeps strokes and label halos legible without hard-coding a value that might clash on a dark basemap or against a particular fill. Prefer `"auto"` for: * `strokeColor` on points and polygons * `color` and `haloColor` on labels …unless a specific color has been requested. ```json { "paint": { "color": "#8F7EBF", "strokeColor": "auto", "strokeWidth": 1 }, "label": { "color": "auto", "haloColor": "auto", "haloWidth": 1.5 } } ``` ## Palette shortcuts For any **data-driven** visualization, prefer a named palette over a hand-built color array. Palettes are referenced with an `@` prefix (for example `"color": "@galaxy"`) and Felt expands them to the right number of colors for your classes or categories. {% hint style="info" %} Only the palette names listed below are valid. Use **sequential** palettes for single-direction data (population, elevation), and **diverging** palettes for data with a meaningful midpoint (change from a baseline, temperature anomaly). Reserve literal hex/HSL colors for simple (uniform) styles or when a specific color is requested. {% endhint %} ### Vector palettes Used by categorical, numeric, heatmap, and H3 visualizations on points, lines, and polygons. #### Sequential (low → high) | Palette | Description | | ------------ | ---------------------------------- | | `@galaxy` | Purple to yellow (popular default) | | `@ylRed` | Yellow to red | | `@ylGrn` | Yellow to green | | `@purpYl` | Purple to yellow | | `@pinkYl` | Pink to yellow | | `@lightning` | Lightning gradient | | `@copper` | Copper gradient | | `@spruce` | Spruce green | | `@riverine` | Water gradient | | `@neptune` | Blue gradient | | `@violet` | Violet gradient | | `@purple` | Purple gradient | #### Diverging (two directions from a center) | Palette | Description | | --------- | -------------------------------- | | `@bluRd` | Blue to red | | `@tealOr` | Teal to orange (colorblind-safe) | | `@bluBr` | Blue to brown | | `@grnOr` | Green to orange | | `@purGrn` | Purple to green | | `@weath` | Weather gradient | #### Categorical (distinct colors) | Palette | Description | | ------------------------------- | ------------------------------ | | `@catPalette1` … `@catPalette7` | Categorical color schemes | | `@catPalettePT1` | Paul Tol categorical palette 1 | | `@catPalettePT2` | Paul Tol categorical palette 2 | Sequential and diverging vector palettes also come in numbered variants that request a specific number of colors — for example `@galaxy7`, `@galaxy8`, `@galaxy9`. Variants exist for 7, 8, and 9 colors (`@lightning` also has a 6-color variant). The unnumbered name lets Felt pick the right count for you, which is usually what you want. ### Heatmap palettes Used by `heatmap` visualizations, ordered from least to most density. | Palette | Description | | ---------------- | ------------------------------------------ | | `@geyser` | Green → beige → orange → red (default) | | `@redOrHeat` | Yellow → orange → red → magenta | | `@purpYlHeat` | Light yellow → coral → pink → purple | | `@lightningHeat` | Purple → teal → green → yellow | | `@ylGrnHeat` | Dark teal → green → yellow | | `@bluRdHeat` | Blue → gray → red (diverging feel) | | `@tealRedHeat` | Teal → green → yellow → orange → pink | | `@purpYlPink` | Purple → teal → yellow → orange → red/pink | ### Raster palettes Used by numeric, hillshade, and raster-algebra visualizations. #### Sequential | Palette | Description | | ---------------- | ------------------------------------------------------------------------------------- | | `@feltGrays` | Grayscale gradient | | `@cbBlues` | ColorBrewer blues | | `@cbPurples` | ColorBrewer purples | | `@feltPinks` | Pink gradient | | `@cmOceanGreens` | Ocean greens gradient | | `@pattFeltOcean` | Teal ocean gradient | | `@cmOceanDeep` | Deep ocean gradient | | `@mpaInferno` | Matplotlib inferno — note the spelling: `mpa`, not `mpl` | | `@mplPlasma` | Matplotlib plasma | | `@mplVirdis` | Matplotlib viridis, perceptually uniform — note the spelling: `Virdis`, not `Viridis` | | `@cividis` | Cividis — colorblind-safe | | `@feltYlRed` | Felt yellow to red | | `@veg` | Vegetation gradient | #### Diverging | Palette | Description | | -------------- | -------------------------------------- | | `@feltWeath` | Felt weather gradient | | `@feltHeat` | Felt heat gradient | | `@feltVibrant` | Felt vibrant gradient | | `@nclBlOrRed` | NCL blue-orange-red diverging | | `@cbRedYlGrn` | ColorBrewer red-yellow-green diverging | | `@cbBrBG` | ColorBrewer brown-blue-green diverging | #### Terrain | Palette | Description | | -------------- | -------------------------- | | `@terrain` | Terrain elevation gradient | | `@rTerrain` | R terrain gradient | | `@feltHypso` | Felt hypsometric tints | | `@wikiTerrain` | Wikipedia terrain gradient | #### Vegetation | Palette | Description | | ----------- | -------------------------- | | `@nasaNDVI` | NASA NDVI vegetation index | For raster **categorical** layers, use the vector categorical palettes above (`@catPalette1` … `@catPalette7`, `@catPalettePT1`, `@catPalettePT2`). Raster palettes also support numbered variants to request a specific number of steps — for example `@feltGrays2`, `@feltGrays3`, … `@feltGrays9`. ## How colors map to classes When a palette or color array drives a data-driven visualization, the number of colors should line up with the number of classes or categories: * **Categorical:** one color per category. With `showOther: true` and an explicit `categories` array, provide **N + 1** colors — the extra one styles the "Other" bucket. * **Classed numeric:** **N break points produce N − 1 classes**, so an explicit color array needs N − 1 entries. * **Continuous:** provide **2 or more** colors and Felt interpolates smoothly between them in the [HCL color space](https://en.wikipedia.org/wiki/HCL_color_space). A palette shortcut handles all of this for you — Felt expands `@galaxy` to exactly the colors it needs. Reach for explicit arrays only when you want precise control over each color. # Icons Point layers can be drawn as icons instead of plain circles. Set `iconImage` in the `paint` block to a built-in icon slug (or an emoji), and the icon takes on the layer's `color` and `size`. Icons work in [simple](/felt-style-language/types-of-visualizations/simple-visualizations), [categorical](/felt-style-language/types-of-visualizations/categorical-visualizations), and [numeric](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size) point visualizations. In categorical and numeric styles, `iconImage` (and the other paint properties) may be an array so each category or class gets its own marker. ## Icon paint properties | Property | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------------------------------- | | `iconImage` | string \| string\[] | An icon slug from the catalog below, or an emoji in the form `"emoji::name:"`. | | `iconFrame` | string | `"none"`, `"frame-circle"`, or `"frame-square"`. Built-in icons only (not emojis). | | `iconRotation` | number \| string | Rotation in degrees, or the name of a column to rotate by. | | `iconHideOnZoom` | number | Zoom level below which icons are drawn as plain points instead. Optional. | When `iconImage` is set, `color` fills the icon and `size` scales it (the same `size` you would use for a circle radius). ## Examples A single icon marker, framed in a circle: ```json { "version": "2.3.1", "type": "simple", "paint": { "iconImage": "hospital", "iconFrame": "frame-circle", "color": "#E74C3C", "size": 4, "opacity": 0.9, "isClickable": true }, "legend": {} } ``` To give each category its own icon, make `iconImage` an array — see the icon-per-category example in [Categorical visualizations](/felt-style-language/types-of-visualizations/categorical-visualizations). ## Available icons {% hint style="warning" %} Use only the icon slugs listed here. Invented names will not render. {% endhint %} * **Shapes**: `dot`, `square`, `diamond`, `triangle`, `x`, `plus`, `circle-line`, `circle-slash`, `circle-triangle`, `circle-x`, `circle-plus`, `star`, `heart`, `hexagon`, `octagon` * **Arrows & directions**: `arrow-up`, `chevron-up`, `double-chevron-up`, `direction-up` (combine with `iconRotation` to point them anywhere) * **Transportation**: `pedestrian`, `bicycle`, `wheelchair`, `airport`, `car`, `bus`, `train`, `truck`, `ferry`, `sailboat`, `electric-service`, `gas-service`, `blood-clinic`, `badge`, `traffic-light`, `traffic-cone`, `road-sign-caution` * **Activities & places**: `person`, `restroom`, `house`, `work`, `letter`, `hotel`, `factory`, `hospital`, `religious-facility`, `school`, `government`, `university`, `bank`, `landmark`, `museum`, `clothing`, `shopping`, `store`, `bar`, `pub`, `cafe`, `food`, `park`, `amusement-park`, `camping-tent`, `cabin`, `picnic`, `water-refill`, `trailhead`, `guidepost`, `viewpoint`, `camera`, `us-football`, `football`, `tennis`, `binoculars`, `swimming` * **Infrastructure**: `zap`, `battery-full`, `battery-half`, `battery-low`, `boom`, `radar`, `wind-turbine`, `solar-panel`, `antenna`, `telephone-pole`, `oil-well`, `oil-barrel`, `railroad-track`, `bridge`, `lighthouse`, `lock-closed`, `lock-open`, `wifi`, `trash`, `recycle` * **Nature**: `tree`, `flower`, `leaf`, `fire`, `mountain`, `snowy-mountain`, `volcano`, `island`, `wave`, `hot-springs`, `water`, `lake`, `ocean`, `animal`, `bird`, `duck`, `dog`, `fish`, `beach`, `wetland` * **Weather**: `sun`, `moon`, `cloud`, `partial-sun`, `rain`, `lightning`, `snowflake`, `wind`, `snow`, `fog`, `sleet`, `hurricane` * **Signs**: `warning`, `parking`, `info`, `circle-exclamation` ## Emojis To use an emoji as a marker, write it as `"emoji::name:"` — note the double colon after `emoji` and the trailing colon. For example: `"emoji::fire:"`, `"emoji::tree:"`. `iconFrame` does not apply to emojis. Prefer built-in icons unless an emoji is specifically requested. ```json { "version": "2.3.1", "type": "simple", "paint": { "iconImage": "emoji::fire:", "size": 6 }, "legend": {} } ``` # Classification methods [Numeric](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size), [H3](/felt-style-language/types-of-visualizations/h3), and [raster](/felt-style-language/types-of-visualizations/raster) (numeric and tinted hillshade) visualizations all turn a range of values into discrete classes (or a smooth gradient) using the `steps` field in the `config` block. The classification method decides where the breaks between classes fall. ## Methods | Method | What it does | Best for | | ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ | | `continuous` | Smooth gradient, no discrete classes | Proportional symbols, smooth color ramps | | `jenks` | Natural breaks — minimizes variance within each class | Most cases; a good starting point | | `quantiles` | Equal number of features in each class | Balanced representation, evenly distributed data | | `equal-intervals` | Equal-sized value bins | When the value ranges themselves matter | | `stddev` | Classes in 1σ steps with the middle class centered on the mean | Data with a near-normal distribution | | `geo-intervals` | Break points in a geometric progression between min and max | Multiplicative, strongly skewed data (values must be non-negative) | All shortcut methods except `continuous` require a `count`. Raster algebra visualizations support only `continuous` and `equal-intervals`. ## Specifying `steps` There are two ways to define `steps`. **Shortcut (recommended when you don't know the data's distribution).** Name a method and a class count and let Felt compute the break points from the data: ```json { "config": { "numericAttribute": "population_density", "steps": {"type": "jenks", "count": 5} } } ``` For a smooth gradient, use the continuous shortcut: ```json { "config": { "numericAttribute": "temperature", "steps": {"type": "continuous"} } } ``` **Explicit break points (when you know the values you want).** Provide the break points directly: ```json { "config": { "numericAttribute": "magnitude", "steps": [0, 3, 5, 7, 9] } } ``` ## How breaks map to colors and sizes * **Classed:** `N` break points produce `N − 1` classes. An explicit `color` or `size` array must therefore have exactly `N − 1` entries. (A palette shortcut such as `@galaxy` is expanded for you.) * **Continuous:** provide **2 or more** colors and Felt interpolates between them across the full value range. For proportional symbols, give `size: [min, max]` and sizes scale smoothly between those two values. {% hint style="info" %} For choropleths and other classed thematic maps, 5–7 classes usually reads best. For right-skewed data (common with population or income), prefer `quantiles` or `jenks` over `equal-intervals`. When you have the data's min/max on hand, use them to inform the method and breaks. {% endhint %} See [Numeric visualizations](/felt-style-language/types-of-visualizations/numeric-visualizations-color-and-size) for full color and size examples, and [Colors & palettes](/felt-style-language/colors-and-palettes) for palette choices. # Zoom-based styling {% hint style="info" %} Zoom-based styling is useful to change how features and labels are shown at different zoom levels. {% endhint %} Most of the properties used on the [`paint`](/felt-style-language/style-definition-blocks/the-paint-block) and [`label`](/felt-style-language/style-definition-blocks/the-label-block) blocks can be defined using interpolators to enable zoom-based styling — the property tables on those pages mark which ones accept an Interpolator. We support multiple types of interpolators: Step functions, linear, exponential and cubic bezier to enable your map looking like you want at each zoom level. See the [*Interpolators*](/felt-style-language/zoom-based-styling/interpolators) page. An example of a layer changing feature colors depending on the zoom level can be found below ```json "paint": { "color": {"linear": [[14, "red"], [20, "blue"]]} } ``` On zoom levels lower than `14`, features of this layer will be rendered in `red` color. On zoom levels higher than `20`, features of this layer will be rendered in `blue` color. In zooms between `14` and `20`, color will be linearly interpolated between `red` and `blue.`

# Interpolators ### Interpolators Interpolators are functions that use the current zoom level to get you a value. The following interpolators are currently supported: #### Step `{ "step": [output0, Stops[]] }`: Computes discrete results by evaluating a piecewise-constant function defined by stops on a given input. Returns the output value of the stop with a stop input value just less than the input one. If the input value is less than the input of the first stop, `output0` is returned. Stops are defined as pairs of `[zoom, value]` where `zoom` is the minimum zoom level where `value` is returned and `value` can be `number | string | boolean`. Note that stops need to be defined by increasing zoom level. ```jsonc { "step": ["hsl(50,5%,72%)", [[9, "hsl(10,75%,75%)"]]] } // If zoom level is less than 9, "hsl(50,5%,72%)" will be returned // If zoom level is equal or higher than 9, "hsl(10,75%,75%)" will be returned ``` The following image shows the behavior of this definition: ```jsonc { "step": [0, [[0, 0], [100, 100]]]} // Blue { "step": [0, [[0, 0], [50, 50], [100, 100]]]} // Red { "step": [0, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ```

Graph showing a Step interpolator function

#### Linear `{ "linear": Stops[] }`: Linearly interpolates between stop values less than or equal and greater than the input value ```jsonc { "linear": [ [8, 10], [14, 15], [20, 21] ] } // If zoom level is less than 8, 10 is returned // If zoom level is greater or equal than 8 but less than 14, a value linearly interpolated // between 10 and 15 is returned // If zoom level is greater or equal than 14 but less than 20, a value linearly interpolated // between 15 and 21 is returned // If zoom level is greater or equal than 20, 21 is returned ``` The following image shows the behaviour of this definitions ```jsonc { "linear": [[0, 0], [100, 100]]} // Blue { "linear": [[0, 0], [50, 50], [100, 100]]} // Red { "linear": [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]} // Yellow ```

Graph showing a Linear interpolator function

`{ "linear": [number, number] }`: Expands to `{ "linear": [[minZoom, number], [maxZoom, number]] }` ```jsonc { "linear": [8, 10] } // If minZoom is defined as 3 and maxZoom is defined as 20: // If zoom level is less than 3, 8 is returned // If zoom level is between 3 and 20, a value linearly interpolated between 8 and 10 is // returned // If zoom level is greater or equal than 20, 10 is returned ``` Color linear interpolation is done in the HCL color-space #### Exponential `{ "exp": [number, Stops[]] }`: Exponentially interpolates between output stop values less than or equal and greater than the input value. The base parameter controls the rate at which output increases where higher values increase the output value towards the end of the range, lower values increase the output value towards the start of the range, and a base 1 interpolates linearly. The used value is computed as follows : `(Math.pow(base, progress) - 1) / (Math.pow(base, difference) - 1)` ```jsonc { "exp": [ 0.25, [ [0, 25], [10, 100] ] ] } // If zoom level is less than 0, 25 is returned // If zoom level z is between 0 and 10, an interpolation factor is computed between 0 and 10 // and then it's used to interpolate between 25 and 100 // If zoom level is equal or higher than 10, 100 will be returned ``` The following images shows the behaviour of this definition ```jsonc { "exp": [0.25, [[0, 0], [100, 100]]]} // Blue { "exp": [0.25, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [0.25, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/GqTmSrwwyf5d5DFHDU8c) ```jsonc { "exp": [0.5, [[0, 0], [100, 100]]]} // Blue { "exp": [0.5, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [0.5, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/Hnhkiy97P6IXxyXVT6wg) ```jsonc { "exp": [0.75, [[0, 0], [100, 100]]]} // Blue { "exp": [0.75, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [0.75, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/GDNHk6BBeYtpHwCaXqQi) ```jsonc { "exp": [1, [[0, 0], [100, 100]]]} // Blue { "exp": [1, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [1, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/EXSrRTG1Gpfc2GBoJ5iL) ```jsonc { "exp": [1.25, [[0, 0], [100, 100]]]} // Blue { "exp": [1.25, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [1.25, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/vscQnVLn9rfFIAbA638N) ```jsonc { "exp": [2, [[0, 0], [100, 100]]]} // Blue { "exp": [2, [[0, 0], [50, 50], [100, 100]]]} // Red { "exp": [2, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/Abr5NovEKu4LTlU6Qk6X) #### Cubic Bezier `{ "cubicbezier": [number, number, number, number, Stops[]] }`: Interpolates using the bezier curve defined by the curve control points. The following images shows the behaviour of this definition ```jsonc { "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [100, 100]]]} // Blue { "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [50, 50], [100, 100]]]} // Red { "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow ``` ![](/files/z63OrwvMBfSMIuMNS9G7) # Legends Adding a legend block to a visualization makes a legend entry appear for this visualization. Each legend entry is shown with the geometry type and color defined by the dataset and the visualization block. While simple visualizations will generate a single legend entry, categorical visualizations will generate a legend entry per category. ## The `legend` block The only field is `displayName`. For **categorical** visualizations it maps each category to its label; for **numeric**/**heatmap** visualizations it maps the index of each class (`"0"`, `"1"`, …) to its label. Set `"displayName": "auto"` to let Felt generate the labels for you — from the computed breaks for numeric classes, or from the category names for categorical visualizations (`"auto"` requires `steps` or `categories` to be set in `config`). An empty `legend: {}` still produces a legend entry using the dataset's geometry and color. For continuous (non-stepped) color-by and heatmap legends keyed by index, `"0"` labels the lowest value and the highest index labels the highest value. Continuous **size** legends are the historical exception: their indices run inverted, with `"0"` labeling the maximum, `"1"` the midpoint, and `"2"` the minimum. ## Simple legend The Biodiversity Hotspots layer in Felt has a simple visualization with a legend defined as follows: ```json "legend": {} ``` ![](/files/aoYHJNg6ujxDyCfF0pTK) ## Categorical legend The Plant Hardiness Zones layer in Felt has a categorical visualization with a legend defined as follows: ```json "legend": { "displayName": { "13": "13: 60 to 70 °F", "12": "12: 50 to 60 °F", "11": "11: 40 to 50 °F", "10": "10: 30 to 40 °F", "9": "9: 20 to 30 °F", "8": "8: 10 to 20 °F", "7": "7: 0 to 10 °F", "6": "6: -10 to 0 °F", "5": "5: -20 to -10 °F", "4": "4: -30 to -20 °F", "3": "3: -40 to -30 °F", "2": "2: -50 to -40 °F", "1": "1: -60 to -50 °F" } } ``` ![](/files/pyGjTKXtT36O8XRuZpbI) ## Numeric legends The visual display of numeric legends varies based on the style method (stepped or continuous) and the geometry type (point, line, polygon). The `displayName` can be modified in the `legend` block similar to simple and categorical style types. ### Stepped ```json "legend": { "displayName": { "0": "5.14 to 19.46", "1": "19.46 to 26.43", "2": "26.43 to 34.06", "3": "34.06 to 45.06", "4": "45.06 to 100" } } ``` ![](/files/3Splg2sWDtmD3FKHrExL) ### **Continuous** ```json "legend": { "displayName": { "0": "2.34M", "1": "714.65K", "2": "33K" } } ``` ![](/files/2rdUZlF0iyVKg9CvwdQP) ## Heatmap legends Heatmap legends are defined as follows: ```json "legend": { "displayName": { "0": "Low", "1": "High" } } ``` ![](/files/X3zL3cTbBtbXyHRTDwNC) Notice that the `displayName` mapping goes from `0` (left value) to `1` (right value) # Errors Style validation errors surface as a banner in the in-app style editor, and as `422` responses with the message in the error `detail` when styling [via the REST API](/rest-api/errors-and-rate-limits). The JS SDK rejects the `setLayerStyle` promise with the validation message. ### Unexpected value or type **Problem**: One of the values set in the style has an unsupported value or an invalid type. **Solution**: Change the value to be valid. **Error messages:** * Attribute `'displayName'` on a legend item of type simple must be a string. * Attribute `attribute_name` is not a number. * Attribute `attribute_name` is not a string. * Attribute `'lineCap'` is not a supported value. Supported values are butt, round, square. * Attribute `'lineJoin'` is not a supported value. Supported values are bevel, round, miter. * Visualization dashArray has to be an array with even length. * Attribute '`offset'` must be either an array of numbers or a number. * Attribute `'placement'` contains a not supported value. Supported values are `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`, `Center`. * Attribute `'placement'` contains a not supported value. Supported values are `Above`, `Center`, `Below`. * All values in `'labelAttribute'` must be a string. * Visualization `'type'` definition must be one of `simple`, `categorical`, `numeric`, `heatmap`, `hillshade`, `h3`. * Attribute `'showOther'` must be one of `above`, `below`. (Despite the wording, this message refers to the `otherOrder` field — `showOther` itself is a boolean, while `otherOrder` must be `"above"` or `"below"`.) ### Categorical visualization not working **Problem**: The style defines a categorical visualization, but the maps are not showing the layer **Error messages:** * Categories required. A `categories` array must be defined in the *config* block when defining a categorical visualization. Read more about categorical visualizations [here](/felt-style-language/types-of-visualizations/categorical-visualizations). * Not enough or too many `attribute_name` values. When defining a categorical visualization, all style and label properties must be an array with either a single value that will apply to all categories or an array with as many values as categories defined in the config block. Read more about categorical visualizations [here](/felt-style-language/types-of-visualizations/categorical-visualizations). # Examples A compact, one-per-type overview. For fuller, captioned examples — line casing, proportional symbols, icon-per-category, H3 aggregation popups, raster algebra — see the individual [Types of visualizations](/felt-style-language/types-of-visualizations) pages. ### Minimal ```json {"version": "2.3.1", "type": "simple", "config": {}, "paint": {}, "label": {}} ``` ### Point (simple) ```json { "version": "2.3.1", "type": "simple", "config": {"labelAttribute": ["name"]}, "paint": {"color": "#8F7EBF", "size": 4, "strokeColor": "auto", "strokeWidth": 1}, "label": {"color": "auto", "haloColor": "auto", "placement": ["E"], "offset": [6, 0]} } ``` ### Line (simple) ```json { "version": "2.3.1", "type": "simple", "config": {"labelAttribute": ["river_name"]}, "paint": {"color": "hsl(217, 80%, 40%)", "size": 2}, "label": {"color": "auto", "fontStyle": "italic", "placement": "Above", "repeatDistance": 200} } ``` ### Polygon (simple) ```json { "version": "2.3.1", "type": "simple", "config": {"labelAttribute": ["name"]}, "paint": {"color": "#3B82F6", "strokeColor": "auto", "strokeWidth": 1, "opacity": 0.8}, "label": {"color": "auto", "haloColor": "auto", "placement": ["Center"]} } ``` ### Categorical ```json { "version": "2.3.1", "type": "categorical", "config": { "categoricalAttribute": "primary_fuel", "categories": {"type": "top", "count": 6}, "showOther": true }, "paint": {"color": "@catPalette1", "size": 4, "strokeColor": "auto", "strokeWidth": 1}, "legend": {"displayName": "auto"} } ``` ### Numeric ```json { "version": "2.3.1", "type": "numeric", "config": {"numericAttribute": "Renter occupied (%)", "steps": {"type": "jenks", "count": 5}}, "paint": {"color": "@galaxy", "opacity": 0.9, "strokeColor": "auto", "strokeWidth": 0.5}, "legend": {"displayName": "auto"} } ``` ### Heatmap ```json { "version": "2.3.1", "type": "heatmap", "config": {}, "paint": {"color": "@purpYlPink", "size": 10, "intensity": 0.2, "opacity": 0.9}, "legend": {"displayName": {"0": "Low", "1": "High"}} } ``` ### H3 ```json { "version": "2.3.1", "type": "h3", "config": { "aggregation": "sum", "numericAttribute": "capacity_mw", "baseBinLevel": 3, "binMode": "fixed", "steps": {"type": "quantiles", "count": 5} }, "paint": {"color": "@riverine"}, "legend": {"displayName": "auto"} } ``` ### Raster ```json { "version": "2.3.1", "type": "numeric", "config": {"band": 1, "steps": {"type": "continuous"}, "noData": [-9999], "rasterResampling": "linear"}, "paint": {"color": "@mplVirdis", "opacity": 1}, "legend": {"displayName": "auto"} } ``` # API Reference To get started: ``` import { Felt } from "@feltmaps/js-sdk"; const felt = await Felt.embed( document.querySelector("#container"), "FELT_MAP_ID", { uiControls: { cooperativeGestures: false, fullScreenButton: false, showLegend: false, }, } ); const layers = await map.getLayers(); ``` **View** [**FeltController**](/js-sdk-api-reference/main/feltcontroller) **for a complete list of available functions.** [**FeltEmbedOptions**](/js-sdk-api-reference/main/feltembedoptions) **enumerates initialization options.** ## Documents * [CHANGELOG](/js-sdk-api-reference/changelog) ## Modules * [Basemaps](/js-sdk-api-reference/basemaps) * [Elements](/js-sdk-api-reference/elements) * [Interactions](/js-sdk-api-reference/interactions) * [Layers](/js-sdk-api-reference/layers) * [Main](/js-sdk-api-reference/main) * [Misc](/js-sdk-api-reference/misc) * [Selection](/js-sdk-api-reference/selection) * [Shared](/js-sdk-api-reference/shared) * [Tools](/js-sdk-api-reference/tools) * [UI](/js-sdk-api-reference/ui) * [Viewport](/js-sdk-api-reference/viewport) # @feltmaps/js-sdk ## 1.10.2 ### Patch Changes * b57ceb5: Make `RasterLayerSource.encodedTileTemplateUrl` nullable (`string | null`). TileService layers (WMS, WMTS, ArcGIS) serve pre-rendered image tiles and have no encoded tile URL. ## 1.10.1 ### Patch Changes * c3b650b: Update layer visible docs * 6c0d014: Fix `Felt.connect` intermittently failing in Safari with `DataCloneError` by creating a fresh `MessageChannel` for each handshake attempt instead of re-transferring the same port ## 1.10.0 ### Minor Changes * 03be185: Add basemaps API * 34b9ed3: Add feature actions * f7a1b4b: Add pageSize and select to getFeatures * 3d9527b: Add duplicateLayer method ### Patch Changes * 6e233c6: Fix feature action types and documentation ## 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 # Basemaps *** The Basemaps module allows you to control the map's basemap layer, such as getting the current basemap, listing available basemaps, changing the basemap, and being notified when the basemap changes. ## Controller * [BasemapsController](/js-sdk-api-reference/basemaps/basemapscontroller) ## Interfaces * [FeltBasemap](/js-sdk-api-reference/basemaps/feltbasemap) * [ColorBasemap](/js-sdk-api-reference/basemaps/colorbasemap) * [CustomTileBasemap](/js-sdk-api-reference/basemaps/customtilebasemap) ## Type Aliases * [ColorBasemapInput](/js-sdk-api-reference/basemaps/colorbasemapinput) * [CustomTileBasemapInput](/js-sdk-api-reference/basemaps/customtilebasemapinput) * [Basemap](/js-sdk-api-reference/basemaps/basemap) # Basemap *** > **Basemap**: [`FeltBasemap`](/js-sdk-api-reference/basemaps/feltbasemap) | [`ColorBasemap`](/js-sdk-api-reference/basemaps/colorbasemap) | [`CustomTileBasemap`](/js-sdk-api-reference/basemaps/customtilebasemap) # BasemapsController *** The basemaps controller allows you to manage the map's basemap layer. You can get the current basemap, list available basemaps, change the basemap, and be notified when the basemap changes. ## Extended by * [`FeltController`](/js-sdk-api-reference/main/feltcontroller) ## Methods ### getCurrentBasemap() > **getCurrentBasemap**(): `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)> Gets the currently active basemap. Use this method to retrieve information about the current basemap, including its type (Felt, color, or custom tile), name, color scheme, and attribution. #### Returns `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)> A promise that resolves to the current basemap configuration. #### Example ```typescript // Get current basemap const basemap = await felt.getCurrentBasemap(); console.log({ name: basemap.name, type: basemap.type, uiColorScheme: basemap.uiColorScheme, }); ``` *** ### getBasemaps() > **getBasemaps**(): `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)\[]> Gets all basemaps available on the map. Use this method to retrieve a list of all available basemaps that can be applied to the map. #### Returns `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)\[]> A promise that resolves to all basemaps available on the map. #### Example ```typescript // Get all available basemaps const basemaps = await felt.getBasemaps(); const lightBasemaps = basemaps.filter(b => b.uiColorScheme === "light"); ``` *** ### chooseBasemap() > **chooseBasemap**(`id`: `string`): `void` Chooses the basemap to use for the map. Use this method to change the current basemap. The basemap ID can be obtained from getBasemaps(). #### Parameters | Parameter | Type | | --------- | -------- | | `id` | `string` | #### Returns `void` A promise that resolves when the basemap has been set. #### Example ```typescript // Switch to a specific basemap const basemaps = await felt.getBasemaps(); const darkBasemap = basemaps.find(b => b.uiColorScheme === "dark"); if (darkBasemap) { await felt.chooseBasemap(darkBasemap.id); } ``` *** ### addCustomBasemap() > **addCustomBasemap**(`args`: { `basemap`: [`ColorBasemapInput`](/js-sdk-api-reference/basemaps/colorbasemapinput) | [`CustomTileBasemapInput`](/js-sdk-api-reference/basemaps/customtilebasemapinput); `select`: `boolean`; }): `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)> Adds a custom basemap to the map. This can be either a solid color or a basemap from a custom tile URL. #### Parameters | Parameter | Type | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `args` | { `basemap`: [`ColorBasemapInput`](/js-sdk-api-reference/basemaps/colorbasemapinput) \| [`CustomTileBasemapInput`](/js-sdk-api-reference/basemaps/customtilebasemapinput); `select`: `boolean`; } | - | | `args.basemap` | [`ColorBasemapInput`](/js-sdk-api-reference/basemaps/colorbasemapinput) \| [`CustomTileBasemapInput`](/js-sdk-api-reference/basemaps/customtilebasemapinput) | The basemap to add. | | `args.select`? | `boolean` | Whether to select the basemap after adding it. | #### Returns `Promise`<[`Basemap`](/js-sdk-api-reference/basemaps/basemap)> A promise for the added basemap. #### Example ```typescript // Add a custom basemap and select it await felt.addCustomBasemap({ basemap: { type: "xyz_tile", tileUrl: "https://example.com/tile.png" }, select: true, }); ``` *** ### removeBasemap() > **removeBasemap**(`id`: `string`): `Promise`<`void`> Removes a basemap from the list of available basemaps. #### Parameters | Parameter | Type | | --------- | -------- | | `id` | `string` | #### Returns `Promise`<`void`> A promise that resolves when the basemap has been removed. ## Events ### onBasemapChange() > **onBasemapChange**(`args`: { `handler`: (`basemap`: [`Basemap`](/js-sdk-api-reference/basemaps/basemap)) => `void`; }): `VoidFunction` Adds a listener for when the basemap changes. Use this to react to basemap changes, such as updating your UI or adjusting other map elements to match the new basemap's color scheme. #### Parameters | Parameter | Type | | -------------- | ------------------------------------------------------------------------------------------ | | `args` | { `handler`: (`basemap`: [`Basemap`](/js-sdk-api-reference/basemaps/basemap)) => `void`; } | | `args.handler` | (`basemap`: [`Basemap`](/js-sdk-api-reference/basemaps/basemap)) => `void` | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript // Listen for basemap changes const unsubscribe = felt.onBasemapChange({ handler: basemap => { console.log(`Switched to ${basemap.name}`); updateUIColors(basemap.uiColorScheme); }, }); // later on... unsubscribe(); ``` # ColorBasemap *** ## Properties ### id > **id**: `string` A unique identifier for the basemap. #### Remarks Do not rely on the stability of this ID for Felt basemaps, as they are subject to change. *** ### name > **name**: `string` The name of the basemap. *** ### uiColorScheme > **uiColorScheme**: `"light"` | `"dark"` The color scheme of the UI that goes with the basemap. It is best to set this to "light" if your basemap is broadly light, and "dark" if your basemap is broadly dark. *** ### type > **type**: `"color"` *** ### color > **color**: `string` *** ### attribution? > `optional` **attribution**: `string` The attribution of the basemap, which is shown in the map's UI. # ColorBasemapInput *** > **ColorBasemapInput**: `Omit`<[`ColorBasemap`](/js-sdk-api-reference/basemaps/colorbasemap), `"id"`> # CustomTileBasemap *** ## Properties ### id > **id**: `string` A unique identifier for the basemap. #### Remarks Do not rely on the stability of this ID for Felt basemaps, as they are subject to change. *** ### name > **name**: `string` The name of the basemap. *** ### uiColorScheme > **uiColorScheme**: `"light"` | `"dark"` The color scheme of the UI that goes with the basemap. It is best to set this to "light" if your basemap is broadly light, and "dark" if your basemap is broadly dark. *** ### type > **type**: `"xyz_tile"` *** ### tileUrl > **tileUrl**: `string` *** ### attribution? > `optional` **attribution**: `string` The attribution of the basemap, which is shown in the map's UI. # CustomTileBasemapInput *** > **CustomTileBasemapInput**: `Omit`<[`CustomTileBasemap`](/js-sdk-api-reference/basemaps/customtilebasemap), `"id"`> # FeltBasemap *** ## Properties ### id > **id**: `string` A unique identifier for the basemap. #### Remarks Do not rely on the stability of this ID for Felt basemaps, as they are subject to change. *** ### name > **name**: `string` The name of the basemap. *** ### uiColorScheme > **uiColorScheme**: `"light"` | `"dark"` The color scheme of the UI that goes with the basemap. It is best to set this to "light" if your basemap is broadly light, and "dark" if your basemap is broadly dark. *** ### type > **type**: `"felt"` *** ### theme > **theme**: `"color_light"` | `"monochrome_dark"` | `"monochrome_light"` | `"satellite"` *** ### attribution? > `optional` **attribution**: `string` The attribution of the basemap, which is shown in the map's UI. # Elements *** 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 [ToolsController](/js-sdk-api-reference/tools/toolscontroller) to\ > select and configure the drawing tools in Felt. ## Controller * [ElementsController](/js-sdk-api-reference/elements/elementscontroller) ## Interfaces * [PlaceElementCreate](/js-sdk-api-reference/elements/placeelementcreate) * [PathElementCreate](/js-sdk-api-reference/elements/pathelementcreate) * [PolygonElementCreate](/js-sdk-api-reference/elements/polygonelementcreate) * [CircleElementCreate](/js-sdk-api-reference/elements/circleelementcreate) * [MarkerElementCreate](/js-sdk-api-reference/elements/markerelementcreate) * [HighlighterElementCreate](/js-sdk-api-reference/elements/highlighterelementcreate) * [TextElementCreate](/js-sdk-api-reference/elements/textelementcreate) * [NoteElementCreate](/js-sdk-api-reference/elements/noteelementcreate) * [ImageElementCreate](/js-sdk-api-reference/elements/imageelementcreate) * [PlaceElementRead](/js-sdk-api-reference/elements/placeelementread) * [PathElementRead](/js-sdk-api-reference/elements/pathelementread) * [PolygonElementRead](/js-sdk-api-reference/elements/polygonelementread) * [CircleElementRead](/js-sdk-api-reference/elements/circleelementread) * [MarkerElementRead](/js-sdk-api-reference/elements/markerelementread) * [HighlighterElementRead](/js-sdk-api-reference/elements/highlighterelementread) * [TextElementRead](/js-sdk-api-reference/elements/textelementread) * [NoteElementRead](/js-sdk-api-reference/elements/noteelementread) * [ImageElementRead](/js-sdk-api-reference/elements/imageelementread) * [LinkElementRead](/js-sdk-api-reference/elements/linkelementread) * [PlaceElementUpdate](/js-sdk-api-reference/elements/placeelementupdate) * [PathElementUpdate](/js-sdk-api-reference/elements/pathelementupdate) * [PolygonElementUpdate](/js-sdk-api-reference/elements/polygonelementupdate) * [CircleElementUpdate](/js-sdk-api-reference/elements/circleelementupdate) * [MarkerElementUpdate](/js-sdk-api-reference/elements/markerelementupdate) * [HighlighterElementUpdate](/js-sdk-api-reference/elements/highlighterelementupdate) * [TextElementUpdate](/js-sdk-api-reference/elements/textelementupdate) * [NoteElementUpdate](/js-sdk-api-reference/elements/noteelementupdate) * [ImageElementUpdate](/js-sdk-api-reference/elements/imageelementupdate) ## Type Aliases * [ElementCreate](/js-sdk-api-reference/elements/elementcreate) * [ElementUpdate](/js-sdk-api-reference/elements/elementupdate) ## Element Groups * [ElementGroup](/js-sdk-api-reference/elements/elementgroup) * [GetElementGroupsConstraint](/js-sdk-api-reference/elements/getelementgroupsconstraint) * [ElementGroupChangeCallbackParams](/js-sdk-api-reference/elements/elementgroupchangecallbackparams) ## Elements * [GetElementsConstraint](/js-sdk-api-reference/elements/getelementsconstraint) * [ElementChangeCallbackParams](/js-sdk-api-reference/elements/elementchangecallbackparams) * [Element](/js-sdk-api-reference/elements/element) # CircleElementCreate *** ## Properties ### type > **type**: `"Circle"` *** ### radius > **radius**: `number` The radius of the circle in meters. *** ### center > **center**: [`LngLatTuple`](/js-sdk-api-reference/shared/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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "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 ```ts 1 ``` *** ### strokeWidth? > `optional` **strokeWidth**: `number` The width of the element's stroke in pixels. #### Default ```ts 2 ``` *** ### strokeStyle? > `optional` **strokeStyle**: `"solid"` | `"dashed"` | `"dotted"` The style of the element's stroke. #### Default ```ts "solid" ``` *** ### radiusMarker? > `optional` **radiusMarker**: `boolean` Whether to show a marker on the circle that indicates the radius #### Default ```ts 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 ```ts 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 ```ts null ``` *** ### fillOpacity? > `optional` **fillOpacity**: `number` The opacity of the circle's fill. #### Default ```ts 0.25 ``` # CircleElementRead *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### groupId > **groupId**: `null` | `string` The ID of the element group that the element belongs to.\ For elements that are not part of a group, this will be null. *** ### color > **color**: `string` The color of the element in some CSS-like format. #### Example ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts 1 ``` *** ### strokeWidth > **strokeWidth**: `number` The width of the element's stroke in pixels. #### Default ```ts 2 ``` *** ### strokeStyle > **strokeStyle**: `"solid"` | `"dashed"` | `"dotted"` The style of the element's stroke. #### Default ```ts "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 ```ts 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 ```ts 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 ```ts null ``` *** ### fillOpacity > **fillOpacity**: `number` The opacity of the circle's fill. #### Default ```ts 0.25 ``` *** ### center > **center**: [`LngLatTuple`](/js-sdk-api-reference/shared/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 ```ts "default" ``` # CircleElementUpdate *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### type > **type**: `"Circle"` *** ### groupId? > `optional` **groupId**: `null` | `string` The ID of the element group that the element belongs to.\ For elements that are not part of a group, this will be null. *** ### color? > `optional` **color**: `string` The color of the element in some CSS-like format. #### Example ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "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 ```ts 1 ``` *** ### strokeWidth? > `optional` **strokeWidth**: `number` The width of the element's stroke in pixels. #### Default ```ts 2 ``` *** ### strokeStyle? > `optional` **strokeStyle**: `"solid"` | `"dashed"` | `"dotted"` The style of the element's stroke. #### Default ```ts "solid" ``` *** ### radius? > `optional` **radius**: `number` The radius of the circle in meters. *** ### radiusMarker? > `optional` **radiusMarker**: `boolean` Whether to show a marker on the circle that indicates the radius #### Default ```ts 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 ```ts 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 ```ts null ``` *** ### fillOpacity? > `optional` **fillOpacity**: `number` The opacity of the circle's fill. #### Default ```ts 0.25 ``` *** ### center? > `optional` **center**: [`LngLatTuple`](/js-sdk-api-reference/shared/lnglattuple) The center of the circle. # Element *** > **Element**: [`PlaceElementRead`](/js-sdk-api-reference/elements/placeelementread) | [`PathElementRead`](/js-sdk-api-reference/elements/pathelementread) | [`PolygonElementRead`](/js-sdk-api-reference/elements/polygonelementread) | [`CircleElementRead`](/js-sdk-api-reference/elements/circleelementread) | [`MarkerElementRead`](/js-sdk-api-reference/elements/markerelementread) | [`HighlighterElementRead`](/js-sdk-api-reference/elements/highlighterelementread) | [`TextElementRead`](/js-sdk-api-reference/elements/textelementread) | [`NoteElementRead`](/js-sdk-api-reference/elements/noteelementread) | [`ImageElementRead`](/js-sdk-api-reference/elements/imageelementread) | [`LinkElementRead`](/js-sdk-api-reference/elements/linkelementread) # ElementChangeCallbackParams *** The parameters for the [\`onElementChange\`](/js-sdk-api-reference/elements/elementscontroller#onelementchange) and the [\`onElementCreate\`](/js-sdk-api-reference/elements/elementscontroller#onelementcreate) listeners. ## Properties ### element > **element**: `null` | [`Element`](/js-sdk-api-reference/elements/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. # ElementCreate *** > **ElementCreate**: [`PlaceElementCreate`](/js-sdk-api-reference/elements/placeelementcreate) | [`PathElementCreate`](/js-sdk-api-reference/elements/pathelementcreate) | [`PolygonElementCreate`](/js-sdk-api-reference/elements/polygonelementcreate) | [`CircleElementCreate`](/js-sdk-api-reference/elements/circleelementcreate) | [`MarkerElementCreate`](/js-sdk-api-reference/elements/markerelementcreate) | [`HighlighterElementCreate`](/js-sdk-api-reference/elements/highlighterelementcreate) | [`ImageElementCreate`](/js-sdk-api-reference/elements/imageelementcreate) | [`TextElementCreate`](/js-sdk-api-reference/elements/textelementcreate) | [`NoteElementCreate`](/js-sdk-api-reference/elements/noteelementcreate) # ElementGroup *** ## Properties ### id > **id**: `string` A string identifying the element group. *** ### name > **name**: `string` The name of the element group. This is shown in the legend. *** ### caption > **caption**: `null` | `string` The caption of the element group. This is shown in the legend. *** ### elementIds > **elementIds**: `string`\[] The ids of the elements in the element group. #### Remarks You can use these ids to get the full element objects via the [\`getElements\`](/js-sdk-api-reference/elements/elementscontroller#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. # ElementGroupChangeCallbackParams *** The parameters for the [\`onElementGroupChange\`](/js-sdk-api-reference/elements/elementscontroller#onelementgroupchange) listener. ## Properties ### elementGroup > **elementGroup**: `null` | [`ElementGroup`](/js-sdk-api-reference/elements/elementgroup) # ElementUpdate *** > **ElementUpdate**: [`PlaceElementUpdate`](/js-sdk-api-reference/elements/placeelementupdate) | [`PathElementUpdate`](/js-sdk-api-reference/elements/pathelementupdate) | [`PolygonElementUpdate`](/js-sdk-api-reference/elements/polygonelementupdate) | [`CircleElementUpdate`](/js-sdk-api-reference/elements/circleelementupdate) | [`MarkerElementUpdate`](/js-sdk-api-reference/elements/markerelementupdate) | [`HighlighterElementUpdate`](/js-sdk-api-reference/elements/highlighterelementupdate) | [`TextElementUpdate`](/js-sdk-api-reference/elements/textelementupdate) | [`NoteElementUpdate`](/js-sdk-api-reference/elements/noteelementupdate) | [`ImageElementUpdate`](/js-sdk-api-reference/elements/imageelementupdate) # ElementsController *** The Elements controller allows you to get information about the elements on the map, and make changes to their visibility. ## Extended by * [`FeltController`](/js-sdk-api-reference/main/feltcontroller) ## Methods ### getElement() > **getElement**(`id`: `string`): `Promise`<`null` | [`Element`](/js-sdk-api-reference/elements/element)> Get a single element from the map by its id. Use this method when you know the specific ID of an element and want to retrieve its current state. This is more efficient than getting all elements and filtering. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------------- | | `id` | `string` | The id of the element you want to get. | #### Returns `Promise`<`null` | [`Element`](/js-sdk-api-reference/elements/element)> A promise that resolves to the requested element, or `null` if not found. #### Example ```typescript const element = await felt.getElement("element-1"); ``` *** ### getElementGeometry() > **getElementGeometry**(`id`: `string`): `Promise`<`null` | [`GeoJsonGeometry`](/js-sdk-api-reference/shared/geojsongeometry)> Get the geometry of an element in GeoJSON geometry format. For most element types, the geometry returned is based on the `coordinates` property of the element, with some differences: * For Circle elements, the geometry is a Polygon drawn from the `center` and `radius` properties. * Path elements become MultiLineString geometries. * Marker elements return a MultiLineString of the path traced by the user as they drew the marker. Note that this is not the polygon formed by filled-in "pen" stroke, which doesn't exactly follow the path traced by the user as it is smoothed and interpolated to create a continuous line. * Text, Note and Image elements do not return geometry, so will return `null`. Use this method when you need the geometric representation of an element for spatial analysis or visualization purposes. #### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------------ | | `id` | `string` | The id of the element you want to get the geometry of. | #### Returns `Promise`<`null` | [`GeoJsonGeometry`](/js-sdk-api-reference/shared/geojsongeometry)> A promise that resolves to the element's geometry in GeoJSON format, or `null` if the element has no geometry. #### Example ```typescript const geometry = await felt.getElementGeometry("element-1"); console.log(geometry?.type, geometry?.coordinates); ``` *** ### getElements() > **getElements**(`constraint`?: [`GetElementsConstraint`](/js-sdk-api-reference/elements/getelementsconstraint)): `Promise`<(`null` | [`Element`](/js-sdk-api-reference/elements/element))\[]> Gets elements from the map, according to the constraints supplied. If no constraints are supplied, all elements will be returned. Use this method to retrieve multiple elements, optionally filtered by constraints. This is useful for bulk operations or when you need to analyze all elements on the map. #### Parameters | Parameter | Type | Description | | ------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `constraint`? | [`GetElementsConstraint`](/js-sdk-api-reference/elements/getelementsconstraint) | Optional constraints to apply to the elements returned from the map. | #### Returns `Promise`<(`null` | [`Element`](/js-sdk-api-reference/elements/element))\[]> A promise that resolves to an array of elements, ordered by the order specified in Felt. #### Remarks The elements in the map, ordered by the order specified in Felt. This is not necessarily the order that they are drawn in, as Felt draws points above lines and lines above polygons, for instance. #### Example ```typescript const elements = await felt.getElements(); ``` *** ### getElementGroup() > **getElementGroup**(`id`: `string`): `Promise`<`null` | [`ElementGroup`](/js-sdk-api-reference/elements/elementgroup)> Get an element group from the map by its id. Element groups allow you to organize related elements together and control their visibility as a unit. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------------------- | | `id` | `string` | The id of the element group you want to get. | #### Returns `Promise`<`null` | [`ElementGroup`](/js-sdk-api-reference/elements/elementgroup)> A promise that resolves to the requested element group, or `null` if not found. #### Example ```typescript const elementGroup = await felt.getElementGroup("element-group-1"); ``` *** ### getElementGroups() > **getElementGroups**(`constraint`?: [`GetElementGroupsConstraint`](/js-sdk-api-reference/elements/getelementgroupsconstraint)): `Promise`<(`null` | [`ElementGroup`](/js-sdk-api-reference/elements/elementgroup))\[]> Gets element groups from the map, according to the filters supplied. If no constraints are supplied, all element groups will be returned in rendering order. Use this method to retrieve multiple element groups, optionally filtered by constraints. This is useful for bulk operations on element groups. #### Parameters | Parameter | Type | Description | | ------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `constraint`? | [`GetElementGroupsConstraint`](/js-sdk-api-reference/elements/getelementgroupsconstraint) | Optional constraints to apply to the element groups returned from the map. | #### Returns `Promise`<(`null` | [`ElementGroup`](/js-sdk-api-reference/elements/elementgroup))\[]> A promise that resolves to an array of element groups in rendering order. #### Example ```typescript const elementGroups = await felt.getElementGroups({ ids: ["element-group-1", "element-group-2"] }); ``` *** ### setElementGroupVisibility() > **setElementGroupVisibility**(`visibility`: [`SetVisibilityRequest`](/js-sdk-api-reference/shared/setvisibilityrequest)): `Promise`<`void`> Hide or show element groups with the given ids. Use this method to control the visibility of multiple element groups at once. This is more efficient than hiding/showing individual elements. #### Parameters | Parameter | Type | Description | | ------------ | --------------------------------------------------------------------------- | ------------------------------------------------ | | `visibility` | [`SetVisibilityRequest`](/js-sdk-api-reference/shared/setvisibilityrequest) | The visibility configuration for element groups. | #### Returns `Promise`<`void`> A promise that resolves when the visibility changes are applied. #### Example ```typescript felt.setElementGroupVisibility({ show: ["element-group-1", "element-group-2"], hide: ["element-group-3"] }); ``` *** ### createElement() > **createElement**(`element`: [`ElementCreate`](/js-sdk-api-reference/elements/elementcreate)): `Promise`<[`Element`](/js-sdk-api-reference/elements/element)> Create a new element on the map. Use this method to programmatically create elements on the map. Elements created via the SDK are only available to the current session and are not persisted. #### Parameters | Parameter | Type | Description | | --------- | --------------------------------------------------------------- | ------------------------------------ | | `element` | [`ElementCreate`](/js-sdk-api-reference/elements/elementcreate) | The element configuration to create. | #### Returns `Promise`<[`Element`](/js-sdk-api-reference/elements/element)> A promise that resolves to the created element. #### Example ```typescript const element = await felt.createElement({ type: "Place", coordinates: [10, 10] }); ``` *** ### updateElement() > **updateElement**(`element`: [`ElementUpdate`](/js-sdk-api-reference/elements/elementupdate)): `Promise`<[`Element`](/js-sdk-api-reference/elements/element)> Update an element on the map. The element type must be specified. Use this method to modify existing elements. You can update properties like coordinates, styling, and metadata. #### Parameters | Parameter | Type | Description | | --------- | --------------------------------------------------------------- | --------------------------------- | | `element` | [`ElementUpdate`](/js-sdk-api-reference/elements/elementupdate) | The element update configuration. | #### Returns `Promise`<[`Element`](/js-sdk-api-reference/elements/element)> A promise that resolves to the updated element. #### Example ```typescript // Update a place element's coordinates await felt.updateElement({ id: "element-1", type: "Place", coordinates: [10, 20] }); // Update a polygon's style await felt.updateElement({ id: "element-2", type: "Polygon", color: "#ABC123", fillOpacity: 0.5 }); ``` *** ### deleteElement() > **deleteElement**(`id`: `string`): `Promise`<`void`> Delete an element from the map. Use this method to remove elements from the map. This operation cannot be undone. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------- | | `id` | `string` | The id of the element to delete. | #### Returns `Promise`<`void`> A promise that resolves when the element is deleted. #### Example ```typescript await felt.deleteElement("element-1"); ``` ## Events ### onElementCreate() > **onElementCreate**(`args`: { `handler`: (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void`; }): `VoidFunction` Adds a listener for when an element is created. This will fire when elements are created programmatically, or when the user starts creating an element with a drawing tool. When the user creates an element with a drawing tool, it can begin in an invalid state, such as if you've just placed a single point in a polygon. You can use the `isBeingCreated` property to determine if the element is still being created by a drawing tool. If you want to know when the element is finished being created, you can use the [\`onElementCreateEnd\`](#onelementcreateend) listener. #### Parameters | Parameter | Type | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `handler`: (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void`; } | - | | `args.handler` | (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void` | The handler that is called when an element is created. This will fire when elements are created programmatically, or when the user starts creating an element with a drawing tool. When the user creates an element with a drawing tool, it can begin in an invalid state, such as if you've just placed a single point in a polygon. You can use the `isBeingCreated` property to determine if the element is still being created by a drawing tool. If you want to know when the element is finished being created, you can use the [\`onElementCreateEnd\`](#onelementcreateend) listener. | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript const unsubscribe = felt.onElementCreate({ handler: ({isBeingCreated, element}) => console.log(element.id), }); // later on... unsubscribe(); ``` *** ### onElementCreateEnd() > **onElementCreateEnd**(`args`: { `handler`: (`params`: { `element`: [`Element`](/js-sdk-api-reference/elements/element); }) => `void`; }): `VoidFunction` Listens for when a new element is finished being created by a drawing tool. This differs from the [\`onElementCreate\`](#onelementcreate) listener, which fires whenever an element is first created. This fires when the user finishes creating an element which could be after a series of interactions. For example, when creating a polygon, the user places a series of points then finishes by pressing Enter or Escape. Or when creating a Place element, they add the marker, type a label, then finally deselect the element. #### Parameters | Parameter | Type | Description | | -------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `args` | { `handler`: (`params`: { `element`: [`Element`](/js-sdk-api-reference/elements/element); }) => `void`; } | - | | `args.handler` | (`params`: { `element`: [`Element`](/js-sdk-api-reference/elements/element); }) => `void` | The handler to call whenever this event fires. | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript const unsubscribe = felt.onElementCreateEnd({ handler: (params) => console.log(params), }); // later on... unsubscribe(); ``` *** ### onElementChange() > **onElementChange**(`args`: { `options`: { `id`: `string`; }; `handler`: (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void`; }): `VoidFunction` Adds a listener for when an element changes. This will fire when an element is being edited, either on the map by the user or programmatically. Like the [\`onElementCreate\`](#onelementcreate) listener, this will fire when an element is still being created by a drawing tool. You can check the [\`isBeingCreated\`](/js-sdk-api-reference/elements/elementchangecallbackparams#isbeingcreated) property to determine if the element is still being created by a drawing tool. #### Parameters | Parameter | Type | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `args` | { `options`: { `id`: `string`; }; `handler`: (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void`; } | - | | `args.options` | { `id`: `string`; } | - | | `args.options.id` | `string` | The id of the element to listen for changes to. | | `args.handler` | (`change`: [`ElementChangeCallbackParams`](/js-sdk-api-reference/elements/elementchangecallbackparams)) => `void` | The handler that is called when the element changes. | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript const unsubscribe = felt.onElementChange({ options: { id: "element-1" }, handler: ({element}) => console.log(element.id), }); // later on... unsubscribe(); ``` *** ### onElementDelete() > **onElementDelete**(`args`: { `options`: { `id`: `string`; }; `handler`: () => `void`; }): `VoidFunction` Adds a listener for when an element is deleted. Use this to react to element deletions, such as cleaning up related data or updating your application state. #### Parameters | Parameter | Type | Description | | ----------------- | ------------------------------------------------------------ | ------------------------------------------------------- | | `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. | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript const unsubscribe = felt.onElementDelete({ options: { id: "element-1" }, handler: () => console.log("element-1 deleted"), }); // later on... unsubscribe(); ``` *** ### onElementGroupChange() > **onElementGroupChange**(`args`: { `options`: { `id`: `string`; }; `handler`: (`change`: [`ElementGroupChangeCallbackParams`](/js-sdk-api-reference/elements/elementgroupchangecallbackparams)) => `void`; }): `VoidFunction` Adds a listener for when an element group changes. Use this to react to changes in element groups, such as when elements are added to or removed from groups. #### Parameters | Parameter | Type | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `options`: { `id`: `string`; }; `handler`: (`change`: [`ElementGroupChangeCallbackParams`](/js-sdk-api-reference/elements/elementgroupchangecallbackparams)) => `void`; } | | `args.options` | { `id`: `string`; } | | `args.options.id` | `string` | | `args.handler` | (`change`: [`ElementGroupChangeCallbackParams`](/js-sdk-api-reference/elements/elementgroupchangecallbackparams)) => `void` | #### Returns `VoidFunction` A function to unsubscribe from the listener. #### Example ```typescript const unsubscribe = felt.onElementGroupChange({ options: { id: "element-group-1" }, handler: elementGroup => console.log(elementGroup.id), }); // later on... unsubscribe(); ``` # GetElementGroupsConstraint *** The constraints to apply when getting element groups. ## Properties ### ids? > `optional` **ids**: `string`\[] The ids of the element groups to get. # GetElementsConstraint *** The constraints to apply when getting elements. ## Properties ### ids? > `optional` **ids**: `string`\[] The ids of the elements to get. # HighlighterElementCreate *** ## Properties ### type > **type**: `"Highlighter"` *** ### coordinates > **coordinates**: [`LngLatTuple`](/js-sdk-api-reference/shared/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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "default" ``` *** ### renderHoles? > `optional` **renderHoles**: `boolean` Whether to render the holes of the highlighted area. #### Default ```ts false ``` *** ### opacity? > `optional` **opacity**: `number` The opacity of the highlighter, between 0 and 1. #### Default ```ts 0.5 ``` # HighlighterElementRead *** ## 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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**: `"Highlighter"` *** ### renderHoles > **renderHoles**: `boolean` Whether to render the holes of the highlighted area. #### Default ```ts false ``` *** ### opacity > **opacity**: `number` The opacity of the highlighter, between 0 and 1. #### Default ```ts 0.5 ``` *** ### 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 ```ts "default" ``` # HighlighterElementUpdate *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### type > **type**: `"Highlighter"` *** ### 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "default" ``` *** ### renderHoles? > `optional` **renderHoles**: `boolean` Whether to render the holes of the highlighted area. #### Default ```ts false ``` *** ### opacity? > `optional` **opacity**: `number` The opacity of the highlighter, between 0 and 1. #### Default ```ts 0.5 ``` *** ### coordinates? > `optional` **coordinates**: [`LngLatTuple`](/js-sdk-api-reference/shared/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. # ImageElementCreate *** ## 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 ```ts "default" ``` *** ### opacity? > `optional` **opacity**: `number` The opacity of the image, between 0 and 1. #### Default ```ts 1 ``` # ImageElementRead *** ## 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 ```ts 1 ``` *** ### 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 ```ts "default" ``` # ImageElementUpdate *** ## 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 ```ts "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 ```ts 1 ``` # LinkElementRead *** ## 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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**: `"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 ```ts "default" ``` # MarkerElementCreate *** ## Properties ### type > **type**: `"Marker"` *** ### coordinates > **coordinates**: [`LngLatTuple`](/js-sdk-api-reference/shared/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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "default" ``` *** ### opacity? > `optional` **opacity**: `number` The opacity of the marker, between 0 and 1. #### Default ```ts 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 ```ts 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`. # MarkerElementRead *** ## 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts 1 ``` *** ### size > **size**: `number` The size of the marker, used in conjunction with the `zoom` to determine\ the actual size of the marker. #### Default ```ts 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 ```ts "default" ``` # MarkerElementUpdate *** ## 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "default" ``` *** ### opacity? > `optional` **opacity**: `number` The opacity of the marker, between 0 and 1. #### Default ```ts 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 ```ts 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`. *** ### coordinates? > `optional` **coordinates**: [`LngLatTuple`](/js-sdk-api-reference/shared/lnglattuple)\[]\[] # NoteElementCreate *** ## Properties ### type > **type**: `"Note"` *** ### 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#C93535" ``` *** ### 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 ```ts "default" ``` *** ### rotation? > `optional` **rotation**: `number` The rotation of the element in degrees. #### Default ```ts 0 ``` *** ### 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 ```ts 1 ``` *** ### 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 ```ts "center" ``` *** ### style? > `optional` **style**: `"light"` | `"italic"` | `"regular"` | `"caps"` The style of the text, either `italic`, `light`, `regular` or `caps`. #### Default ```ts "regular" ``` *** ### widthScale? > `optional` **widthScale**: `number` *** ### position? > `optional` **position**: [`LngLatTuple`](/js-sdk-api-reference/shared/lnglattuple) The geographical position of the center of the note element. If this is omitted, the note will be placed at the center of the current viewport. # NoteElementRead *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### groupId > **groupId**: `null` | `string` The ID of the element group that the element belongs to. For elements that are not part of a group, this will be null. *** ### color > **color**: `string` The color of the element in some CSS-like format. #### Example ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#C93535" ``` *** ### description > **description**: `null` | `string` Text describing the element, which is shown in an element's popup when it is selected. Note that some elements are not selectable on the map, such as Notes, Text and Markers, so their description will not be shown. *** ### attributes > **attributes**: `Record`<`string`, `unknown`> A set of key-value pairs that can be used to store arbitrary data about the element. This is most useful for associating additional data with an element that is not part of the element's core data, such as a Place's address or some other data. *** ### rotation > **rotation**: `number` The rotation of the element in degrees. #### Default ```ts 0 ``` *** ### scale > **scale**: `number` The relative scale of the element from the default size. This is combined with the `zoom` to determine the actual size of the element. #### Default ```ts 1 ``` *** ### zoom > **zoom**: `number` The zoom level at which the element was created. This is combined with the `scale` to determine the actual size of the element. When creating an element, if you don't supply this value it defaults to the current zoom of the map when you call `createElement`. *** ### text > **text**: `string` The text in the element. *** ### align > **align**: `"center"` | `"left"` | `"right"` The alignment of the text, either `left`, `center` or `right`. #### Default ```ts "center" ``` *** ### style > **style**: `"light"` | `"italic"` | `"regular"` | `"caps"` The style of the text, either `italic`, `light`, `regular` or `caps`. #### Default ```ts "regular" ``` *** ### name > **name**: `string` The text shown in the element, which is identical to the `text` property. #### Remarks This is added for consistency with other elements that have a `name` property. *** ### type > **type**: `"Note"` *** ### widthScale > **widthScale**: `number` *** ### position > **position**: [`LngLatTuple`](/js-sdk-api-reference/shared/lnglattuple) The geographical position of the center of the note element. *** ### interaction? > `optional` **interaction**: `"default"` | `"locked"` Whether the element is interactive. The `default` interaction mode means that the element can be selected and edited by the user, if it was created by the SDK or by the user using a tool. If the interaction mode is `locked`, the element will not be editable by the user, which is often used for elements that you don't want the user to edit or move by accident. Elements that were created by the map author (i.e. not during an SDK "session") are not editable and have special behaviour depending on their name, description and attributes. #### Default ```ts "default" ``` # NoteElementUpdate *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### type > **type**: `"Note"` *** ### 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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#C93535" ``` *** ### 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 ```ts "default" ``` *** ### rotation? > `optional` **rotation**: `number` The rotation of the element in degrees. #### Default ```ts 0 ``` *** ### 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 ```ts 1 ``` *** ### zoom? > `optional` **zoom**: `number` The zoom level at which the element was created. This is combined with the `scale` to determine the actual size of the element. When creating an element, if you don't supply this value it defaults to the current zoom of the map when you call `createElement`. *** ### text? > `optional` **text**: `string` The text in the element. *** ### align? > `optional` **align**: `"center"` | `"left"` | `"right"` The alignment of the text, either `left`, `center` or `right`. #### Default ```ts "center" ``` *** ### style? > `optional` **style**: `"light"` | `"italic"` | `"regular"` | `"caps"` The style of the text, either `italic`, `light`, `regular` or `caps`. #### Default ```ts "regular" ``` *** ### widthScale? > `optional` **widthScale**: `number` *** ### position? > `optional` **position**: [`LngLatTuple`](/js-sdk-api-reference/shared/lnglattuple) The geographical position of the center of the note element. # PathElementCreate *** ## Properties ### type > **type**: `"Path"` *** ### coordinates > **coordinates**: [`LngLatTuple`](/js-sdk-api-reference/shared/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 ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts "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 ```ts 1 ``` *** ### strokeWidth? > `optional` **strokeWidth**: `number` The width of the element's stroke in pixels. #### Default ```ts 2 ``` *** ### strokeStyle? > `optional` **strokeStyle**: `"solid"` | `"dashed"` | `"dotted"` The style of the element's stroke. #### Default ```ts "solid" ``` *** ### distanceMarker? > `optional` **distanceMarker**: `boolean` Whether a distance marker is shown at the midpoint of the path. #### Default ```ts false ``` *** ### routingMode? > `optional` **routingMode**: `null` | `"driving"` | `"cycling"` | `"walking"` | `"flying"` Whether this represents a route, and if so, what mode of transport\ is used. If this is `null`, the path is not considered to be a route, so while it\ can have a `distanceMarker`, it will does not have a start or end cap. #### Default ```ts null ``` *** ### endCaps? > `optional` **endCaps**: `boolean` Whether or not to show Start and End caps on the path. This is\ only available if the `routingMode` is set. #### Default ```ts false ``` # PathElementRead *** ## Properties ### id > **id**: `string` The unique identifier for the element. *** ### groupId > **groupId**: `null` | `string` The ID of the element group that the element belongs to.\ For elements that are not part of a group, this will be null. *** ### color > **color**: `string` The color of the element in some CSS-like format. #### Example ```typescript "#ABC123"; "rgb(255, 0, 0)"; "hsl(200, 100%, 50%)"; ``` #### Default ```ts "#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 ```ts 1 ``` *** ### strokeWidth > **strokeWidth**: `number` The width of the element's stroke in pixels. #### Default ```ts 2 ``` *** ### strokeStyle > **strokeStyle**: `"solid"` | `"dashed"` | `"dotted"` The style of the element's stroke. #### Default ```ts "solid" ``` *** ### type > **type**: `"Path"` *** ### distanceMarker > **distanceMarker**: `boolean` Whether a distance marker is shown at the midpoint of the path. #### Default ```ts false ``` *** ### routingMode > **routingMode**: `null` | `"driving"` | `"cycling"` | `"walking"` | `"flying"` Whether this represents a route, and if so, what mode of transport\ is used. If this is `null`, the path is not considered to be a route, so while it\ can have a `distanceMarker`, it will does not have a start or end cap. #### Default ```ts null ``` *** ### endCaps > **endCaps**: `boolean` Whether or not to show Start and End caps on the path. This is\ only available if the `routingMode` is set. #### Default ```ts false ``` *** ### 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 ```ts "default" ``` --- [Next Page](/llms-full.txt/1)

My Felt app

My Felt app

My Felt app

Cities

Layers