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
  • Upgrade packages
  • Upgrading from v2.2 to v2.3
  • Upgrading from v2.1 to v2.2
  • Upgrading from v2.0 to v2.1
  • Upgrading from v1.5 to v2.0
  • Upgrading from v1.5 to v1.6
  • Upgrading from v1.4 to v1.5
  • Upgrading from v1.3 to v1.4
  • Upgrading from v1.2 to v1.3
  • External Library Changes
  • Library Changes
  • Upgrading from v1.1 to v1.2
  • Upgrading from v1.0 to v1.1
  • Library changes
  • Template changes
  • Compatibility with platform versions

Was this helpful?

Export as PDF
  1. CARTO for Developers
  2. CARTO for React
  3. Guides

Upgrade Guide

PreviousDeploymentNextExamples

Last updated 11 months ago

Was this helpful?

Upgrade packages

YARN:

yarn upgrade @carto/react-api \
    @carto/react-basemaps  \
    @carto/react-core \
    @carto/react-redux \
    @carto/react-ui \
    @carto/react-widgets \
    @carto/react-workers

NPM:

npm upgrade @carto/react-api \
    @carto/react-basemaps  \
    @carto/react-core \
    @carto/react-redux \
    @carto/react-ui \
    @carto/react-widgets \
    @carto/react-workers

Upgrading from v2.2 to v2.3

Version 2.3 includes localization of messages and this is a breaking change. Clients updating to version 2.3 without making the necessary changes will get an error such as:

[React Intl] Could not find required `intl` object. <IntlProvider> needs to exist in the component ancestry.

To fix it:

  1. Add new dependencies: yarn add react-intl @formatjs/intl-localematcher

  2. Add provider to your app root level. The only supported locales are 'en' or 'es'

    import { IntlProvider } from 'react-intl';
    
    // ... your code
    
        <IntlProvider locale='en'>
          <StyledEngineProvider injectFirst>
            <ThemeProvider theme={theme}>
              <CssBaseline />
              <GridApp container>
                <LazyLoadRoute>{routing}</LazyLoadRoute>
              </GridApp>
            </ThemeProvider>
          </StyledEngineProvider>
        </IntlProvider>
    
    ```

Upgrading from v2.1 to v2.2

SelectField props removal: items no longer available, use children instead.

Changed to a controlled component. So now it needs to handle onChange function in the parent.

For multiple selection functionality, now use MultipleSelectField instead.

Upgrading from v2.0 to v2.1

The geoColumn and aggregationExp are moved from CartoLayer to Source.

The new API is backward compatibe for rendering purposes, but improved widgets calculation needs the two parameters in Source.

If the parameters are present in a layer and widgets are defined over the same data source, it's important that the parameters are moved to the data source definition used in both the layer and the widgets.

className and sx props removed from: Legend, Geocoder, Category and FeatureSelection widgets. Use styled API instead to wrap the affected widget in a container and apply the styles there.

Upgrading from v1.5 to v2.0

There is a breaking change regarding both the underlying UI library (major upgrade from Material-UI 4 to MUI5) and the visual aspect of the components (a new & improved Design System, with new palette of colors & fonts).

On the React side, current 2.0 is compatible with React 17, as it still uses some makeStyles calls (API based on JSS). A migration process has already started, to dump that API, in favor of more modern and recommended options, like the styled & sx apis. Once that process is done, React 18 will be compatible.

Upgrading from v1.5 to v1.6

Both and aggregationExp have transitioned from CartoLayer to Source.

While the updated API maintains backward compatibility for rendering, enhanced widget calculations require these parameters to be in the Source.

For layers with these parameters and widgets using the same data source, ensure the parameters are relocated to the data source definition employed in both the layer and widgets.

Upgrading from v1.4 to v1.5

There are no major changes in v1.2 that should affect your applications when upgrading from v1.4 to v1.5

Upgrading from v1.3 to v1.4

It requires bumping deck.gl to >=8.8.15 + new dependency: 'quadbin' >= 0.1.5

Upgrading from v1.2 to v1.3

External Library Changes

Library Changes

We have updated the HistogramWidget and now it can work in two different modes: you can keep using the ticks property to specify the breaks for the bins, or you can use the new bins property where you just specify the number of bins to use and the widget is going to calculate the breaks.

Sometimes the HistogramWidget was used with categorical data but it should be use to show the distribution of a numeric column. We have created a new BarWidget that should be used when we want to visualize categorical data using vertical bars.

Upgrading from v1.1 to v1.2

There are no major changes in v1.2 that should affect your applications when upgrading from v1.1.

Upgrading from v1.0 to v1.1

Library changes

If you update an application that is using v1.0 of the CARTO for React library to v1.1, there are some minor changes that might affect your existing code (we have already updated our documentation with these changes):

  • SourceTypes constants have been removed from the @carto/react-api package

  • The type property in data sources now accepts a different set of values. You need to use MAP_TYPES.QUERY if you were using 'sql' or MAP_TYPES.TILESET if you were using 'bigquery'. The MAP_TYPES constants are defined in the @deck.gl/carto package.

Template changes

In this new version 1.1, we have also renamed our existing templates and added three new templates for creating applications with the CARTO 3 platform:

  • base-2 is the new name for the existing CARTO 2 skeleton template, previously the default @carto template

    $ yarn create react-app my-app --template @carto/base-2
  • base-3 is the name for the new CARTO 3 template

    $ yarn create react-app my-app --template @carto/base-3
  • base-3-typescript is the name for the new CARTO 3 template for TypeScript

    $ yarn create react-app my-app --template @carto/base-3-typescript
  • sample-app-2 is the new name for the existing sample app template for CARTO 2, previously named sample-app

    $ yarn create react-app my-app --template @carto/sample-app-2
  • sample-app-3 is the name for the new sample app template for CARTO 3

    $ yarn create react-app my-app --template @carto/sample-app-3

Compatibility with platform versions

For the Material UI migration there is a very detailed guide in the official , that should help to achieve a smooth migration. Regarding the second, some visual tweaks might be needed to fit into already existing apps, especially if those were using some type of theme customization.

The main change that can have an impact when upgrading is the update of deck.gl to v8.8. In this new version of deck.gl, the CartoLayer only works with vector tiles and this change can affect to widgets. If we are using dynamic tiling and there are features dropped in the current zoom level, the widgets are not going to show results but a message indicating that not all the data is available. If you need the widgets to work at all zoom levels and the data source is of small/medium size, you can keep using GeoJSON but directly with the GeoJsonLayer as explained .

CARTO for React v1.1 includes support for deck.gl 8.6 that provides data visualization capabilities for the new . Read more about the capabilities in this new deck.gl version .

now uses object destructuring instead of multiple arguments

now uses object destructuring instead of multiple arguments

CARTO for React v1.1 is the first version compatible with the CARTO 3 platform. CARTO 3 is the new version of the CARTO platform that provides direct connectivity to cloud data warehouses without the need for importing data first into CARTO. If you want to learn more about this new version and sign-up for a free trial, please go to .

View on Github
Documentation
here
CARTO 3 platform
here
useCartoLayerProps
executeSQL
this page