CARTO for React

CARTO for React

Github Code

API

Package Version Downloads
@carto/react-api version downloads

Set of functions that allow to work with CARTO APIs.

Functions

executeSQL

Async function that executes a SQL query against CARTO SQL API

  • Input:
Param Type Description
credentials Object CARTO user credentials
credentials.username string CARTO username
credentials.apiKey string CARTO API Key
query string SQL query to be executed
opts Object Optional. Additional options for the HTTP request, following the Request interface
opts.abortController AbortController To cancel the network request using AbortController
opts.format string Output format to be passed to SQL API (i.e. ‘geojson’)

  • Returns: Object - Data returned from the SQL query execution

  • Example:

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

    import { executeSQL } from "@carto/react-api";

const credentials = {
  username: "public",
  apiKey: "default_public"
};
const query = `SELECT COUNT(cartodb_id) FROM populated_places`;

const fetchData = async () => {
  const result = await executeSQL(credentials, query);
  return result;
};

const rows = await fetchData();
console.log(rows[0]); // {count: 7343}

useCartoLayerProps

React hook that allows a more powerful use of CARTO deck.gl layers, creating a set of layer props (see @deck.gl/carto module). It manages automatically filtering and viewport-related calculations, for common use cases.

  • Input:
Param Type Description
source Object Required source. { id, type, data }
[uniqueIdProperty] string (optional) Name of the column for identity. To be used internally when getting viewportFeatures (used by widget computations)

Tip: About uniqueIdProperty: the uniqueIdProperty allows to identify a feature unequivocally. When using tiles, it allows to detect portions of a same feature present in different tiles (think about a road segment crossing 2 tiles) and apply correct calculations (eg. avoid counting the same feature more than once). These are the rules used internally, in this precise order:

  1. if user indicates a particular property, it will be honoured.
  2. if cartodb_id is present, it will be used (all features coming from a CartoSQLLayer have this field, just be sure to include it in the SQL you use)
  3. if geoid is present, it will be used. Some datasets used inside CartoBQTilerLayer have this identifier.
  4. finally, if a value isn’t set for this param and none cartodb_id or geoid are found, every feature (or portion of a feature), will be treated as a unique feature.
  • Returns: a set of props for the layer.
Param Type Description
props Object Default props required for layers
props.binary boolean Returns true. The internal viewportFeatures calculation requires MVT property set to true
props.uniqueIdProperty string Returns same unique id property for the layer as the input one
props.onViewportLoad function Function that is called when all tiles in the current viewport are loaded
props.getFilterValue function Accessor to the filterable value of each data object
props.filterRange [number, number] The [min, max] bounds of the filter values to display
props.extensions [Object] Bonus features to add to the core deck.gl layers
props.updateTriggers Object Tells deck.gl exactly which attributes need to change, and when
props.updateTriggers.getFilterValue Object Updating getFilterValue accessor when new filters are applied to source

  • Example:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

    import { useCartoLayerProps } from '@carto/react-api';

const cartoLayerProps = useCartoLayerProps(source);

const layer = new CartoSQLLayer({
  id: 'exampleLayer',
  data: source.data,
  credentials: source.credentials,
  getFillColor: [255, 0, 255],
  ...cartoLayerProps,
}

    Tip: if you’re using CARTO for React templates, you would usually get the source from Redux. It is recommended to use the hook as the latest prop; and you might need to apply destructuring on its properties for more advanced use cases.

Constants & enums

SourceTypes

Enum for the different types of @deck.gl/carto sources. If you create a source with hygen, it will manage the type for you.

  • Options:

    • SQL
    • BIGQUERY

  • Example:

    1
2
3

    import { SourceTypes } from "@carto/react-api";

console.log(SourceTypes.SQL); // 'sql'