This guide describes how to add interactive widgets to your map in CARTO Builder. Widgets are embedded within your visualization and do not modify your original data, they simply allow you to explore your data and get insights by drilling-down different types of filters that are connected to each other and the map’s viewport.
In the Widgets tab of Builder, you will see the list of your current widgets. If you haven’t created a widget yet, you will see the following page:
Click on New widget button to start interacting with your data. When you add a widget, it’s always the Formula widget by default:
You can access the quick actions menu to manage your widgets by clicking on the “three dots” icon in the top-right corner. There are two options available: Rename and Delete widget.
You can also manage your widgets by clicking on the “three dots” icon in the top-right corner of the widget. There are two options available: Widget options and Delete widget.
Click on the top-right icon to show or hide the list of your widgets from the map:
If you click on the Back arrow, you will exist the widget options and you will be redirected to the Widget tab of Builer from where you will see the list of your current widgets.
Click on the “three dots” icon to configure your widgets. There are 3 options available: Widgets options, Rename and Delete widget.
To add a new widget to the map, click on Add widget button and select the data source:

Modes (behaviour)

The widgets can work in two different modes: viewport and global.
  • Viewport: the widgets in viewport mode update the information when the viewport changes.
  • Global: the widgets in global mode read the data from the entire data source, independently from what's shown in the viewport of the map.
Viewport Mode
By default the widgets work in viewport mode, meaning the data gets updated when the viewport extent changes.
For simple features, viewport widgets get the data by performing a SQL query to the data warehouse; whereas, if you are working with aggregated grids or pre-generated tilesets, viewport widgets work with the data that has been downloaded for visualization which is available locally in the browser.
Global Mode
You can configure Widgets to make use of the global mode where information is displayed for the full data source. Global mode is only available for simple features and the data is retrieved by performing a SQL query to the data warehouse.
Global mode is not available for pre-generated Tilesets and Aggregated grids based on Spatial Indexes. Pre-generated tilesets are based on a different data structure that doesn't allow cross filtering between widgets. Aggregated grids always show aggregated data in the map, which would be inconsistent with the global, non-aggregated data used by a global widget.
At this moment, there are six types of widgets available to customize your visualization and enable a richer interaction with your data:
  • Formula: Shows aggregated numerical data from the features in the map’s viewport.
  • Category: Breaks down the data into categories and shows aggregated values.
  • Histogram: Shows the frequency distribution across equal bins in the data range.
  • Range Widget: Shows a specific range of numerical data that is filtered by using a slider or manual inputs.
  • Time-Series: Shows the frequency distribution aggregated by a fixed temporal period (Days, Weeks, Months or Years). It also allows to create animated maps.
  • Table Widget: It shows tabular information of the features in the viewport.
When working with aggregated data sources, you will need to select an aggregation operation for your columns.
Connections to Redshift clusters don’t support aggregation of categorical properties.