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-uipackage 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.
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 useCartoLayerProps 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.
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.
Please read the Data Sources guide for more information.
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 for the widget instance |
| Title to show in the widget header |
| ID of the data source to get the data from |
| Indicates whether the widget is using the global mode |
| Indicates whether the widget update is animated or jumps directly to the new state |
| Props to pass to the WrapperWidgetUI |
| Message (title and body) to show when there is no data available for the widget |
| Extra props to pass to the |
| 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.
Last updated
