Prototyping mobile apps with Mapbox in Framer
Familiarity with front-end development concepts. Some advanced JavaScript required.

In this tutorial, you’ll walk through how to initialize a simple Mapbox GL JS map in your Framer prototype. In web design, prototyping is the process of creating an interactive demo of what a final application will look like before actually building it. It’s useful for testing design ideas and getting feedback from key stakeholders in your design process.

Framer is a prototyping system that allows users to design applications across multiple native platforms using front-end web development principles. Rather than learning Swift to prototype an iOS app or Java to prototype an Android app, Framer allows designers to create a single prototype for multiple platforms using CoffeeScript, a programming language that compiles to JavaScript.

Mapbox GL JS and Framer integrate seamlessly to help you add beautiful interactive maps to your prototype. Anything you can build for the web using Mapbox GL JS you can also build in Framer– you just need to translate your code from JavaScript to CoffeeScript. This tutorial will walk through how to initialize a basic map to get you started.

Getting started

Some of the following steps tutorial will require the command line and rely on basic front-end web development principles. If you’re new to either of these, be sure to check out an educational resource like Codecademy before starting.

  • Node.js and npm. You’ll be using Node.js and npm to install the Mapbox GL module in your project folder. npm will be included when you download Node.js.
  • Framer. Make sure you install Framer on your local machine. Framer offers a 14 day free trial, after which it requires a paid plan.
    • Familiarize yourself with Framer. If you’d like to learn more about how Framer works or how to customize your prototypes, be sure to read Framer’s Getting Started guide and documentation.
  • Your API access token. You can find your access token on your Account page.

Setting up your project

First, create a new Framer project.

  • Open Framer.
  • Click File > New. You should see a new window open with your blank project.
  • Save your file by clicking File > Save. Call your project DC.

Before moving on, take a quick look at the file structure of your Framer project.

├─ framer
├─ images
├─ index.html
└─ modules

Framer projects exist on your computer as folders that end with .framer. This is known as your project folder. The project folder contains all of the resources you need to build your prototype, including your CoffeeScript code in the file, as well as a modules directory.

Install Mapbox GL JS

Next, install Mapbox GL JS into your project as a module.

  • Open a new Terminal window.
  • Navigate inside your project folder DC.framer.
  • Use npm to install the latest version of Mapbox GL JS by running the following command:
$ 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 this source code, so you’ll need to create a file that points to its location.

  • Open a new file in your project’s modules directory.
  • Copy and paste the following code into your new file:
exports.mapboxgl = require "mapbox-gl"
  • Save your file as

Now you can require Mapbox GL JS in your project.

  • Open up your project in Framer if it isn’t open already.
  • At the top of your blank file, copy and paste the following code to import the mapboxgl object and CSS:
{ mapboxgl } = require "npm"

Utils.insertCSS('@import url(')

Congratulations! You’re now ready to start using Mapbox GL JS to build your map.

Initializing your map

Once you have mapboxgl imported, you can start creating a map!

Create the map container

Like many graphics editing tools, Framer uses layers to create elements in your project. To initialize our map, you’ll need to create a new layer and add an HTML <div> to it with an id of #map.

  • Create a new layer for our map by copying and pasting the following code into your project after you require Mapbox GL code:
mapLayer = new Layer
	height: Screen.height
	width: Screen.width
  • Copy and paste the following code after your mapLayer declaration:
mapLayer.html = "<div id='map'></div>"
mapElement = mapLayer.querySelector("#map") = Screen.height + 'px'

This code adds a <div> element with an id of #map to your mapLayer and uses the querySelector method to return this HTML element. You can then set the height of mapElement just like you would with any DOM element.

To learn more about how HTML elements work in Framer, be sure to check out the Framer documentation.

Declare a new Map object

Next, you’ll create a new Map object in much the same way you would if you were creating a web application with Mapbox GL JS. You’ll be using the Mapbox Streets basemap for this project, but you could use any default or custom style URL you’d like in your own project.

  • Copy and paste the following code at the end of your current code. Make sure you replace {your access token} with your access token.

  • Save your project:

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

map = new mapboxgl.Map
    container: mapElement
    zoom: 12
    center: [-77.01866, 38.888]
    # Add Mapbox style url
    style: 'mapbox://styles/mapbox/streets-v9'

You should now see your map displaying in your preview window. Before moving on, you should add one more thing. By default, Framer disables interactivity for HTML elements, which means that right now you can’t pan or zoom your map.

  • To make your map interactive, copy and paste the following code at the end of your project:
mapLayer.ignoreEvents = false

Finished product

Congratulations! You’ve created an interactive web map in your Framer prototype using Mapbox GL JS. The map object you created will have the same methods and properties as the Mapbox GL JS API.

Next steps

Be sure to check out our Mapbox GL JS examples for more ideas on how to extend your project. When you’re done prototyping, you can start building a fully native mobile app with the Mapbox Maps SDK for iOS or Android with the confidence that your map will look great. Have fun mapping and prototyping!