# 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()`](/js-sdk-api-reference/main/feltcontroller.md#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()`](/js-sdk-api-reference/main/feltcontroller.md#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()`](/js-sdk-api-reference/main/feltcontroller.md#getselection). This returns an array of [`EntityNode`](/js-sdk-api-reference/selection/entitynode.md) 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()`](/js-sdk-api-reference/main/feltcontroller.md#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()`](/js-sdk-api-reference/main/feltcontroller.md#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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.felt.com/js-sdk/working-with-selection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.