Prototyping mobile apps with Mapbox in Framer.js

Follow this tutorial to integrate Mapbox GL JS into your Framer prototypes. Framer is based on web technologies and works perfectly with Mapbox’s JavaScript Libraries for fast prototyping. When you’re ready to build a fully native mobile app, you can move to the Mapbox iOS SDK and Mapbox Android SDK with confidence that your map will look great.

To get started, you’ll need:

If you haven’t used a terminal before, the first step will be the hardest, but it’ll be all fun after that.


You can start from an existing Framer project or create a blank one and start from scratch. Framer projects exist on your computer as folders named something like YourProject.framer, and contain CoffeeScript source code as well as a directory called modules. In the following steps, you’ll install Mapbox GL JS into your project as a module.

Open a terminal and navigate to your project folder. If your project is in your Documents folder instead of in your home folder, type ~/Documents/my-framer-project

$ cd ~/my-framer-project

Next, use npm to install the latest version of Mapbox GL JS:

$ npm install mapbox-gl

Great! Once this is done, you’ll have the Mapbox GL JS source code downloaded onto your computer. Your project still doesn’t know how to find that source code, though, so you’ll need to create a file that connects it. Create a new file in the modules directory inside of your project and call it Give it these contents:

exports.mapboxgl = require "mapbox-gl"

Now you’ll be able to require Mapbox GL JS in your project. At the top of your Framer project, add a single line of code telling the project to pull in the mapboxgl object:

{ mapboxgl } = require "npm"

Once you have mapboxgl imported, you can start adding maps!

Two notes before you pull together that source code:

  • Mapbox maps live inside HTML elements. By default, Framer makes HTML non-interactive, which means no panning or zooming. If you want your maps to be interactive, add the line mapboxLayer.ignoreEvents = false to turn events back on.
  • Framer tries to make your prototypes fit on your computer’s screen by scaling them at a number of ratios. For example, you might look at your prototype at 75% scale to view a high-resolution mock-up on a small laptop screen. Mapbox GL JS will act a little strangely when scaled, so we recommend setting your scale to 100% to ensure map interactions, like zooming or panning, behave correctly.
  • Any place you see {your_access_token}, you’ll need to substitute a valid access token from your account. Get an access token and put it in there.
{ mapboxgl } = require "npm"

# Creating a new HTML layer
# for the map to live inside of and scale
# it to fit the entire window
mapHeight = Screen.height
mapWidth = Screen.width

mapboxLayer = new Layer
mapboxLayer.ignoreEvents = false
mapboxLayer.width = mapWidth
mapboxLayer.height = mapHeight
mapboxLayer.html = "<div id='map'></div>"
mapElement = mapboxLayer.querySelector("#map") = mapHeight + 'px'

# Set your Mapbox access token here!
mapboxgl.accessToken = '{your_access_token}'

map = new mapboxgl.Map({
    container: mapElement
    zoom: 12.5
    center: [-77.01866, 38.888]
    # here we're using a default style:
    # you can use any of the defaults or a
    # custom style you design in Mapbox Studio
    style: 'mapbox://styles/mapbox/streets-v9'
    hash: true

That’s it! The map object you have access to in Framer will have the same methods and properties as the Mapbox GL JS API.

For instance, if you want to add a button that zooms the map, you can add this code to the bottom of the prototype:

layerA = new Layer
    x: 100
    y: 100
    width: 200
    height: 200
    borderRadius: 200
    opacity: 1
    backgroundColor: "white"

layerA.onClick ->
    map.zoomTo 10

Have fun prototyping!

Next article:

Switch from Google Maps to the Mapbox iOS SDK

Moving your app from Google Maps to Mapbox is a snap.

Additional questions? Ask our support team or learn more about How Mapbox Works.