CARTO for React

CARTO for React

Build compelling spatial apps using CARTO, React and deck.gl.

Github Code

Widgets

Package Version Downloads
@carto/react-widgets version downloads

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.

Tip: To review interactively the widgets, check the Storybook catalogue

Components

CategoryWidget

Renders a <CategoryWidget /> component, binded to a source at redux. The widget displays the calculations considering just the viewport features.

  • Input:

    Param Type Default Description
    props
    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 (optional) Name of the data source’s column to operate with. If not defined, same as column.
    [props.formatter] function (optional) formatterCallback: Function to format each value returned.
    [props.labels] Object {} (optional) Overwrite category labels.
    [props.onError] function (optional) errorCallback: Function to handle error messages from the widget.
    [props.wrapperProps] Object (optional) Extra props to pass to WrapperWidgetUI

  • Example:

    In this example, the widget would display the SUM of population for all the countries, grouped by continent

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

    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

FormulaWidget

Renders a <FormulaWidget /> component, binded to a source at redux. The widget displays the calculations considering just the viewport features.

  • Input:

    Param Type Default Description
    props
    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.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

  • Example:

    In this example, the widget would display the AVG sales for all the stores on screen

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

    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}
  />
);

GeocoderWidget

Renders a <GeocoderWidget /> component

  • Input:
    Param Type Description
    props
    props.id string ID for the widget instance.
    [props.className] Object (optional) Material-UI withStyle class for styling
    [props.onError] function (optional) errorCallback: Function to handle error messages from the widget.

HistogramWidget

Renders a <HistogramWidget /> component, binded to a source at redux. The widget displays the calculations considering just the viewport features.

  • Input:

    Param Type Default Description
    props
    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.ticks Array.<number> Array of numbers to build intervals (eg 1, 5, 10 will define 4 intervals: <1, 1 to 5, 5 to 10 and >10)
    [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

  • Example:

    In this example, the widget would display the number of stores in different ranks, based on their number of sales

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

    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

PieWidget

Renders a <PieWidget /> component, binded to a source at redux. The widget displays the calculations considering just the viewport features. From a data perspective, PieWidget would present a behaviour equivalent to CategoryWidget (groups or ‘categories’ from a column, with an aggregated calculation), but with a different UI.

  • Input:
    Param Type Default Description
    props
    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.height string 300px Height of the chart in CSS format.
    [props.operationColumn] string Name of the data source’s column to operate with. If not defined it will default to the one defined in column.
    [props.formatter] function (optional) formatterCallback: Function to format each value returned.
    [props.tooltipFormatter] formatterCallback (optional) formatterCallback: Function to return the HTML of the tooltip.
    [props.onError] errorCallback (optional) errorCallback: Function to handle error messages from the widget.
    [props.wrapperProps] Object (optional) Extra props to pass to WrapperWidgetUI