CARTO for React

CARTO for React

Redux

Package Version Downloads
@carto/react-redux version downloads

Functions to ease the management of CARTO within a react-redux application. 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 achitecture.

  • 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 }
props.id string unique id for the source
props.data string data definition for the source. Either a Query for SQL dataset or the name of the tileset for BigQuery Tileset
props.type string type of source. Posible values are ‘sql’ or ‘bigquery’
  • Example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    
    import { addSource } from "@carto/react-redux";
    
    const source = {
      id: "sourceOne",
      type: "sql",
      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.

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

setBasemap

Action to set a basemap. To see available maps, check the reference for @carto/react-basemaps. If you use a googlemaps 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({ id: "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 CARTO platform.

  • 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);