LogoLogo
HomeAcademyLoginTry for free
  • Welcome
  • What's new
    • Q2 2025
    • Q1 2025
    • Q4 2024
    • Q3 2024
    • Q2 2024
    • Q1 2024
    • Q4 2023
    • Q3 2023
    • Q2 2023
    • Q1 2023
    • Q4 2022
    • Q3 2022
  • FAQs
    • Accounts
    • Migration to the new platform
    • User & organization setup
    • General
    • Builder
    • Workflows
    • Data Observatory
    • Analytics Toolbox
    • Development Tools
    • Deployment Options
    • CARTO Basemaps
    • CARTO for Education
    • Support Packages
    • Security and Compliance
  • Getting started
    • What is CARTO?
    • Quickstart guides
      • Connecting to your data
      • Creating your first map
      • Creating your first workflow
      • Developing your first application
    • CARTO Academy
  • CARTO User Manual
    • Overview
      • Creating your CARTO organization
      • CARTO Cloud Regions
      • CARTO Workspace overview
    • Maps
      • Data sources
        • Simple features
        • Spatial Indexes
        • Pre-generated tilesets
        • Rasters
        • Defining source spatial data
        • Managing data freshness
        • Changing data source location
      • Layers
        • Point
          • Grid point aggregation
          • H3 point aggregation
          • Heatmap point aggregation
          • Cluster point aggregation
        • Polygon
        • Line
        • Grid
        • H3
        • Raster
        • Zoom to layer
      • Widgets
        • Formula widget
        • Category widget
        • Pie widget
        • Histogram widget
        • Range widget
        • Time Series widget
        • Table widget
      • SQL Parameters
        • Date parameter
        • Text parameter
        • Numeric parameter
        • Publishing SQL parameters
      • Interactions
      • Legend
      • Basemaps
        • Basemap selector
      • AI Agents
      • SQL analyses
      • Map view modes
      • Map description
      • Feature selection tool
      • Search locations
      • Measure distances
      • Exporting data
      • Download PDF reports
      • Managing maps
      • Sharing and collaboration
        • Editor collaboration
        • Map preview for editors
        • Map settings for viewers
        • Comments
        • Embedding maps
        • URL parameters
      • Performance considerations
    • Workflows
      • Workflow canvas
      • Results panel
      • Components
        • Aggregation
        • Custom
        • Data Enrichment
        • Data Preparation
        • Generative AI
        • Input / Output
        • Joins
        • Parsers
        • Raster Operations
        • Spatial Accessors
        • Spatial Analysis
        • Spatial Constructors
        • Spatial Indexes
        • Spatial Operations
        • Statistics
        • Tileset Creation
        • BigQuery ML
        • Snowflake ML
        • Google Earth Engine
        • Google Environment APIs
        • Telco Signal Propagation Models
      • Data Sources
      • Scheduling workflows
      • Sharing workflows
      • Using variables in workflows
      • Executing workflows via API
      • Temporary data in Workflows
      • Extension Packages
      • Managing workflows
      • Workflows best practices
    • Data Explorer
      • Creating a map from your data
      • Importing data
        • Importing rasters
      • Geocoding data
      • Optimizing your data
    • Data Observatory
      • Terminology
      • Browsing the Spatial Data Catalog
      • Subscribing to public and premium datasets
      • Accessing free data samples
      • Managing your subscriptions
      • Accessing your subscriptions from your data warehouse
        • Access data in BigQuery
        • Access data in Snowflake
        • Access data in Databricks
        • Access data in Redshift
        • Access data in PostgreSQL
    • Connections
      • Google BigQuery
      • Snowflake
      • Databricks
      • Amazon Redshift
      • PostgreSQL
      • CARTO Data Warehouse
      • Sharing connections
      • Deleting a connection
      • Required permissions
      • IP whitelisting
      • Customer data responsibilities
    • Applications
    • Settings
      • Understanding your organization quotas
      • Activity Data
        • Activity Data Reference
        • Activity Data Examples
        • Activity Data Changelog
      • Users and Groups
        • Inviting users to your organization
        • Managing user roles
        • Deleting users
        • SSO
        • Groups
        • Mapping groups to user roles
      • CARTO Support Access
      • Customizations
        • Customizing appearance and branding
        • Configuring custom color palettes
        • Configuring your organization basemaps
        • Enabling AI Agents
      • Advanced Settings
        • Managing applications
        • Configuring S3 Bucket for Redshift Imports
        • Configuring OAuth connections to Snowflake
        • Configuring OAuth U2M connections to Databricks
        • Configuring S3 Bucket integration for RDS for PostgreSQL Exports in Builder
        • Configuring Workload Identity Federation for BigQuery
      • Data Observatory
      • Deleting your organization
    • Developers
      • Managing Credentials
        • API Base URL
        • API Access Tokens
        • SPA OAuth Clients
        • M2M OAuth Clients
      • Named Sources
  • Data and Analysis
    • Analytics Toolbox Overview
    • Analytics Toolbox for BigQuery
      • Getting access
        • Projects maintained by CARTO in different BigQuery regions
        • Manual installation in your own project
        • Installation in a Google Cloud VPC
        • Core module
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • cpg
        • data
        • http_request
        • import
        • geohash
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • routing
        • s2
        • statistics
        • telco
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release notes
      • About Analytics Toolbox regions
    • Analytics Toolbox for Snowflake
      • Getting access
        • Native App from Snowflake's Marketplace
        • Manual installation
      • Key concepts
        • Spatial indexes
        • Tilesets
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • data
        • http_request
        • import
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release Notes
    • Analytics Toolbox for Databricks
      • Getting access
        • Personal (former Single User) cluster
        • Standard (former Shared) cluster
      • Reference
        • lds
        • tiler
      • Guides
      • Release Notes
    • Analytics Toolbox for Redshift
      • Getting access
        • Manual installation in your database
        • Installation in an Amazon Web Services VPC
        • Core version
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • clustering
        • constructors
        • data
        • http_request
        • import
        • lds
        • placekey
        • processing
        • quadbin
        • random
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
      • Release Notes
    • Analytics Toolbox for PostgreSQL
      • Getting access
        • Manual installation
        • Core version
      • Key concepts
        • Tilesets
        • Spatial Indexes
      • SQL Reference
        • h3
        • quadbin
        • tiler
      • Guides
        • Creating spatial index tilesets
        • Running queries from Builder
      • Release Notes
    • CARTO + Python
      • Installation
      • Authentication Methods
      • Visualizing Data
      • Working with Data
        • How to work with your data in the CARTO Data Warehouse
        • How to access your Data Observatory subscriptions
        • How to access CARTO's Analytics Toolbox for BigQuery and create visualizations via Python notebooks
        • How to access CARTO’s Analytics Toolbox for Snowflake and create visualizations via Python notebooks
        • How to visualize data from Databricks
      • Reference
    • CARTO QGIS Plugin
  • CARTO for Developers
    • Overview
    • Key concepts
      • Architecture
      • Libraries and APIs
      • Authentication methods
        • API Access Tokens
        • OAuth Access Tokens
        • OAuth Clients
      • Connections
      • Data sources
      • Visualization with deck.gl
        • Basemaps
          • CARTO Basemap
          • Google Maps
            • Examples
              • Gallery
              • Getting Started
              • Basic Examples
                • Hello World
                • BigQuery Tileset Layer
                • Data Observatory Tileset Layer
              • Advanced Examples
                • Arc Layer
                • Extrusion
                • Trips Layer
            • What's New
          • Amazon Location
            • Examples
              • Hello World
              • CartoLayer
            • What's New
        • Rapid Map Prototyping
      • Charts and widgets
      • Filtering and interactivity
      • Summary
    • Quickstart
      • Make your first API call
      • Visualize your first dataset
      • Create your first widget
    • Guides
      • Build a public application
      • Build a private application
      • Build a private application using SSO
      • Visualize massive datasets
      • Integrate CARTO in your existing application
      • Use Boundaries in your application
      • Avoid exposing SQL queries with Named Sources
      • Managing cache in your CARTO applications
    • Reference
      • Deck (@deck.gl reference)
      • Data Sources
        • vectorTableSource
        • vectorQuerySource
        • vectorTilesetSource
        • h3TableSource
        • h3QuerySource
        • h3TilesetSource
        • quadbinTableSource
        • quadbinQuerySource
        • quadbinTilesetSource
        • rasterSource
        • boundaryTableSource
        • boundaryQuerySource
      • Layers (@deck.gl/carto)
      • Widgets
        • Data Sources
        • Server-side vs. client-side
        • Models
          • getFormula
          • getCategories
          • getHistogram
          • getRange
          • getScatter
          • getTimeSeries
          • getTable
      • Filters
        • Column filters
        • Spatial filters
      • CARTO APIs Reference
    • Release Notes
    • Examples
    • CARTO for React
      • Guides
        • Getting Started
        • Views
        • Data Sources
        • Layers
        • Widgets
        • Authentication and Authorization
        • Basemaps
        • Look and Feel
        • Query Parameters
        • Code Generator
        • Sample Applications
        • Deployment
        • Upgrade Guide
      • Examples
      • Library Reference
        • Introduction
        • API
        • Auth
        • Basemaps
        • Core
        • Redux
        • UI
        • Widgets
      • Release Notes
  • CARTO Self-Hosted
    • Overview
    • Key concepts
      • Architecture
      • Deployment requirements
    • Quickstarts
      • Single VM deployment (Kots)
      • Orchestrated container deployment (Kots)
      • Advanced Orchestrated container deployment (Helm)
    • Guides
      • Guides (Kots)
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Use Workload Identity in GCP
        • High availability configuration for CARTO Self-hosted
        • Configure your custom service account
      • Guides (Helm)
        • Configure your own buckets (Helm)
        • Configure an external in-memory cache (Helm)
        • Enable Google Basemaps (Helm)
        • Enable the CARTO Data Warehouse (Helm)
        • Configure an external proxy (Helm)
        • Enable BigQuery OAuth connections (Helm)
        • Configure Single Sign-On (SSO) (Helm)
        • Use Workload Identity in GCP (Helm)
        • Use EKS Pod Identity in AWS (Helm)
        • Enable Redshift imports (Helm)
        • Migrating CARTO Self-hosted installation to an external database (Helm)
        • Advanced customizations (Helm)
        • Configure your custom service account (Helm)
    • Maintenance
      • Maintenance (Kots)
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
        • Change the Admin Console password
      • Maintenance (Helm)
        • Monitoring (Helm)
        • Rotating keys (Helm)
        • Uninstall (Helm)
        • Backups (Helm)
        • Updates (Helm)
    • Support
      • Get debug information for Support (Kots)
      • Get debug information for Support (Helm)
    • CARTO Self-hosted Legacy
      • Key concepts
        • Architecture
        • Deployment requirements
      • Quickstarts
        • Single VM deployment (docker-compose)
      • Guides
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Enable Redshift imports
        • Configure your custom service account
        • Advanced customizations
        • Migrating CARTO Self-Hosted installation to an external database
      • Maintenance
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
      • Support
    • Release Notes
  • CARTO Native App for Snowflake Containers
    • Deploying CARTO using Snowflake Container Services
  • Get Help
    • Legal & Compliance
    • Previous libraries and components
    • Migrating your content to the new CARTO platform
