LogoLogo
HomeAcademyLoginTry for free
  • Welcome
  • What's new
    • Q2 2025
    • Q1 2025
    • Q4 2024
    • Q3 2024
    • Q2 2024
    • Q1 2024
    • Q4 2023
    • Q3 2023
    • Q2 2023
    • Q1 2023
    • Q4 2022
    • Q3 2022
  • FAQs
    • Accounts
    • Migration to the new platform
    • User & organization setup
    • General
    • Builder
    • Workflows
    • Data Observatory
    • Analytics Toolbox
    • Development Tools
    • Deployment Options
    • CARTO Basemaps
    • CARTO for Education
    • Support Packages
    • Security and Compliance
  • Getting started
    • What is CARTO?
    • Quickstart guides
      • Connecting to your data
      • Creating your first map
      • Creating your first workflow
      • Developing your first application
    • CARTO Academy
  • CARTO User Manual
    • Overview
      • Creating your CARTO organization
      • CARTO Cloud Regions
      • CARTO Workspace overview
    • Maps
      • Data sources
        • Simple features
        • Spatial Indexes
        • Pre-generated tilesets
        • Rasters
        • Defining source spatial data
        • Managing data freshness
        • Changing data source location
      • Layers
        • Point
          • Grid point aggregation
          • H3 point aggregation
          • Heatmap point aggregation
          • Cluster point aggregation
        • Polygon
        • Line
        • Grid
        • H3
        • Raster
        • Zoom to layer
      • Widgets
        • Formula widget
        • Category widget
        • Pie widget
        • Histogram widget
        • Range widget
        • Time Series widget
        • Table widget
      • SQL Parameters
        • Date parameter
        • Text parameter
        • Numeric parameter
        • Publishing SQL parameters
      • Interactions
      • Legend
      • Basemaps
        • Basemap selector
      • AI Agents
      • SQL analyses
      • Map view modes
      • Map description
      • Feature selection tool
      • Search locations
      • Measure distances
      • Exporting data
      • Download PDF reports
      • Managing maps
      • Sharing and collaboration
        • Editor collaboration
        • Map preview for editors
        • Map settings for viewers
        • Comments
        • Embedding maps
        • URL parameters
      • Performance considerations
    • Workflows
      • Workflow canvas
      • Results panel
      • Components
        • Aggregation
        • Custom
        • Data Enrichment
        • Data Preparation
        • Generative AI
        • Input / Output
        • Joins
        • Parsers
        • Raster Operations
        • Spatial Accessors
        • Spatial Analysis
        • Spatial Constructors
        • Spatial Indexes
        • Spatial Operations
        • Statistics
        • Tileset Creation
        • BigQuery ML
        • Snowflake ML
        • Google Earth Engine
        • Google Environment APIs
        • Telco Signal Propagation Models
      • Data Sources
      • Scheduling workflows
      • Sharing workflows
      • Using variables in workflows
      • Executing workflows via API
      • Temporary data in Workflows
      • Extension Packages
      • Managing workflows
      • Workflows best practices
    • Data Explorer
      • Creating a map from your data
      • Importing data
        • Importing rasters
      • Geocoding data
      • Optimizing your data
    • Data Observatory
      • Terminology
      • Browsing the Spatial Data Catalog
      • Subscribing to public and premium datasets
      • Accessing free data samples
      • Managing your subscriptions
      • Accessing your subscriptions from your data warehouse
        • Access data in BigQuery
        • Access data in Snowflake
        • Access data in Databricks
        • Access data in Redshift
        • Access data in PostgreSQL
    • Connections
      • Google BigQuery
      • Snowflake
      • Databricks
      • Amazon Redshift
      • PostgreSQL
      • CARTO Data Warehouse
      • Sharing connections
      • Deleting a connection
      • Required permissions
      • IP whitelisting
      • Customer data responsibilities
    • Applications
    • Settings
      • Understanding your organization quotas
      • Activity Data
        • Activity Data Reference
        • Activity Data Examples
        • Activity Data Changelog
      • Users and Groups
        • Inviting users to your organization
        • Managing user roles
        • Deleting users
        • SSO
        • Groups
        • Mapping groups to user roles
      • CARTO Support Access
      • Customizations
        • Customizing appearance and branding
        • Configuring custom color palettes
        • Configuring your organization basemaps
        • Enabling AI Agents
      • Advanced Settings
        • Managing applications
        • Configuring S3 Bucket for Redshift Imports
        • Configuring OAuth connections to Snowflake
        • Configuring OAuth U2M connections to Databricks
        • Configuring S3 Bucket integration for RDS for PostgreSQL Exports in Builder
        • Configuring Workload Identity Federation for BigQuery
      • Data Observatory
      • Deleting your organization
    • Developers
      • Managing Credentials
        • API Base URL
        • API Access Tokens
        • SPA OAuth Clients
        • M2M OAuth Clients
      • Named Sources
  • Data and Analysis
    • Analytics Toolbox Overview
    • Analytics Toolbox for BigQuery
      • Getting access
        • Projects maintained by CARTO in different BigQuery regions
        • Manual installation in your own project
        • Installation in a Google Cloud VPC
        • Core module
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • cpg
        • data
        • http_request
        • import
        • geohash
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • routing
        • s2
        • statistics
        • telco
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release notes
      • About Analytics Toolbox regions
    • Analytics Toolbox for Snowflake
      • Getting access
        • Native App from Snowflake's Marketplace
        • Manual installation
      • Key concepts
        • Spatial indexes
        • Tilesets
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • data
        • http_request
        • import
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release Notes
    • Analytics Toolbox for Databricks
      • Getting access
        • Personal (former Single User) cluster
        • Standard (former Shared) cluster
      • Reference
        • lds
        • tiler
      • Guides
      • Release Notes
    • Analytics Toolbox for Redshift
      • Getting access
        • Manual installation in your database
        • Installation in an Amazon Web Services VPC
        • Core version
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • clustering
        • constructors
        • data
        • http_request
        • import
        • lds
        • placekey
        • processing
        • quadbin
        • random
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
      • Release Notes
    • Analytics Toolbox for PostgreSQL
      • Getting access
        • Manual installation
        • Core version
      • Key concepts
        • Tilesets
        • Spatial Indexes
      • SQL Reference
        • h3
        • quadbin
        • tiler
      • Guides
        • Creating spatial index tilesets
        • Running queries from Builder
      • Release Notes
    • CARTO + Python
      • Installation
      • Authentication Methods
      • Visualizing Data
      • Working with Data
        • How to work with your data in the CARTO Data Warehouse
        • How to access your Data Observatory subscriptions
        • How to access CARTO's Analytics Toolbox for BigQuery and create visualizations via Python notebooks
        • How to access CARTO’s Analytics Toolbox for Snowflake and create visualizations via Python notebooks
        • How to visualize data from Databricks
      • Reference
    • CARTO QGIS Plugin
  • CARTO for Developers
    • Overview
    • Key concepts
      • Architecture
      • Libraries and APIs
      • Authentication methods
        • API Access Tokens
        • OAuth Access Tokens
        • OAuth Clients
      • Connections
      • Data sources
      • Visualization with deck.gl
        • Basemaps
          • CARTO Basemap
          • Google Maps
            • Examples
              • Gallery
              • Getting Started
              • Basic Examples
                • Hello World
                • BigQuery Tileset Layer
                • Data Observatory Tileset Layer
              • Advanced Examples
                • Arc Layer
                • Extrusion
                • Trips Layer
            • What's New
          • Amazon Location
            • Examples
              • Hello World
              • CartoLayer
            • What's New
        • Rapid Map Prototyping
      • Charts and widgets
      • Filtering and interactivity
      • Summary
    • Quickstart
      • Make your first API call
      • Visualize your first dataset
      • Create your first widget
    • Guides
      • Build a public application
      • Build a private application
      • Build a private application using SSO
      • Visualize massive datasets
      • Integrate CARTO in your existing application
      • Use Boundaries in your application
      • Avoid exposing SQL queries with Named Sources
      • Managing cache in your CARTO applications
    • Reference
      • Deck (@deck.gl reference)
      • Data Sources
        • vectorTableSource
        • vectorQuerySource
        • vectorTilesetSource
        • h3TableSource
        • h3QuerySource
        • h3TilesetSource
        • quadbinTableSource
        • quadbinQuerySource
        • quadbinTilesetSource
        • rasterSource
        • boundaryTableSource
        • boundaryQuerySource
      • Layers (@deck.gl/carto)
      • Widgets
        • Data Sources
        • Server-side vs. client-side
        • Models
          • getFormula
          • getCategories
          • getHistogram
          • getRange
          • getScatter
          • getTimeSeries
          • getTable
      • Filters
        • Column filters
        • Spatial filters
      • CARTO APIs Reference
    • Release Notes
    • Examples
    • CARTO for React
      • Guides
        • Getting Started
        • Views
        • Data Sources
        • Layers
        • Widgets
        • Authentication and Authorization
        • Basemaps
        • Look and Feel
        • Query Parameters
        • Code Generator
        • Sample Applications
        • Deployment
        • Upgrade Guide
      • Examples
      • Library Reference
        • Introduction
        • API
        • Auth
        • Basemaps
        • Core
        • Redux
        • UI
        • Widgets
      • Release Notes
  • CARTO Self-Hosted
    • Overview
    • Key concepts
      • Architecture
      • Deployment requirements
    • Quickstarts
      • Single VM deployment (Kots)
      • Orchestrated container deployment (Kots)
      • Advanced Orchestrated container deployment (Helm)
    • Guides
      • Guides (Kots)
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Use Workload Identity in GCP
        • High availability configuration for CARTO Self-hosted
        • Configure your custom service account
      • Guides (Helm)
        • Configure your own buckets (Helm)
        • Configure an external in-memory cache (Helm)
        • Enable Google Basemaps (Helm)
        • Enable the CARTO Data Warehouse (Helm)
        • Configure an external proxy (Helm)
        • Enable BigQuery OAuth connections (Helm)
        • Configure Single Sign-On (SSO) (Helm)
        • Use Workload Identity in GCP (Helm)
        • Use EKS Pod Identity in AWS (Helm)
        • Enable Redshift imports (Helm)
        • Migrating CARTO Self-hosted installation to an external database (Helm)
        • Advanced customizations (Helm)
        • Configure your custom service account (Helm)
    • Maintenance
      • Maintenance (Kots)
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
        • Change the Admin Console password
      • Maintenance (Helm)
        • Monitoring (Helm)
        • Rotating keys (Helm)
        • Uninstall (Helm)
        • Backups (Helm)
        • Updates (Helm)
    • Support
      • Get debug information for Support (Kots)
      • Get debug information for Support (Helm)
    • CARTO Self-hosted Legacy
      • Key concepts
        • Architecture
        • Deployment requirements
      • Quickstarts
        • Single VM deployment (docker-compose)
      • Guides
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Enable Redshift imports
        • Configure your custom service account
        • Advanced customizations
        • Migrating CARTO Self-Hosted installation to an external database
      • Maintenance
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
      • Support
    • Release Notes
  • CARTO Native App for Snowflake Containers
    • Deploying CARTO using Snowflake Container Services
  • Get Help
    • Legal & Compliance
    • Previous libraries and components
    • Migrating your content to the new CARTO platform
Powered by GitBook
On this page
  • CARTO Slice
  • createCartoSlice
  • addSource
  • removeSource
  • addLayer
  • updateLayer
  • removeLayer
  • setCredentials
  • setBasemap
  • addFilter
  • removeFilter
  • clearFilters
  • selectSourceById
  • setViewState
  • setWidgetLoadingState
  • removeWidgetLoadingState
  • setAllWidgetsLoadingStates
  • OAuth Slice
  • createOauthCartoSlice
  • setTokenAndUserInfoAsync
  • logout
  • selectOAuthCredentials

Was this helpful?

Export as PDF
  1. CARTO for Developers
  2. CARTO for React
  3. Library Reference

Redux

PreviousCoreNextUI

Last updated 11 months ago

Was this helpful?

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

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

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

Source type. Check available types

CARTO platform credentials. Check the parameters

View on Github
slice
slice
here
here
version
downloads