Redux

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-redux

Functions to manage application state using React-Redux and the Redux Toolkit. This package includes 2 slices to manage the main redux blocks of a CARTO for React application. A slice is a way to manage a “portion” or slice of the redux store with a module:

• cartoSlice: to deal with basemap, viewState, sources, layers, and filters on sources.

• oauthSlice: to use an OAuth app.

Tip: The CARTO for React template already makes extensive use of these slices for redux out of the box, to provide several features in an easy way.

CARTO Slice

createCartoSlice

A function that accepts an initialState, setups the state, and creates the reducers that support CARTO for React architecture. In the CARTO 3 templates this slice includes also the OAuth settings; in the CARTO 2 templates there is a separate slice for OAuth settings.

• Input:

Param	Type	Description
initialState	Object	the initial state

An initial state object might look like:

import { POSITRON } from "@carto/react-basemaps";

export const initialState = {
  viewState: {
    latitude: 31.802892,
    longitude: -103.007813,
    zoom: 2,
    pitch: 0,
    bearing: 0,
    dragRotate: false,
  },
  basemap: POSITRON,
  credentials: {
    username: "public",
    apiKey: "default_public",
    serverUrlTemplate: "https://{user}.carto.com",
  },
  googleApiKey: "",
};

addSource

Action to add a source to the store.

• Input:

Param	Type	Description
props	Object	{ id, data, type, credentials, connection }
props.id	string	Unique id for the source
props.data	string	Table name, tileset name or SQL query
props.type	string	Source type. Check available types here
props.credentials	string	Credentials for accessing the source
props.connection	string	Connection name. Used only for CARTO 3.
props.filtersLogicalOperator	FiltersLogicalOperators	Logical operation to use for combining filters. Can take the values FiltersLogicalOperators.AND and FiltersLogicalOperators.OR. Default value is AND. Note: this property is only available beginning with v1.3
[props.queryParameters]	QueryParameters (@deck.gl/carto)	Optional. SQL query parameters

• Example:

import { addSource } from "@carto/react-redux";
import { MAP_TYPES } from '@deck.gl/carto';

const source = {
  id: "sourceOne",
  type: MAP_TYPES.QUERY,
  connection: 'bqconn',
  data: "SELECT * FROM my_table",
  filtersLogicalOperator: FiltersLogicalOperators.OR
};

const action = addSource(source);
// dispatch(action);

removeSource

Action to remove a source from the store

• Input:

Param	Type	Description
sourceId	string	id of the source to remove

• Example:

import { removeSource } from "@carto/react-redux";

const action = removeSource("sourceOne");
// dispatch(action);

addLayer

Action to add a Layer to the store. By default, the layer visible attribute is set to true unless the layerAttributes property overrides the visible property.

Important! This doesn’t imply adding a whole deck.gl layer to the redux store, just a “pointer” to it, by using an id shared with a Layer file + linking it to a source. See code generated by hygen assistants in the create-react-app template projects.

• Input:

Param	Type	Description
props	Object	{ id, source, layerAttributes }
props.id	string	unique id for the layer
props.source	string	id of the source of the layer
[props.layerAttributes]	Object	(optional) custom attributes to pass to the layer

• Example:

const action = addLayer({
  id: "layerOne",
  source: "sourceOne",
  layerAttributes: {
    extraAttribute: 1,
  },
});
// dispatch(action);
// extraAttribute will be available inside the Layer, for custom operations inside it (eg. styling)

updateLayer

Action to update a Layer in the store

• Input:

Param	Type	Description
props	Object	{ id, layerAttributes }
props.id	string	unique id for the CARTO layer already in the store
props.layerAttributes	Object	custom attributes to update in the layer

• Example:

const action = updateLayer({
  id: "layerOne",
  layerAttributes: {
    extraAttribute: 100,
  },
});
// dispatch(action);
// extraAttribute will be updated to the new value

removeLayer

Action to remove a layer from the store

• Input:

Param	Type	Description
id	string	id of the layer to remove

• Example:

const action = removeLayer("layerOne");
// dispatch(action);

setCredentials

Action to set the default credentials parameters to use for requests to the CARTO platform.

• Input:

Param	Type	Description
credentials	Object	CARTO platform credentials. Check the parameters here

• Example:

import { API_VERSIONS } from "@deck.gl/carto";
import { setCredentials } from "@carto/react-redux";

      
const action = setCredentials({ 
  apiBaseUrl: 'https://gcp-us-east1.api.carto.com',
  apiVersion: API_VERSIONS.V3,
  accessToken: 'eyJhb...'
});
// dispatch(action);

setBasemap

Action to set a basemap. To see available maps, check the reference for @carto/react-basemaps. If you use a Google Maps basemap, you would need to manage its api_key properly.

• Input:

Param	Type	Description
basemap	String	the new basemap to add

• Example:

import { DARK_MATTER } from "@carto/react-basemaps";
import { setBasemap } from "@carto/react-redux";

const action = setBasemap(DARK_MATTER);
// dispatch(action);

addFilter

Action to add a filter on a given source by a column. This is done internally (and in a transparent way) by widgets.

• Input:

