CARTO for React

CARTO for React

Widgets

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.

There is also a difference in how they are implemented. Widgets in viewport mode work with the data that has been downloaded for visualization so all the data needed to make the calculations is available locally in the browser. On the other hand, widgets in global mode get the data by performing a SQL query to the data warehouse.

Data sources

The data-driven widgets work with vector tiles or GeoJSON features provided by the Maps API. The workers retrieve the information from the tiles / GeoJSON features and execute the different calculations needed by each widget. Every time we change the viewport, the widgets are updated.

Common properties for data-driven widgets

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

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.

Bar Widget

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.

Category Widget

Geocoder widget

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

Geocoder Widget

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.

Feature Selection Widget

Formula widget

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

Formula Widget

Histogram widget

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

Histogram Widget

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.

Legend Widget

Pie widget

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

Pie Widget

ScatterPlot widget

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

ScatterPlot Widget

Table widget

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

Table Widget

TimeSeries widget

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

TimeSeries Widget