> 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/widgets.md). # Widgets In Builder, widgets empower users to dynamically explore data, leading to rich visualizations. They also serve to filter data based on the map viewport and interconnected widgets. Below are the current type of Widgets available to customize your visualization and enable a richer interaction with your data: * [**Formula Widget**](/carto-user-manual/maps/widgets/formula-widget.md): Shows aggregated numerical data as a single metric. * [**Category Widget**](/carto-user-manual/maps/widgets/category-widget.md): Segments data into distinct categories displaying aggregated metrics. * [**Pie Widget**](/carto-user-manual/maps/widgets/pie-widget.md): Visualizes categorical data by displaying the proportion of each category relative to the whole data set. * [**Histogram Widget**](/carto-user-manual/maps/widgets/histogram-widget.md): Shows the frequency distribution across equal bins in the data range. * [**Range Widget**](/carto-user-manual/maps/widgets/range-widget.md): Shows a specific range of numerical data adjustable via slider or input values. * [**Time Series Widget**](/carto-user-manual/maps/widgets/time-series-widget.md)**:** Shows the frequency distribution aggregated by a temporal period. It also allows to create animated maps. * [**Table Widget**](/carto-user-manual/maps/widgets/table-widget.md): Displays tabular data for easy viewing and interaction. {% hint style="info" %} Time Series Widget is not supported for raster or pre-generated tilesets sources. Table Widget is not supported for raster sources. {% endhint %} ### Adding a Widget Add a widget to Builder by clicking "New Widget" and select your data source.

Then, select a widget type from the menu: *Formula,* *Category*, *Histogram*, *Range*, *Time Series* or *Table*.

### Configuring a Widget Once you have selected the widget type of your preference, you are ready to configure your Widget. ### Widget Data In the Data section of the Widget configuration, choose an aggregation operation `COUNT`, `AVG`, `MAX`, `MIN` or `SUM` and, if relevant, specify the column on which to perform the aggregation.

{% hint style="info" %} When working with **pre-generated tilesets**, please ensure your data have a unique identifier named *`geoid`* for correct Widgets calculations. {% endhint %} ### Widget Display Using the **Formatting** option, you can auto-format data, ensuring enhanced clarity. For instance, you can apply automatic rounding, comma-separations, or percentage displays.

*Formatting selector on Widget configuration*

You can use **Notes** to supplement your Widgets with descriptive annotations which support [Markdown syntax](https://www.markdownguide.org/basic-syntax/), allowing to add text formatting, ordered lists, links, etc.

### Widget Behavior Widgets offer two distinct modes of operation: "Global" and "Viewport". **Global Mode** By default widgets are calculated in global mode where information is displayed for the full data source. This option does not take into account the viewport extent of the data. **Viewport Mode** You can configure widgets to work in viewport mode, meaning the data gets updated when the viewport extent changes. For dynamic tiling sources, viewport widgets get the data by performing a SQL query to the data warehouse; whereas, if you are working with pre-generated tilesets, viewport widgets work with the data that has been downloaded for visualization which is available locally in the browser. {% hint style="info" %} Please be aware that **global mode is not supported for pre-generated** **tileset** sources. In such scenarios, the functionality defaults to viewport mode. This means that all calculations are based on the extent of the map's current viewport. {% endhint %} **Cross-filtering** Some widgets support **cross-filtering**, allowing them to filter not only themselves but also other components on the map. When enabled, the widget can apply filters across: * A **single source** (default behavior), affecting all layers and widgets connected to that source. * **Multiple sources**, as long as they share the same filtering property (e.g., region, category, or timestamp). When **cross-filtering is disabled** for a widget, it becomes read-only: it still displays aggregated data but cannot trigger any filtering actions on the widget itself or related components. This behavior can be toggled on or off per widget using the **cross-filtering toggle** in the widget configuration panel.

{% hint style="info" %} **Limitations** The **Time Series widget** supports cross-filtering across multiple sources **only over the temporal property**. Split by property is not supported. Only **one Range widget per map** using a specific property can be configured to cross-filter across multiple sources. {% endhint %} **Collapsing widgets** Every widget can be collapsed from its header. In the Behavior section, you can also turn on **Collapse when no layers are visible**, so the widget collapses to its header when none of its layers are visible on the map. ### Widgets panel layout Widgets appear in the widgets panel on the right side of the map. As an Editor, you can show them in one or two columns, float the panel over the map, and make a widget take the full width of the panel. Viewers see the layout you choose. Learn more in [Map layout](/carto-user-manual/maps/map-layout.md#widgets-panel). ### Clearing widget filters When widgets are filtering the map, the top of the panel shows how many filters are active. Click **Clear all** to remove every widget filter at once. To clear a single widget, use **Clear** inside that widget. Widget filters and SQL parameters are cleared separately. **Clear all** removes widget filters, and **Reset all** in the parameters bar resets parameters. {% hint style="info" %} As Widget settings differ between widget types, please visit the individual widget's documentation page for more detailed information. {% 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.carto.com/carto-user-manual/maps/widgets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.