Param	Type	Description
props	Object	{ id, column, type, values, [owner], [params]}
props.id	string	Identifier of the source to apply the filter on
props.column	string	Column from the source to use by the filter
props.type	FilterType	Type of filter
props.values	array	Values for the filter (eg: [‘a’, ‘b’] for ‘in’ or [10, 20] for ‘between’)
[props.owner]	string	(optional) Identifier of the widget triggering the filter (to be excluded)
[props.params]	object	(optional) Additional filter parameters (depending on filter type)

• Example:

  This would apply a filter equivalent to a ‘WHERE country IN (‘Spain’)’ to the source. It is important to notice that a source can have multiple filters at the same type.

import { addFilter } from "@carto/react-redux";

const action = addFilter({
  id: "sourceOne", // a valid sourceId
  column: "country",
  type: "in",
  values: ["Spain"],
});

// dispatch(action)

removeFilter

Action to remove a column filter from a source.

• Input:

Param	Type	Description
props	Object	{ id, column }
props.id	string	sourceId of the source to remove the filter from
props.column	string	column of the filter to remove

• Example:

  This would remove a filter (the previous example on addFilter)

import { removeFilter } from "@carto/react-redux";

const action = removeFilter({
  id: "sourceOne",
  column: "country",
});

// dispatch(action)

clearFilters

Action to remove all filters from a source.

• Input:

Type	Description
id	sourceId of the source to remove all filters from

• Example:

  This would remove all filters from a source with id ‘sourceOne’

import { clearFilters } from "@carto/react-redux";

const action = clearFilters("sourceOne");

// dispatch(action)

selectSourceById

Redux selector to get a source by ID

• Input:

Param	Type	Description
state	Object	root redux state
sourceId	string	id of the source to recover from redux

• Example:

import { useSelector } from "react-redux";
import { selectSourceById } from "@carto/react-redux";

const source = useSelector((state) => selectSourceById(state, "sourceOne") || {});

// source is now available, for further operations

setViewState

Action to set the current ViewState of the map.

• Input:

Param	Type	Description
viewState	Object	ViewState, as defined by deck.gl

• Example Example to increase the zoom level

import { useSelector } from "react-redux";
import { setViewState } from "@carto/react-redux";

const zoomLevel = useSelector((state) => state.carto.viewState.zoom);
const action = setViewState({ zoom: zoomLevel + 1 });

// dispatch(action)

setWidgetLoadingState

Action to set the loading state to a specific widget. It can be useful when creating custom widgets.

• Input:

Param	Type	Description
props	Object	{ widgetId, isLoading}
props.widgetId	string	id of the widget
props.isLoading	boolean	loading state

removeWidgetLoadingState

Action to remove a specific widget loading state

• Input:

Param	Type	Description
widgetId	string	id of the widget

setAllWidgetsLoadingStates

Action to set the all the widgets loading state at once

• Input:

Param	Type	Description
areLoading	boolean	loading state

OAuth Slice

createOauthCartoSlice

A function that accepts an initialState, setup the state, and creates reducers to manage OAuth with the CARTO 2 platform. This slice is not used with CARTO 3 templates because OAuth is managed through the Auth0 React SDK.

• Input:

Param	Type	Description
initialState	Object	the initial state

An initial state object might look like:

  export const oauthInitialState = {
    oauthApp: {
      clientId: 'YOUR-CARTO-OAUTH-APP-CLIENTID'
      scopes: [
        'user:profile', // to load avatar photo
        'datasets:metadata', // to list all your datasets,
        'dataservices:geocoding', // to use geocoding through Data Services API
        'dataservices:isolines', // to launch isochrones or isodistances through Data Services API
      ],
      authorizeEndPoint: 'https://carto.com/oauth2/authorize',
    }
  };

setTokenAndUserInfoAsync

Action to set the userInfo in the redux store, once there is a valid token (and set them both in state).

• Input:

Param	Type	Description
props	Object	oauthParams, as returned by useOAuthLogin hook ({ accessToken, expirationDate, userInfoUrl})

• Example:

import { setTokenAndUserInfoAsync } from "@carto/react-redux";

// const oauthApp = { whatever your app requires... }

const onParamsRefreshed = (oauthParams) => {
  if (oauthParams.error) {
    console.error(`OAuth error: ${oauthParams.error}`);
  } else {
    const action = setTokenAndUserInfoAsync(oauthParams);
    dispatch(action);
  }
};

const [handleLogin] = useOAuthLogin(oauthApp, onParamsRefreshed);

/* 
    oauthParams look something like:
    { 
      accessToken: "xxxxxxxxx", 
      expirationDate: 1616013732973.8652, 
      userInfoUrl: "https://a-certain-user.carto.com/api/v4/me"
    }
  */

logout

Action to logout, removing user info & token from redux store.

• Example:

import { logout } from "@carto/react-redux";

const action = logout();
// dispatch(action)

selectOAuthCredentials

Selector to fetch the current OAuth credentials from the redux store.

• Returns:

Param	Type	Description
credentials	Object	{ username, apiKey, serverUrlTemplate }
credentials.username	string	CARTO username
credentials.apiKey	string	apiKey coming from OAuth
credentials.serverUrlTemplate	string	required for further api requests

• Example:

import { useSelector } from "react-redux";
import { selectOAuthCredentials } from "@carto/react-redux";

const oauthCredentials = useSelector(selectOAuthCredentials);