Powered by GitBook
On this page
  • Modes (Behavior)
  • Data sources
  • Common properties for data-driven widgets
  • Usage recommendations for data-driven widgets
  • Bar widget
  • Category widget
  • Geocoder widget
  • Feature Selection widget
  • Formula widget
  • Histogram widget
  • Legend widget
  • Pie widget
  • ScatterPlot widget
  • Table widget
  • TimeSeries widget

Was this helpful?

Export as PDF
  1. CARTO for Developers
  2. CARTO for React
  3. Guides

Widgets

PreviousLayersNextAuthentication and Authorization

Last updated 11 months ago

Was this helpful?

You can use widgets in your application to provide advanced functionality for exploring and filtering the information. CARTO for React comes with several widgets out-of-the-box that you can add really easily to your spatial apps:

The widgets are implemented combining the functionality of three different library packages:

  • @carto/react-ui. This package provides the user interface functionality for widgets. This means you can reuse the UI with your own business logic if you need to provide custom functionality.

  • @carto/react-widgets. This package takes advantage of the UI components from the @carto/react-ui package and provides the business logic for the filters, including the integration with other components through the Redux store.

  • @carto/react-workers. This package implements the calculations needed by the widgets. Everything is implemented using web workers to improve the performance and the user experience.

We can group the widgets in two main categories:

  • Data-driven widgets. These widgets perform calculations on the data sources, including aggregations, and then show the results using different types of charts. The widgets included in this category are: Bar, Category, Formula, Histogram, Pie, Scatterplot, Table and Time-Series.

  • Non data-driven widgets. These widgets provide functionality that does not perform calculations on the data sources. We have the Geocoder widget to provide geocoding functionality, the Legend widget to provide layer selection and legend functionality and the FeatureSelectionWidget to filter features drawing a shape in the map.

