Widgets

​View on Github​
Package
Version
Downloads
@carto/react-widgets
​​
​​
​​
​​
A set of advanced widgets, which allow not only a visual representation but a rich interaction with data & map layers, such as filtering or an automatic data refresh on viewport change, thanks to the connection with the CARTO slice on redux.
This package, @carto/react-widgets contains the widgets business logic and the @carto/react-ui package contains the user interface components. The UI is decoupled from the business logic so you can provide your own user interface or modify the business logic. To review interactively the UI for the widgets, check the Storybook catalogue.
Components
BarWidget
Renders a <BarWidget /> component, binded to a source at redux. From a data perspective, the BarWidget would present a behaviour equivalent to CategoryWidget (groups or ‘categories’ from a column, with an aggregated calculation), but with a different UI that uses vertical bars instead of horizontal bars.
Input:
Param
Type
Default
Description
props
Object
​
​
props.id
string
​
ID for the widget instance.
props.title
string
​
Title to show in the widget header.
props.dataSource
string
​
ID of the data source to get the data from.
props.column
string
​
Name of the data source’s column to get the data from.
props.operation
string
​
Operation to apply to the operationColumn. Must be one of those defined in AggregationTypes object.
[props.operationColumn]
string | Array<string>
​
(optional) Name of the data source’s column to operate with. If not defined, same as column. If multiple columns are provided, they will be combined using the operation specified with the joinOperation property. Note: support for multiple columns is only available beginning with v1.3
[props.joinOperation]
string
​
Operation applied to aggregate multiple operation columns into a single one. Must be one of those defined in AggregationTypes object. Note: this property is only available beginning with v1.3
[props.global]
bool
false
(optional) Indicates whether the widget is using the global mode.
[props.animation]
bool
true
(optional) Indicates whether the widget update is animated or jumps directly to the new state.
[props.formatter]
function
​
(optional) formatterCallback: Function to format each value returned.
[props.labels]
Object
{}
(optional) Overwrite category labels.
[props.filterable]
bool
true
(optional) Indicates whether filtering capabilities are enabled or not.
[props.onError]
function
​
(optional) errorCallback: Function to handle error messages from the widget.
[props.wrapperProps]
Object
​
(optional) Extra props to pass to WrapperWidgetUI​
[props.noDataAlertProps]
Object
{ title: 'No data available', body: 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.' }
(optional) Message (title and body) to show when there is no data available for the widget.
[props.droppingFeaturesAlertProps]
Object
{ body: 'Data for this widget is not available at this zoom level. Zoom in to get data from features in the map.' }
(optional) Extra props to pass to the NoDataAlert component when features have been dropped in the data source
Example:
In this example, the widget would display the SUM of population for all the countries, grouped by continent:
import { BarWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} people`;
  
return (
  <BarWidget
    id="populationByContinent"
    title="Population by continent"
    dataSource="countriesSourceId"
    column="continent"
    operationColumn="population"
    operation={AggregationTypes.SUM}
    formatter={customFormatter}
    onError={console.error}
  />
);
  
// The operationColumn wouldn't be required if using AggregationTypes.COUNT, to count the number of countries per continent
Available beginning with v1.3
You can also make calculations on widgets using multiple columns. For instance, if you are working with a dataset that contains population data disaggregated by gender: population_m and population_f, you can use an array in operationColumn and sum the values from both columns using the joinOperation property.
import { BarWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} people`;
  
return (
  <BarWidget
    id="populationByContinent"
    title="Population by continent"
    dataSource="countriesSourceId"
    column="continent"
    operationColumn={["population_m", "population_f"]}
    joinOperation={AggregationTypes.SUM}
    operation={AggregationTypes.SUM}
    formatter={customFormatter}
    onError={console.error}
  />
);
CategoryWidget
Renders a <CategoryWidget /> component, binded to a source at redux.
Input:
Param
Type
Default
Description
props
Object
​
​
props.id
string
​
ID for the widget instance.
props.title
string
​
Title to show in the widget header.
props.dataSource
string
​
ID of the data source to get the data from.
props.column
string
​
Name of the data source’s column to get the data from.
props.operation
string
​
Operation to apply to the operationColumn. Must be one of those defined in AggregationTypes object.
[props.operationColumn]
string | Array<string>
​
(optional) Name of the data source’s column to operate with. If not defined, same as column. If multiple columns are provided, they will be combined using the operation specified with the joinOperation property. Note: support for multiple columns is only available beginning with v1.3
[props.joinOperation]
string
​
Operation applied to aggregate multiple operation columns into a single one. Must be one of those defined in AggregationTypes object. Note: this property is only available beginning with v1.3
[props.global]
bool
false
(optional) Indicates whether the widget is using the global mode.
[props.animation]
bool
true
(optional) Indicates whether the widget update is animated or jumps directly to the new state.
[props.formatter]
function
​
(optional) formatterCallback: Function to format each value returned.
[props.labels]
Object
{}
(optional) Overwrite category labels.
[props.filterable]
bool
true
(optional) Indicates whether filtering capabilities are enabled or not.
[props.searchable]
bool
true
(optional) Indicates whether the functionality for searching in categories not displayed is available or not.
[props.onError]
function
​
(optional) errorCallback: Function to handle error messages from the widget.
[props.wrapperProps]
Object
​
(optional) Extra props to pass to WrapperWidgetUI​
[props.noDataAlertProps]
Object
{ title: 'No data available', body: 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.' }
(optional) Message (title and body) to show when there is no data available for the widget.
[props.droppingFeaturesAlertProps]
Object
{ body: 'Data for this widget is not available at this zoom level. Zoom in to get data from features in the map.' }
(optional) Extra props to pass to the NoDataAlert component when features have been dropped in the data source
Example:
In this example, the widget would display the SUM of population for all the countries, grouped by continent:
import { CategoryWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} people`;
  
return (
  <CategoryWidget
    id="populationByContinent"
    title="Population by continent"
    dataSource="countriesSourceId"
    column="continent"
    operationColumn="population"
    operation={AggregationTypes.SUM}
    formatter={customFormatter}
    onError={console.error}
  />
);
  
// The operationColumn wouldn't be required if using AggregationTypes.COUNT, to count the number of countries per continent
Available beginning with v1.3
You can also make calculations on widgets using multiple columns. For instance, if you are working with a dataset that contains population data disaggregated by gender: population_m and population_f, you can use an array in operationColumn and sum the values from both columns using the joinOperation property.
import { CategoryWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} people`;
  
return (
  <CategoryWidget
    id="populationByContinent"
    title="Population by continent"
    dataSource="countriesSourceId"
    column="continent"
    operationColumn={["population_m", "population_f"]}
    joinOperation={AggregationTypes.SUM}
    operation={AggregationTypes.SUM}
    formatter={customFormatter}
    onError={console.error}
  />
);
FeatureSelectionWidget
Renders a <FeatureSelectionWidget /> component. The widget allows the user to draw a shape on the map and apply a filter to select the features within the shape. Once a shape has been drawn, it can be selected and modified by adding/removing vertices or translated to a new location. By default the mask is active but it can be disabled temporarily and re-enabled again.
There are different selection modes supporting different shapes. The mode selected by default is FEATURE_SELECTION_MODES.POLYGON. If you want to choose a different default selection mode, you can set the featureSelectionMode prop in the initialStateSlice.
If you want to use this widget in your app, you need to do two different things:
1.Add the <FeatureSelectionWidget> component to the view where you want to have it available. If you are using one of the CARTO for React templates and you want to use it in all of your views, you can add it to the <MapContainer> component.
2.Add the FeatureSelectionLayer to your layers list. If you are using one of the CARTO for React templates, you need to add it to the src/components/layers/index.js file like this:
import { FeatureSelectionLayer } from '@carto/react-widgets';
​
export const getLayers = () => {
  return [
    ...,
    FeatureSelectionLayer(),
  ];
}; 
Input:
Param
Type
Default
Description
props
Object
​
​
[props.className]
string
​
(optional) Material-UI withStyle class for styling
[props.selectionModes]
Array<FEATURE_SELECTION_MODES>
[FEATURE_SELECTION_MODES.CIRCLE, FEATURE_SELECTION_MODES.LASSO_TOOL, FEATURE_SELECTION_MODES.POLYGON, FEATURE_SELECTION_MODES.RECTANGLE]
Available selection modes.
[props.editModes]
EDIT_MODES
[EDIT_MODES.EDIT]
Available edit modes.
[props.tooltipPlacement]
string
'bottom'
Tooltip placement. Allowed values available here​
The FeatureSelectionLayer accepts the following optional props:
Param
Type
Default
Description
props
Object
​
​
[props.eventManager]
EventManager
nebula.gl event manager
(optional) This prop allows using a different event manager instead of the one provided by nebula.gl. It is used for integration with other mapping libraries like Google Maps JavaScript API.
[props.mask]
bool
true
Indicates whether to apply a mask or not to hide the features outside the shape drawn by the user.
Example:
In this example, we add a FeatureSelectionWidget supporting just two selection modes using a specific CSS class.
import { FeatureSelectionWidget } from "@carto/react-widgets";
import { FEATURE_SELECTION_MODES } from '@carto/react-core';
  
return (
  <FeatureSelectionWidget 
    className={myCSSClassName} 
    selectionModes={[FEATURE_SELECTION_MODES.POLYGON, FEATURE_SELECTION_MODES.RECTANGLE]}
  />
);
FormulaWidget
Renders a <FormulaWidget /> component, binded to a source at redux.
Input:
Param
Type
Default
Description
props
Object
​
​
props.id
string
​
ID for the widget instance.
props.title
string
​
Title to show in the widget header.
props.dataSource
string
​
ID of the data source to get the data from.
props.column
string | Array<string>
​
Name of the data source’s column to operate with. If multiple columns are provided, they will be combined using the operation specified with the joinOperation property. Note: support for multiple columns is only available beginning with v1.3
[props.joinOperation]
string
​
Operation applied to aggregate multiple columns into a single one. Must be one of those defined in AggregationTypes object. Note: this property is only available beginning with v1.3
props.operation
string
​
Operation to apply to the operationColumn. Must be one of those defined in AggregationTypes object.
[props.global]
bool
false
(optional) Indicates whether the widget is using the global mode.
[props.animation]
bool
true
Indicates whether the widget update is animated or jumps directly to the new state
[props.formatter]
function
​
(optional) formatterCallback: Function to format each value returned.
[props.onError]
errorCallback
​
(optional) errorCallback: Function to handle error messages from the widget.
[props.wrapperProps]
Object
​
(optional) Extra props to pass to WrapperWidgetUI​
[props.noDataAlertProps]
Object
{ title: 'No data available', body: 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.' }
(optional) Message (title and body) to show when there is no data available for the widget.
[props.droppingFeaturesAlertProps]
Object
{ body: 'Data for this widget is not available at this zoom level. Zoom in to get data from features in the map.' }
(optional) Extra props to pass to the NoDataAlert component when features have been dropped in the data source
Example:
In this example, the widget would display the AVG sales for all the stores on screen:
import { FormulaWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} $`;
  
return (
  <FormulaWidget
    id="averageRevenue"
    title="Average revenue"
    dataSource="storesSourceId"
    column="revenue"
    operation={AggregationTypes.AVG}
    formatter={customFormatter}
    onError={console.error}
  />
);
Available beginning with v1.3
You can also make calculations on widgets using multiple columns. For instance, if you are working with a dataset that contains revenue data disaggregated by year: revenue_2021 and revenue_2022, you can use an array in column and sum the values from both columns using the joinOperation property.
import { FormulaWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} $`;
  
return (
  <FormulaWidget
    id="averageRevenue"
    title="Average revenue"
    dataSource="storesSourceId"
    column={["revenue_2021", "revenue_2022"]}
    joinOperation={AggregationTypes.SUM}
    operation={AggregationTypes.AVG}
    formatter={customFormatter}
    onError={console.error}
  />
);
GeocoderWidget
Renders a <GeocoderWidget /> component
Input:
Param
Type
Description
props
​
​
props.id
string
ID for the widget instance.
[props.className]
Object
(optional) Material-UI with CSS class for styling
[props.onError]
function
(optional) errorCallback: Function to handle error messages from the widget.
Example:
In this example, the widget is using the geocoder CSS custom style class and also defines a custom error handler:
import { GeocoderWidget } from "@carto/react-widgets";
  
const useStyles = makeStyles((theme) => ({
  geocoder: {
    position: 'absolute',
    top: theme.spacing(4),
    left: theme.spacing(4),
    zIndex: 1,
  }
}));
​
const onGeocoderWidgetError = (error) => {
  dispatch(setError(`Geocoding error: ${error.message}`));
};
​
return (
  <GeocoderWidget className={classes.geocoder} onError={onGeocoderWidgetError} />
);
HistogramWidget
Renders a <HistogramWidget /> component, binded to a source at redux.
Input:
Param
Type
Default
Description
props
Object
​
​
props.id
string
​
ID for the widget instance.
props.title
string
​
Title to show in the widget header.
props.dataSource
string
​
ID of the data source to get the data from.
props.column
string
​
Name of the data source’s column to get the data from.
props.operation
string
​
Operation to apply to the column. Must be one of those defined in AggregationTypes object.
[props.min]
number
​
(optional) Set this property to use this value as the minimum value instead of calculating it from the dataset.
[props.max]
number
​
(optional) Set this property to use this value as the maximum value instead of calculating it from the dataset.
[props.bins]
number
​
(optional) Number of bins to use. Incompatible with the ticks prop.
[props.ticks]
Array<number>
​
(optional) Array of numbers to build intervals (eg 1, 5, 10 will define 4 intervals: <1, [1,5), [5-10) and >= 10). Incompatible with the bins property, but you need to set one of them.
[props.global]
bool
false
(optional) Indicates whether the widget is using the global mode.
[props.animation]
bool
true
(optional) Indicates whether the widget update is animated or jumps directly to the new state
[props.filterable]
bool
true
(optional) Indicates whether filtering capabilities are enabled or not.
[props.xAxisFormatter]
function
​
(optional) formatterCallback: Function to format X axis values.
[props.formatter]
function
​
(optional) formatterCallback: Function to format tooltip and Y axis values.
[props.onError]
function
​
(optional) errorCallback: Function to handle error messages from the widget.
[props.wrapperProps]
Object
​
Extra props to pass to WrapperWidgetUI​
[props.noDataAlertProps]
Object
{ title: 'No data available', body: 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.' }
(optional) Message (title and body) to show when there is no data available for the widget.
[props.droppingFeaturesAlertProps]
Object
{ body: 'Data for this widget is not available at this zoom level. Zoom in to get data from features in the map.' }
(optional) Extra props to pass to the NoDataAlert component when features have been dropped in the data source
Example:
In this example, the widget would display the number of stores in different ranks, based on their number of sales.
import { HistogramWidget } from "@carto/react-widgets";
  
const customFormatter = (value) => `${value} $`;
  
return (
  <HistogramWidget
    id="storesByNumberOfSales"
    title="Stores by number of sales"
    dataSource="storesSourceId"
    operation={AggregationTypes.COUNT}
    column="salesNumber"
    ticks={[10, 100, 500, 1000]}
    onError={console.error}
  />
);
// bins for the histogram would be <10, 10 to 100, 100 to 500, 500 to 1000 and > 1000
LegendWidget
Renders a <LegendWidget /> component. The widget can display a switch to show or hide a layer and a legend for the layer. The legend representation depends on the legend type. You can check the available LEGEND_TYPES here. The widget accesses the layer information from the store and add the legend for those layers where it has been specified.
Input:
Param
Type
Default
Description
props
Object
​
​
[props.className]
string
​
(optional) Material-UI withStyle class for styling.
[props.customLegendTypes]
Object.<string, function>
​
(optional) Object with custom legend types and the components to be used with these types.
[props.customLayerOptions]
Object.<string, function>
​
(optional) Object with custom layer options and the components to be used with these options.
[props.initialCollapsed]
bool
false
(optional) Indicates whether the widget is initially collapsed or not.
[props.layerOrder]
Array<string>
[]
Array of layer identifiers. Defines the order of layers in the legend.
You can control the legend options through the following properties that must be added to the layerAttributes property for the layer in the store:
Param
Type
Default
Description
title
string
​
Layer title
visible
boolean
true
Indicates whether the layer is visible by default or not.
opacity
Number
1
Initial opacity for the layer.
showOpacityControl
boolean
true
Indicates whether the opacity control is shown or not.
options
Array
​
Array of keys from the customLayerOptions passed to LegendWidget. Indicates which of the customLayerOptions components to render in the legend for this layer
switchable
boolean
true
Indicates whether the layer can be hide/shown
legend
Object
​
Legend properties. Define an empty object legend: {} if you just want layer switching capabilities.
legend.type
string
​
Legend type. Must be one of the types defined in the LEGEND_TYPES enum
legend.attr
string
​
Attribute used for styling the layer
legend.colors
Array or string
​
Array of colors (RGB arrays) or CARTO colors palette (string). Used for LEGEND_TYPES.CATEGORY, LEGEND_TYPES.BINS and LEGEND_TYPES.CONTINUOUS_RAMP

Param	Type	Default	Description
props	`Object`
props.id	`string`		ID for the widget instance.
props.title	`string`		Title to show in the widget header.
props.dataSource	`string`		ID of the data source to get the data from.
props.column	`string`		Name of the data source’s column to get the data from.
props.operation	`string`		Operation to apply to the operationColumn. Must be one of those defined in `AggregationTypes` object.
[props.operationColumn]	`string \| Array<string>`		(optional) Name of the data source’s column to operate with. If not defined, same as `column`. If multiple columns are provided, they will be combined using the operation specified with the `joinOperation` property. Note: support for multiple columns is only available beginning with v1.3
[props.joinOperation]	`string`		Operation applied to aggregate multiple operation columns into a single one. Must be one of those defined in `AggregationTypes` object. Note: this property is only available beginning with v1.3
[props.global]	`bool`	`false`	(optional) Indicates whether the widget is using the global mode.
[props.animation]	`bool`	`true`	(optional) Indicates whether the widget update is animated or jumps directly to the new state.
[props.formatter]	`function`		(optional) formatterCallback: Function to format each value returned.
[props.labels]	`Object`	`{}`	(optional) Overwrite category labels.
[props.filterable]	`bool`	`true`	(optional) Indicates whether filtering capabilities are enabled or not.
[props.onError]	`function`		(optional) errorCallback: Function to handle error messages from the widget.
[props.wrapperProps]	`Object`		(optional) Extra props to pass to WrapperWidgetUI
[props.noDataAlertProps]	`Object`	`{ title: 'No data available', body: 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.' }`	(optional) Message (title and body) to show when there is no data available for the widget.
[props.droppingFeaturesAlertProps]	`Object`	`{ body: 'Data for this widget is not available at this zoom level. Zoom in to get data from features in the map.' }`	(optional) Extra props to pass to the `NoDataAlert` component when features have been dropped in the data source

Param	Type	Default	Description
props	`Object`
[props.className]	`string`		(optional) Material-UI withStyle class for styling
[props.selectionModes]	`Array<FEATURE_SELECTION_MODES>`	`[FEATURE_SELECTION_MODES.CIRCLE, FEATURE_SELECTION_MODES.LASSO_TOOL, FEATURE_SELECTION_MODES.POLYGON, FEATURE_SELECTION_MODES.RECTANGLE]`	Available selection modes.
[props.editModes]	`EDIT_MODES`	`[EDIT_MODES.EDIT]`	Available edit modes.
[props.tooltipPlacement]	`string`	`'bottom'`	Tooltip placement. Allowed values available here

Param	Type	Default	Description
props	`Object`
[props.eventManager]	`EventManager`	nebula.gl event manager	(optional) This prop allows using a different event manager instead of the one provided by nebula.gl. It is used for integration with other mapping libraries like Google Maps JavaScript API.
[props.mask]	`bool`	`true`	Indicates whether to apply a mask or not to hide the features outside the shape drawn by the user.

Param	Type	Default	Description
title	`string`		Layer title
visible	`boolean`	`true`	Indicates whether the layer is visible by default or not.
opacity	`Number`	`1`	Initial opacity for the layer.
showOpacityControl	`boolean`	`true`	Indicates whether the opacity control is shown or not.
options	`Array`		Array of keys from the `customLayerOptions` passed to `LegendWidget`. Indicates which of the `customLayerOptions` components to render in the legend for this layer
switchable	`boolean`	`true`	Indicates whether the layer can be hide/shown
legend	`Object`		Legend properties. Define an empty object `legend: {}` if you just want layer switching capabilities.
legend.type	`string`		Legend type. Must be one of the types defined in the LEGEND_TYPES enum
legend.attr	`string`		Attribute used for styling the layer
legend.colors	`Array` or `string`		Array of colors (RGB arrays) or CARTO colors palette (string). Used for `LEGEND_TYPES.CATEGORY`, `LEGEND_TYPES.BINS` and `LEGEND_TYPES.CONTINUOUS_RAMP`