CARTO for React

CARTO for React

Redux

Package Version Downloads
@carto/react-redux version downloads

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 skeleton template 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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.
  • Example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    
    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",
    };
    
    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:

    1
    2
    3
    4
    
    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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    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:

    1
    2
    3
    4
    5
    6
    7
    8
    
    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:

    1
    2
    
    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:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    
    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:

    1
    2
    3
    4
    5
    
    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]}
props.id string sourceId of the source to apply the filter on
props.column string column from the source to use by the filter
props.type FilterType ‘in’ or ‘between’
props.values array Values for the filter (eg: [‘a’, ‘b’] for ‘in’ or [10, 20] for ‘between’)
[props.owner] FilterType (optional) id of the widget triggering the filter (to be excluded)
  • 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.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    
    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)

    1
    2
    3
    4
    5
    6
    7
    8
    
    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’

    1
    2
    3
    4
    5
    
    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:

    1
    2
    3
    4
    5
    6
    
    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

    1
    2
    3
    4
    5
    6
    7
    
    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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
  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:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    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:

    1
    2
    3
    4
    
    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:

    1
    2
    3
    4
    
    import { useSelector } from "react-redux";
    import { selectOAuthCredentials } from "@carto/react-redux";
    
    const oauthCredentials = useSelector(selectOAuthCredentials);