CARTO for React

View on Github

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, which allows for maximum flexibility and scalability.

CARTO for React is an application template packed with ready-to-use components to speed up the development of Location Intelligence (LI) Apps using the CARTO platform + React + deck.gl.

To quickly start a project locally, it's enough with:

npx create-react-app my-app --template @carto/base-3

It is based on Create React App, and it will allow you to start with a well designed structure and an integrated toolchain for testing, building, and deploying your application.

The code is open source and is available in the following repositories:

Templates for Create React App: https://github.com/CartoDB/carto-react-template
Library: https://github.com/CartoDB/carto-react

About Carto Platform Versions

In this documentation we use the term “CARTO 3” to refer to the latest version of the CARTO platform launched on October 2021, and “CARTO 2” to refer to the previous version. Note that each platform version has its own set of account credentials.

The latest CARTO for React version is 2.x. This version series is paired with MUI5. Regarding React support, from 2.0.4 both React 18 and React 17 are supported. In version 2.x only templates for CARTO 3 are available. All maintained Node versions are supported.

To work with previous version of Material UI (v4.x) and/or CARTO 2 version, user must use CARTO for React 1.x version series. The last stable release for MUI 4.x is 1.5 and there won't be any more active development on it, therefore migration to v2.x is recommended for all users.

The NPM packages (latest version) are linked below:

Templates:

Lib packages:

Architecture

CARTO for React is based on the following libraries:

CARTO for deck.gl as the library to visualize maps. For the basemaps you can use either Google Maps or CARTO basemaps.
React as the JavaScript library for building user interfaces and Redux for managing global state for the application. We use React-Redux for managing the interactions between the React components with the Redux store.
Material-UI: UI React components for faster and easier web development.
[@carto/react-*]: A set of packages created to make easy integration with CARTO platform and its APIs, geospatial widgets, and a custom theme for Material-UI.

Templates

CARTO for React includes the following Create React App templates for kickstarting your application:

The CARTO 3 template that creates a simple application with just a map using the CARTO 3 platform. This is the template you are usually going to choose when you are creating a new app using JavaScript.
The CARTO 3 template for TypeScript that creates a simple application with just a map using the CARTO 3 platform. This is the template you are usually going to choose when you are creating a new app using TypeScript.
The CARTO 2 template, similar to the CARTO 3 template. You are going to use it when you are creating a new app with the CARTO 2 platform.
The sample app templates for CARTO 2 and CARTO 3 that create a more complex application with several views, layers, and widgets. The purpose of these templates is to demonstrate how you can implement common Location Intelligence functionalities in a CARTO for React app.

The command to create a new application depends on the package manager we are using.

If using npm as the package manager:

npx create-react-app [application_name] --template [template_name]

If using yarn:

yarn create react-app [application_name] --template [template_name]

application_name is the name of the folder that will be created for your application
template_name is the name of the template to use:
- @carto/base-3 for the CARTO 3 template
- @carto/base-3-typescript for the CARTO 3 template for TypeScript
- @carto/sample-app-3 for the sample app template for CARTO 3.
- @carto/base-2 for the CARTO 2 template
- @carto/sample-app-2 for the sample app template for CARTO 2.
As said before, base-2 & sample-app-2 are not supported anymore in CARTO for React 2.x

Library

In addition to the Create React App templates, we have created a library to:

Provide an easy integration with the CARTO platform and its APIs.
Provide a catalog of useful widgets for Location Intelligence Apps.
Create a custom theme for Material-UI to reduce the design work of your team.

There is a full reference available.

The library includes a set of UI components ready to be used to create the best Location Intelligence Apps.

Frequently Asked Questions (FAQ)

I’m using Vue or Angular for building my applications, what are my options?

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, which allows for maximum flexibility and scalability.

When should I use the CARTO 3 platform vs the CARTO 2 platform?

CARTO 3 is the next version of the CARTO Platform. The main difference is that it provides full native support for cloud data warehouses and platforms, pushing down queries. If you are starting a new application, we recommend you to use the latest version of CARTO by requesting access. Or contact us if you have questions.

PreviousExamples NextGuides

Last updated 4 months ago