Modes (Behavior)

The data-driven widgets (except the Scatterplot and Table widgets) can work in two different modes: viewport and global. By default the widgets work in viewport mode, meaning they are showing information about the features in the current viewport. But you can also configure them to use the global mode where information is displayed for the full data source.

The main difference is that widgets in global mode are static, they always show the same information, but widgets in viewport mode update the information when the viewport changes.

In both modes, widgets get the data they need by performing a request to the API that will execute a SQL query in the data warehouse.

Warning

Global mode is not available for widgets linked to static (pre-generated) tilesets sources, only with dynamic tiling. The main reason for that is that static tilesets are usually created for extremely large datasets (i.e. billions of features) and the SQL query could have a processing time not suitable for an interactive applications. Another reason is that the source table(s) for the tileset might have been updated (or it might not be even available) so the tileset and the widget could potentially show different information.

Data sources

The data-driven widgets need to perform different calculations to get the data they need. If we are using the viewport mode, every time we change the viewport, the widgets need to be updated and new calculations are performed.

Warning

Since deck.gl v8.8, included by default in CARTO for React 1.3, the CartoLayer works always with tiles (static or dynamic). This means that features can be simplified and/or dropped depending on the zoom level to improve the performance of the visualization. If your source is using dynamic tiles, it won't affect the widgets because the calculations are decoupled from the visualization. If your source is using static tiles (pre-generated tilesets), widget calculations at some zoom levels can be inaccurate due to features being dropped from the tiles to keep the tile size under the limit.

