# Upgrade Guide

[View on Github](https://github.com/CartoDB/carto-react-template)

{% hint style="warning" %}
**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](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), which allows for maximum flexibility and scalability.
{% endhint %}

## Upgrade packages <a href="#upgrading-from-v12-to-v13" id="upgrading-from-v12-to-v13"></a>

YARN:

```sh
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 <a href="#upgrading-from-v2.1-to-v2.2" id="upgrading-from-v2.1-to-v2.2"></a>

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 <a href="#upgrading-from-v2.1-to-v2.2" id="upgrading-from-v2.1-to-v2.2"></a>

`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 <a href="#upgrading-from-v2.0-to-v2.1" id="upgrading-from-v2.0-to-v2.1"></a>

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 <a href="#upgrading-from-v1.5-to-v2.0" id="upgrading-from-v1.5-to-v2.0"></a>

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

For the Material UI migration there is a very detailed guide in the official [Documentation](https://mui.com/material-ui/migration/migration-v4/), 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.

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 <a href="#upgrading-from-v1.5-to-v1.6" id="upgrading-from-v1.5-to-v1.6"></a>

Both `geoColumn` 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 <a href="#upgrading-from-v1.4-to-v1.5" id="upgrading-from-v1.4-to-v1.5"></a>

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 <a href="#upgrading-from-v1.3-to-v1.4" id="upgrading-from-v1.3-to-v1.4"></a>

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

## Upgrading from v1.2 to v1.3 <a href="#upgrading-from-v1.2-to-v1.3" id="upgrading-from-v1.2-to-v1.3"></a>

### **External Library Changes**

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 [here](https://docs.carto.com/development-tools/carto-for-react/guides/data-sources#dropping-features).

### **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 <a href="#upgrading-from-v1.1-to-v1.2" id="upgrading-from-v1.1-to-v1.2"></a>

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 <a href="#upgrading-from-v1.0-to-v1.1" id="upgrading-from-v1.0-to-v1.1"></a>

CARTO for React v1.1 includes support for deck.gl 8.6 that provides data visualization capabilities for the new [CARTO 3 platform](https://docs.carto.com/development-tools/carto-for-react/guides/upgrade-guide). Read more about the capabilities in this new deck.gl version [here](https://docs.carto.com/development-tools/carto-for-deck.gl).

### **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):

* [useCartoLayerProps](https://docs.carto.com/development-tools/carto-for-react/library-reference/api#usecartolayerprops) now uses object destructuring instead of multiple arguments
* [executeSQL](https://docs.carto.com/development-tools/carto-for-react/library-reference/api#executesql) now uses object destructuring instead of multiple arguments
* `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

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

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

  ```shell
  $ 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`

  ```shell
  $ 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

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

### **Compatibility with platform versions**

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 [this page](https://carto.com/carto3/).