> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-user-manual/maps/interactions.md).
# Interactions
Builder interactions let you configure how each layer responds when a user clicks or hovers over a feature on the map. Interactions are disabled by default but can be enabled for each individual layer using the toggle button. Once enabled, choose between two interaction types, **Click** and **Hover**:
* **Click**: choose one or both of:
* **Filter by feature**: clicking a feature filters your map data directly. See [Filter by feature](#filter-by-feature) below.
* **Pop-up info panel**: clicking a feature shows a pop-up or info panel with its details. See [Pop-up info panel](#pop-up-info-panel) below.
* **Hover**: hovering over a feature shows a pop-up or info panel with its details.
## Filter by feature
In addition to Click and Hover for viewing feature details, you can enable **Filter by feature** on a layer (under the Click tab) so that clicking a feature filters your map data directly. It can be enabled together with the pop-up info panel option, independently of it.
### Filtering modes
Once enabled, choose one of two scopes:
* **Only this layer**: highlights the clicked feature(s) and filters only this layer's data. Available on Point, Line, Polygon, H3, and Quadbin layers.
* **All layers in the selected areas**: highlights the clicked area(s) and filters every layer's data to what intersects them, acting as a spatial mask. Available only on Polygon, H3, and Quadbin layers — Point and Line layers can't filter intersecting features, since a point or a line has no area to intersect with.
{% hint style="info" %}
Click additional features while holding Shift to add them to the current selection. The filter remains active as you pan and zoom, and you can clear it at any time by pressing Esc or clicking outside any feature.
{% endhint %}
### Where the filter applies
A click-based filter behaves like any other map filter:
* Widgets fed by the filtered source update immediately.
* PDF exports reflect the filtered map.
* Viewport data exports contain only the filtered features.
## Pop-up info panel
Clicking or hovering over a feature can show its details as a pop-up window or an info panel, in addition to (or instead of) filtering data with [Filter by feature](#filter-by-feature).
### Display styles
Interactions can be displayed in two formats:
* **Pop-up windows**: Click and hover-type interactions can be styled in various themes, such as light or dark.
* **Info panel**: Click-type interactions can also appear in the right-side panel with a default style.
You can switch between these from the layer's interaction settings.
Pop-up window (left) vs. info panel (right)
### Configuring properties
Interactions can be customized either manually or through custom HTML code, with support for properties in vector layers and both properties and custom expressions in raster layers:
* **Adding properties manually**: For vector layers, users can set labels and customize formats for their properties. For raster layers, users can configure bands (properties) and also define *custom expressions* to enhance data visualization and analysis.
* **Using HTML custom code**: This method offers flexibility for both vector and raster layers. While vector layers allow users to design tailored interaction layouts using properties, raster layers support both properties and custom expressions for advanced configurations. You can add images, modify styles, and more to create tailored user experiences.
#### Custom aggregation in popups
Popup fields on aggregated layers (H3, Quadbin, and point / line / polygon layers using [Aggregate by geometry](/carto-user-manual/maps/layers.md#aggregate-by-geometry)) support custom SQL aggregation expressions. This is useful when a tooltip needs to display a derived metric (rate, ratio, weighted average) at click or hover scope.
```sql
SUM(female) / NULLIF(SUM(population), 0)
```
For details on the same feature applied to layer styling, see the [H3 layer documentation](/carto-user-manual/maps/layers/h3.md#custom-aggregation-expressions).
### Click behavior
**Non-aggregated layers**
* **How it works**: Information is retrieved directly from the server when you click on points, lines, or polygons.
* **Highlighting**: Features are automatically highlighted when clicked.
**Aggregated layers**
* **How it works**: Information is calculated on your computer for aggregated data (e.g., spatial indexes, cluster, etc.).
* **Aggregation operation**: You'll need to specify how data is aggregated (e.g., totals, averages).
#### Navigating stacked and overlapping features
When you click a location where multiple features in a layer share the same space - overlapping polygons, overlapping lines, or multiple records sharing the same geometry (for example, repeated features or time-series rows at the same address) - the popup and the info panel display pagination controls so you can step through every feature at that location.
Use the previous and next arrows to move across each feature. A counter indicates your position (for example, "2 of 7"). As you paginate, the highlight on the map updates to show the feature currently inspected.
Pagination is available in both **pop-up** and **info panel** display modes.
### Hover behavior
**Non-aggregated layers**
* **How it works**: Information is retrieved on your computer for individual points, lines, or polygons when you hover over them.
* **Highlighting**: Automatic, same as Click.
**Aggregated layers**
* **How it works**: Information is calculated on your computer for grouped data when you hover over it.
* **Aggregation operation**: You'll need to specify how data is aggregated (e.g., totals, averages).
## Limitations
{% hint style="warning" %}
**Interactions limitations**
* Highlighting isn't available on **raster** layers.
* Highlighting on **static (pre-generated) tileset** layers requires the source to include a column named `geoid` as a unique identifier — other vector sources and spatial index layers don't need this.
* **Filter by feature** can't be enabled on **raster**, **heatmap**, or **cluster** layers, **static tilesets**, or layers **aggregated by geometry**.
* The **all layers in the selected areas** scope is limited to **polygon**, **H3**, and **quadbin** layers — point and line layers can't filter intersecting features.
* **Hover** pop-ups display up to **5 columns**, with values limited to **150 characters**.
* **Redshift** connections only support aggregating **categorical properties** by **any value** for styling and interactions.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.carto.com/carto-user-manual/maps/interactions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.