How to display MapLibre GL JS map using React JS
Deprecated!!!moved to https://docs.maptiler.com/react/maplibre-gl-js/how-to-use-maplibre-gl-js/
In this tutorial, you’ll learn how to create React JS component to render a map using MapLibre GL JS. Together we will make a simple fullscreen map application as an example on how to use MapTiler maps together with React and MapLibre GL JS for your own React app.
By the end of this tutorial, you will be able to create a full-screen map with a marker at a specified location. Your final map will look like this:
Getting started
Minimal requirements for completing this tutorial.
- Basic React JS knowledge. You don’t need a lot of experience using React for this tutorial, but you should be familiar with basic concepts and workflow.
- MapTiler API key. Your MapTiler account access key is on your MapTiler Cloud account page or Get API key for FREE.
- MapLibre GL JS. JavaScript library for building web maps. In this tutorial, you will learn how to install it.
- Node.js and npm. Necessary to run your React app locally. Node.js
Create an app
In this step, we are going to learn how to create a React app.
To create a new react project run in your command-line:
npx create-react-app my-react-map
create-react-app
will create a simple one-page application in React. For more information follow Create React app.
Navigate to the newly created project folder my-react-map
cd my-react-map
Inside the newly created project, you can run npm start
to start your local environment. You will find your app running on address http://localhost:3000/
.
Now you should see the app in your browser.
Installation and setting up
To install MapLibre GL library, navigate to your project folder and run the command:
npm i maplibre-gl
Navigate to the src
folder and replace all the contents of the App.css
file with the following lines:
body {
margin: 0;
padding: 0;
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
code {
font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
monospace;
}
Replace all the contents of the App.js
file with the following lines:
import './App.css';
function App() {
return (
<div className="App">
This is my map App
</div>
);
}
export default App;
Now you should see “This is my map App“ in your browser.
Create a navbar component
In this step, we will create a simple heading navbar component.
Create a new folder called components
inside the src
folder.
Create a new file called navbar.js
inside the components
folder and write these lines:
import React from 'react';
import './navbar.css';
export default function Navbar(){
return (
<div className="heading">
<h1>This is my map App</h1>
</div>
);
}
Create a new file called navbar.css
inside the components
folder and write these lines:
.heading {
margin: 0;
padding: 0px;
background-color: black;
color: white;
text-align: center;
}
.heading > h1 {
padding: 20px;
margin: 0;
}
Finally, to display the Navbar
we need to import the Navbar component and add it to our main component App.js
.
Import the navbar component into App.js
write the following line at the beginning of the file
import Navbar from './components/navbar.js';
Replace the text ‘This is my map App’ with <Navbar />
. Your App.js
file should look like this:
import Navbar from './components/navbar.js';
import './App.css';
function App() {
return (
<div className="App">
<Navbar/>
</div>
);
}
export default App;
Now you should see the black navbar at the top of your browser.
Create a map component
In this step, we will create a simple map component.
Create a new file called map.js
inside the components
folder.
First, we’ll import MapLibre GL and the required React functions. Add these lines on top of map.js
file.
import React, { useRef, useEffect, useState } from 'react';
import maplibregl from 'maplibre-gl';
import './map.css';
Now we will create a function as our map component.
export default function Map(){
}
And set up your map’s default state.
export default function Map(){
const mapContainer = useRef(null);
const map = useRef(null);
const [lng] = useState(139.753);
const [lat] = useState(35.6844);
const [zoom] = useState(14);
const [API_KEY] = useState('YOUR_MAPTILER_API_KEY');
}
The state stores the map object, its container. Longitude, latitude, and zoom for the map will all change as your user interacts with the map.
Here you will need to replace YOUR_MAPTILER_API_KEY
with your actual MapTiler API key.
In the next step, we will initialize the map in the Map()
function.
useEffect(() => {
if (map.current) return; //stops map from intializing more than once
map.current = new maplibregl.Map({
container: mapContainer.current,
style: `https://api.maptiler.com/maps/streets/style.json?key=${API_KEY}`,
center: [lng, lat],
zoom: zoom
});
});
This code will be right after the component is inserted into the DOM tree. We initialize the map using React effect hook and we also set up some basic options of the map:
- The
container
option sets the DOM element in which will the map be rendered. We will assign theref
our component expects to an HTML element, which will act as a container, later in this tutorial. - The
style
option defines what style is the map going to use. - The
center
andzoom
options set the starting position of the map.
Now, we will add the return
statement to your Map()
function. Add the following code to your component above the closing curly brace of Map()
:
return (
<div className="map-wrap">
<div ref={mapContainer} className="map" />
</div>
);
The ref={mapContainer}
specifies that App
should be drawn to the HTML page in the <div>
element.
We are finished with our basic map component, your map.js
file should look like this:
import React, { useRef, useEffect, useState } from 'react';
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import './map.css';
export default function Map(){
const mapContainer = useRef(null);
const map = useRef(null);
const [lng] = useState(139.753);
const [lat] = useState(35.6844);
const [zoom] = useState(14);
const [API_KEY] = useState('YOUR_MAPTILER_API_KEY');
useEffect(() => {
if (map.current) return;
map.current = new maplibregl.Map({
container: mapContainer.current,
style: `https://api.maptiler.com/maps/streets/style.json?key=${API_KEY}`,
center: [lng, lat],
zoom: zoom
});
});
return (
<div className="map-wrap">
<div ref={mapContainer} className="map" />
</div>
);
}
Now we will need simple styling to render the map correctly. Create a file named map.css
in components
folder for the map component style and write the following code to your map.css
file:
.map-wrap {
position: relative;
width: 100%;
height: calc(100vh - 77px); /* calculate height of the screen minus the heading */
}
.map {
position: absolute;
width: 100%;
height: 100%;
}
We use position: absolute
on the map itself and position: relative
on the wrap around the map for more possibilities in future styling.
Render a map
Now we will import the map component into your app, add the following line to the top of the App.js
.
import Map from './components/map.js';
And then, add the imported <Map/>
component in your App()
function. Your App.js
file should then look like this:
import React from 'react';
import Map from './components/map.js';
import Navbar from './components/navbar.js';
import './App.css';
function App() {
return(
<div className="App">
<Navbar/>
<Map/>
</div>
)
}
export default App;
With everything done up until now, you should be able see your beautiful map in your browser.
Basic additional options
The last topic of this tutorial will be adding basic objects to your map. For more detailed information you can visit the MapLibre documentation.
Map Controls
We will navigate back to our map.js
file and add map navigation controls to our map.
On line 21 (just after the initialization of the map) of the map.js
file add the following line:
map.current.addControl(new maplibregl.NavigationControl(), 'top-right');
new maplibregl.NavigationControl()
will create new controls object which we add to current map using the addControl()
function in the 'top-right'
position.
Map marker
Another basic thing to add to your map could be a marker of some location.
In the next line where we declare the navigation control we add these lines:
new maplibregl.Marker({color: "#FF0000"})
.setLngLat([139.7525,35.6846])
.addTo(map.current);
We create a new marker using the .marker
function. We added the color option to make it red, then set Lng/Lat of the marker using .setLngLat()
function , and finally added it to the current map using .addTo()
function.
We are finished with our basic map objects, your map.js
file should look like this:
import React, { useRef, useEffect, useState } from 'react';
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import './map.css';
export default function Map(){
const mapContainer = useRef(null);
const map = useRef(null);
const [lng] = useState(139.753);
const [lat] = useState(35.6844);
const [zoom] = useState(14);
const [API_KEY] = useState('YOUR_MAPTILER_API_KEY');
useEffect(() => {
if (map.current) return; //stops map from intializing more than once
map.current = new maplibregl.Map({
container: mapContainer.current,
style: `https://api.maptiler.com/maps/streets/style.json?key=${API_KEY}`,
center: [lng, lat],
zoom: zoom
});
map.current.addControl(new maplibregl.NavigationControl(), 'top-right');
new maplibregl.Marker({color: "#FF0000"})
.setLngLat([139.7525,35.6846])
.addTo(map.current);
});
return (
<div className="map-wrap">
<div ref={mapContainer} className="map" />
</div>
);
}
Full code to download
We have created a template with the result of this tutorial that will serve as a basis to build future applications. You can access the template repository at React template for MapLibre.
###
Online demo:
You can see an online demo at https://labs.maptiler.com/cra-template-maplibre-gl-js/
Conclusion
Congratulations! You have finished your simple fullscreen map app using React JS, showing Tokyo with a marker on Tokyo Imperial Palace. You can explore more about MapLibre GL JS for your map in the MapLibre API reference.
Useful links
MapTiler - React template for MapLibre MapLibre API
React JS - Getting Started
MapLibre GL
MapLibre
MapTiler Cloud - Customize
Related guides
- Automatically created API key
- Check if MapLibre GL JS is supported
- Dataset upload - formats and limits
- Difference between 256x256, 512x512, and HiDPI/Retina rasterized tiles
- Disputed borders on your maps
- Exported Tiles Multiplier
- Generalization in maps
- How are maps used in NFT tokens
- How are the tile requests cached in web browser?
- How MapTiler map tiles are Generated and Delivered