> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to Mapbox

> Connect your app to Mapbox to embed interactive maps with Mapbox GL JS, geocode addresses, and calculate routes and directions from your Lovable app.

export const connector_0 = "Mapbox"

[Mapbox](https://www.mapbox.com/) is a location platform for interactive maps, geocoding, routing, and static map images. The Mapbox connector lets your Lovable app render maps in the browser with Mapbox GL JS and call server-side Mapbox APIs through Lovable's connector gateway. It's designed for apps that need Mapbox-specific styles, Mapbox GL JS, or location features you want to run on Mapbox rather than another maps provider.

With Mapbox, your app can:

* Embed interactive maps with Mapbox GL JS using a public token
* Geocode addresses and search places with the Geocoding API
* Calculate routes and turn-by-turn directions
* Render static map images for previews and thumbnails

<Tip>
  For a quick prototype with generic maps, geocoding, or directions, [Google Maps Platform](/integrations/google-maps) can be faster to setup.
</Tip>

## Common use cases and example apps

| Example app                  | Example prompt                                                                                                                                          | Description                                                                                                                                                    |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Store locator**            | *Use Mapbox and build a store locator with clustered pins, address search, and a sidebar that lists the nearest locations.*                             | **Help visitors find the closest location on a map.**<br />The app geocodes searches, renders pins with Mapbox GL JS, and updates the list as the map moves.   |
| **Delivery dispatch board**  | *Use Mapbox and build a dispatch board that shows today's stops on a map, calculates route distance between pickup and dropoff, and sorts jobs by ETA.* | **Plan routes and ETAs for field operations.**<br />The app calls Mapbox routing server-side and renders stops and paths on an interactive map.                |
| **Real estate listings**     | *Use Mapbox and build a property listing app where users browse homes on a map, filter by neighborhood, and open detail pages from each pin.*           | **Browse listings on a map-first experience.**<br />The app centers the map on search results, renders listing pins, and links each pin to a detail page.      |
| **Travel itinerary planner** | *Use Mapbox and build a trip planner where users add stops, see them on a map, and view driving distance and time between each leg.*                    | **Visualize multi-stop trips with distances and times.**<br />The app geocodes stops, draws the route on a Mapbox map, and shows leg-by-leg summaries.         |
| **Event venue finder**       | *Use Mapbox and build an event finder where users search by city, see venues on a map, and filter by capacity or event type.*                           | **Discover venues through map search and filters.**<br />The app geocodes venue addresses, renders them as pins, and filters the map and list together.        |
| **Static map previews**      | *Use Mapbox and build an admin page that shows a thumbnail map image for each saved location using the Static Images API.*                              | **Generate map previews without loading a full interactive map.**<br />The app requests static map images server-side and displays them in list or card views. |

## How to connect Mapbox

Who can create Mapbox connections depends on your plan and workspace settings. See [Who can create connections](/integrations/introduction#who-can-create-connections).

You can create multiple Mapbox connections using different tokens, which is useful for separating environments (for example, development and production) or using different Mapbox accounts.

When the connection is created, you can link it to the projects where you want to use it. Anyone building in a project can ask Lovable in chat to link their project to it.

### Prerequisites

Before connecting Mapbox, make sure you have:

* A Mapbox account
* At least one Mapbox access token: a **public token** (`pk.`) for browser maps, a **secret token** (`sk.`) for server-side APIs, or both
* Permission to **create connections** in your Lovable workspace (see [Who can create connections](/integrations/introduction#who-can-create-connections))

<Note>
  All Mapbox API usage counts toward your Mapbox plan and is billed by Mapbox, not Lovable.
</Note>

### Step 1: Get Mapbox access tokens

Mapbox uses two token types for different surfaces. They are not interchangeable.

* **Public token (`pk.`)**: browser only. Use it for Mapbox GL JS and map tiles in the frontend.
* **Secret token (`sk.`)**: backend only. Use it for geocoding, directions, static images, and every other server-side Mapbox API called through Lovable's connector gateway.

Provide at least one token when you connect. Map-only apps can connect with a public token alone. Any server-side Mapbox feature requires a secret token on the connection.

To create Mapbox access tokens:

<Steps>
  <Step title="Open your Mapbox account">
    Sign in to [Mapbox](https://account.mapbox.com/).
  </Step>

  <Step title="Open access tokens">
    Go to [Access tokens](https://account.mapbox.com/access-tokens/).
  </Step>

  <Step title="Create or copy tokens">
    Create the tokens your app needs:

    1. **Public token**: create or copy a default public token that starts with `pk.`. Restrict it to your app domains when you go to production.
    2. **Secret token** (if you need geocoding, directions, or other server-side APIs): click **Create a token**, give it a descriptive name (for example, `Lovable integration`), choose the scopes your app needs, and copy the token that starts with `sk.`.
  </Step>

  <Step title="Store the tokens securely">
    Copy each token and store it securely. You'll paste them into Lovable in the next step.
  </Step>
</Steps>

<Warning>
  Your secret token functions like a password. Keep it secure, never embed it in frontend code, and never share it publicly.
</Warning>

See Mapbox documentation for details: [Access tokens](https://docs.mapbox.com/help/glossary/access-token/).

### Step 2: Connect Mapbox to Lovable

You can create multiple connections using different tokens.

<Steps>
  <Step title="Open Mapbox in Connectors">
    Go to **Connectors → App connectors** and select **Mapbox**.
  </Step>

  <Step title="Add a connection">
    Click **Add connection**.
  </Step>

  <Step title="Configure the connection">
    1. **Display name**: name the connection, for example `Mapbox Prod`. This name is only used inside Lovable to identify the connection.
    2. **Secret token** (optional): paste your secret token (`sk.`) if your app needs server-side geocoding, directions, static images, or other backend Mapbox APIs.
    3. **Public token** (optional): paste your public token (`pk.`) if your app renders Mapbox GL JS maps in the browser. This value is publicly visible in your published app after you link the connection to a project.
  </Step>

  <Step title="Choose who can use this connection">
    Under **Who can use this connection**, decide who in your workspace can use the connection. You start as the only person with access:

    * **Only you** (default): leave the access list as is; only you can use the connection and its associated data.
    * **Invite specific people**: add workspace members by email; only you and the people you add can use the connection and its associated data.
    * **Invite entire workspace**: click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

    See [Who can manage connections](/integrations/introduction#who-can-manage-connections) for more information.
  </Step>

  <Step title="Connect">
    Click **Connect**. Lovable validates each token you provide against Mapbox before saving the connection.
  </Step>
</Steps>

When connected, anyone building in a project can ask Lovable in chat to link their project to Mapbox (based on configured connection-level access). Your Lovable apps can then render Mapbox GL JS maps with the public token and call server-side Mapbox APIs through Lovable's connector gateway with the secret token.

## Public and secret tokens

The connector accepts two tokens with different roles:

* The **secret token** (`sk.`) is used for server-side Mapbox API calls. Lovable routes these requests through the connector gateway and exposes the token to your backend as `MAPBOX_API_KEY` after you link the connection to a project. Never use the secret token in frontend code.
* The **public token** (`pk.`) is used for Mapbox GL JS in the browser. After you link the connection, Lovable exposes it as `VITE_LOVABLE_CONNECTOR_MAPBOX_PUBLIC_TOKEN`. Restrict this token to your app domains in the Mapbox account dashboard.

You must provide at least one token when creating the connection. Browser-only map apps can connect with a public token alone. Geocoding, directions, and other backend Mapbox features require a secret token on the connection.

Server-side calls must go through Lovable's connector gateway. Do not call `https://api.mapbox.com` directly from backend code in generated apps.

## Limitations

The Mapbox connector cannot:

* Use a public token (`pk.`) for server-side Mapbox API calls or through the connector gateway
* Use a secret token (`sk.`) in frontend code or Mapbox GL JS
* Replace domain restrictions on your public token. You must configure allowed URLs in the Mapbox account dashboard for production domains
* Support per-end-user Mapbox authentication. Each connection represents a single Mapbox account shared across all projects linked to it
* Refresh or rotate tokens automatically. To rotate, create new tokens in Mapbox and update the Lovable connection

If a token is revoked or deleted in Mapbox, reconnect the integration in Lovable with a valid token before API calls can succeed again.

## How to unlink projects from a {connector_0} connection

Editors and above can remove specific projects from a connection without deleting the connection entirely. The connection will remain available for other projects.

To unlink projects:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to manage.
  </Step>

  <Step title="Select projects">
    Under **Linked projects**, check the projects you want to unlink.
  </Step>

  <Step title="Confirm">
    Click **Unlink projects** and confirm.
  </Step>
</Steps>

When unlinked, those projects will no longer have access to {connector_0} through this connection. If a project needs {connector_0} again, you can link it to any available connection.

## How to delete a {connector_0} connection

Workspace admins and owners can delete {connector_0} connections. Other members can delete a connection if they created it, or if they have been explicitly granted access to it.

<Warning>
  Deleting a connection is permanent and cannot be undone. It will remove the credentials from all linked projects, and any apps using this connection will stop working until a new connection is added.
</Warning>

Before deleting, review the **Linked projects** section to see which projects are currently using the connection.

To delete a connection:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to remove.
  </Step>

  <Step title="Review linked projects">
    Review the **Linked projects** section.
  </Step>

  <Step title="Delete">
    Under **Delete this connection**, click **Delete** and confirm.
  </Step>
</Steps>