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() method. Only one feature can be selected at a time - selecting a new feature will replace the current selection.

await felt.selectFeature({
  id: "feature-123",
  layerId: "buildings-layer"
});

The selectFeature() method accepts options to control the selection behavior:

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(). This returns an array of EntityNode objects, each representing a selected entity. The selection can include various types of entities at the same time, such as annotations and features:

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():

// 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() method:

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:

const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    // Handle selection...
  }
});

// Later, when you're done:
unsubscribe();

1. Handle empty selection: Remember that the selection array might be empty if nothing is selected:

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.