Core

View on Github

Note: We are reducing our investment in CARTO for React and currently we discourage users from starting new projects with it.

CARTO for React is an opinionated framework with pre-built components and templates. This greatly speeds up the process to create React-based applications, but customization options are limited.

If you need further customization in React, or you want to build geospatial applications using Vue, Angular, or any other Javascript-based framework, we recommend going directly to the main CARTO for Developers documentation, including CARTO + deck.gl, which allows for maximum flexibility and scalability.

Package	Version	Downloads
@carto/react-core

Set of common functions, to be used mostly by other packages. You won’t usually consume this package directly, but when using AggregationTypes for widgets or when creating custom widgets.

Tip: The computations performed internally by widgets use these functions. They can be useful in the context of new custom widgets (for example using a different charting library)

Functions

aggregationFunctions

Contains a set of basic aggregation functions (count, min, max, sum, and average), used automatically for widgets and layers, see AggregationTypes. Functions are applicable to numbers and also objects using a numeric property.

• Input:

Param	Type	Description
values	Array	Array of numbers or objects with a numerical property
[key]	string	(optional). When using objects, name of the property to use for calculations

• Returns: Object - An object with Aggregation functions, which keys are every AggregationTypes values

• Example:

import { aggregationFunctions, AggregationTypes } from "@carto/react-core";

const values = [{ f: 1 }, { f: 2 }, { f: 3 }, { f: 4 }, { f: 5 }];
const avgFn = aggregationFunctions[AggregationTypes.AVG];

console.log(avgFn(values, "f")); // 3

groupValuesByColumn

Makes groups from features based in a column (keysColumn) and applying an operation to the numeric values in a predefined column (valuesColumn).

• Input:

Param	Type	Default	Description
data	Array		Features for calculations (plain objects with properties)
valuesColumn	string		Quantitative column for grouping (the name of a numeric property in the object)
keysColumn	string		Qualitative column for grouping (the name of a string property in the object)
operation	string		Operation for groups calculations, see AggregationTypes

• Returns: Array - Grouped values

• Example:

import { groupValuesByColumn, AggregationTypes } from "@carto/react-core";

const data = [
  { category: "A", population: 100 },
  { category: "A", population: 200 },
  { category: "B", population: 50 },
];

const groups = groupValuesByColumn(data, "population", "category", AggregationTypes.SUM);

console.log(groups); // output: [ { name: 'A', value: 300 }, { name: 'B', value: 50 }]

histogram

Categorizes numeric values as a histogram from a set of features, having the option of just calculating the frequency (with COUNT operation) or an aggregated operation on the features inside the bin (e.g., SUM).

• Input:

Param	Type	Description
features	Array	Features for calculations (plain objects with properties)
columnName	string	Quantitative column for calculations (the name of a number property in the object)
ticks	Array	Array of numbers to build intervals (eg 1, 5, 10 will defines 4 intervals: <1, 1 to 5, 5 to 10 and >10)
operation	string	Operation for groups calculations, see AggregationTypes

• Returns: Array - Histogram data for each bin, derived from ticks

• Example:

import { histogram, AggregationTypes } from "@carto/react-core";

const features = [
  { field: 1 },
  { field: 2 },
  { field: 2 },
  { field: 3 },
  { field: 3 },
  { field: 3 },
  { field: 4 },
  { field: 4 },
  { field: 5 },
];

const ticks = [2, 4, 6];

const h = histogram(features, "field", ticks, AggregationTypes.COUNT);
console.log(h); // [1, 5, 3, 0]
/* 
        histogram results as:
        <2          --> 1 item
        >=2 to <4   --> 5 items
        >=4 to <6   --> 3 items
        >=6         --> 0 items
    */

scatterPlot

Receives an array of features and the properties that will be used for each axis, checks that properties are valid and returns a formatted array.

• Input:

Param	Type	Description
features	Array	Features
xAxisColumn	string	Property containing values for the X axis.
yAxisColumn	string	Property containing values for the Y axis.

• Returns: Array - Formatted array.

• Example:

import { scatterPlot } from "@carto/react-core";

const data = [
  { x: 0 }, // Missing y
  { y: 1 }, // Missing x
  { x: null, y: 1 }, // null x
  { x: 1, y: null }, // null y
  { x: 0, y: 0 }, // zero for both
  { x: 1, y: 2 }, // valid
  {}, // no values for both
  { x: 2, y: 3 } // valid
];
sp = scatterPlot(data, 'x', 'y'));
console.log(sp); // [[0, 0],[1, 2],[2, 3]]; Invalid values are filtered out

Constants & enums

AggregationTypes

Enum for the different types of aggregations, available for widgets.

• Options:

  • COUNT

  • SUM

  • AVG

  • MIN

  • MAX

• Example:

import { AggregationTypes } from "@carto/react-core";

console.log(AggregationTypes.COUNT);