Common properties for data-driven widgets

Property
Description

id

ID for the widget instance

title

Title to show in the widget header

dataSource

ID of the data source to get the data from

global

Indicates whether the widget is using the global mode

animation

Indicates whether the widget update is animated or jumps directly to the new state

wrapperProps

Props to pass to the WrapperWidgetUI

noDataAlertProps

Message (title and body) to show when there is no data available for the widget

droppingFeaturesAlertProps

Extra props to pass to the NoDataAlert component when features have been dropped in the data source

onError

Event emitted when an error is thrown while the widget is doing calculations

Usage recommendations for data-driven widgets

Every data-driven widget provides different functionality so you should consider carefully which widget you want to use depending on the goals you have:

  • If you just want to show the number of features in the current viewport/dataset or you want to make a simple aggregation on a numeric column like calculating the sum or the average, you can use the FormulaWidget.

  • If you are dealing with data that you need to group by category (string values) like store types before making a calculation, you should use a widget that supports columns with categorical values (BarWidget, CategoryWidget, PieWidget).

  • If you are interested in understanding the distribution of numeric column values like store revenues, you should use the HistogramWidget.

  • If you have a column with timestamp values in your dataset and you want to understand trends or evolution through time, you can use the TimeSeriesWidget.

  • If you want to understand the correlation between two numeric columns of the same dataset, you should use the ScatterPlotWidget.

  • If you want to display the data in a tabular view and be able to order it by column values, you can use the TableWidget.

A particular use case that often arises when dealing with socio-demographics data is how to analyze data by age (i.e. population, employment status…). If we are just interested in the distribution, we should use the HistogramWidget, but if we want to define our own ranges/groups, what we are doing is to create categories (those ranges), so we should use a widget that supports categorical data. The main difference is that bars in a HistogramWidget cannot be re-ordered, the X axis has numerical values so you need to keep the order; but with widgets supporting categorical data, it might make sense to reorder to show first the category with more elements or to order alphabetically the categorical values.

Bar widget

Groups features into categories (column) and executes an operation on another column (operationColumn) for each group. The categories are then visualized using vertical bars.

Category widget

Groups features into categories (column) and executes an operation on another column (operationColumn) for each group. The categories are then visualized using horizontal bars. Displays 5 categories at the same time.

Geocoder widget

Provides geocoding functionality through a search bar, requiring credentials/token with access to geocoding services.

When the results are returned, the widget performs an automatic zoom to the best result (no autocomplete) and adds a marker.

Feature Selection widget

Provides functionality to filter spatially the features by drawing a shape on the map.

Formula widget

Calculates a value executing an aggregation operation on a data source column.

Histogram widget

Groups features into buckets after executing an aggregation operation on a column.

Legend widget

Creates a widget for switching layers on/off and showing legends. The legend representation depends on the legend type. The widget access the layer information from the store and add the legend for those layers where it has been specified.

Pie widget

Groups features into categories (column) and executes an operation on another column (operationColumn) for each group.

ScatterPlot widget

Represents two properties/columns in a cartesian chart from a data source to help understand if there is correlation between them.

Table widget

Displays the column values for the current features visualized in the map in a tabular way.

TimeSeries widget

Groups features into time intervals and allows to play an animation that filters the features displayed based on the current interval.

If you are working with vector tiles (static or dynamic), you need to provide the name of the field that identifies each feature using the uniqueIdProperty property while calling the function, except if your source already includes a field called cartodb_id or geoid. This is needed to ensure that each feature is only counted once even if it is split in several tiles.

Please read the guide for more information.

There are some properties that are used by all the data-driven widgets. You can check the full API reference for each widget :

Data Sources
here
View on Github
Bar
Category
FeatureSelection
Formula
Geocoder
Histogram
Legend
Pie
ScatterPlot
Table
TimeSeries
useCartoLayerProps