Home / GPS and Navigation Guides

Offline Maps With Leaflet: Tile Folders, MBTiles, and Cache-First Patterns That Actually Work Offline

A laptop on a desk displaying lines of code

Photo: Christina Morillo / Pexels

A Leaflet map with no tiles is a gray grid and an apology. The library itself is tiny, about 42 KB gzipped in its current 1.9.4 release, and happily works offline; it is the map imagery, fetched tile by tile from a server, that dies with the connection. So an offline Leaflet map is really a tile logistics problem, and there are three architectures that solve it, suited to three different scales. This guide walks through all three with the trade offs stated plainly, does the tile-count math that determines your maximum zoom, and ends with the one sourcing rule that is not optional. It is the developer companion to our OpenStreetMap vs Leaflet comparison, which covers what each project is; this article assumes you have chosen Leaflet and need it to survive a tunnel, a plane, or a dead zone. The embedding basics live in how to use OpenStreetMap in a website.

Interactive tool

Ship an Offline Leaflet Map: The Checklist

Check off each step as you finish it. Your progress stays on this page.

0 of 7 complete

0% done

Tiles in Sixty Seconds

Leaflet displays the world as a pyramid of square image tiles addressed by z/x/y: zoom level z, and the tile's column x and row y at that zoom. At zoom 0 the world is one tile; each zoom level down multiplies the count by four. A tile layer is just a URL template, and Leaflet asks the browser for tiles like tiles/16/10342/25489.png as you pan. Offline, therefore, means one thing: when Leaflet asks for a tile, something local must answer, a file, a database, or a cache, instead of a remote server. Every architecture below is a different way of arranging that answer.

Method 1: A Local Tile Folder (Best for One Area, One App)

The simplest architecture is a directory of pre-rendered tiles in the standard z/x/y layout, shipped with your app or served from your own static hosting, with the tile layer pointed at it:

```

L.tileLayer('tiles/{z}/{x}/{y}.png', { maxZoom: 16 }).addTo(map);

```

Serve the folder from the same origin as the page and Leaflet cannot tell the difference from a tile server. This is the right choice for a kiosk, a field app covering one park or campus, an Electron or Cordova app, or a demo that must work on conference Wi-Fi, which is to say no Wi-Fi. Its limits are file count and updates: a deep zoom range over a wide area becomes hundreds of thousands of small files, which filesystems and deployment pipelines handle grumpily, and updating the map means replacing the folder. Keep the area tight and the maximum zoom honest (see the math below) and this method is bulletproof.

Method 2: MBTiles in the Browser (Best for One File, Shipped Anywhere)

MBTiles packs an entire tile pyramid into a single SQLite database file. One file is vastly easier to ship, version, and download than a folder of a hundred thousand PNGs, which is why MBTiles is the standard format for offline map packages. In the browser, the Leaflet.TileLayer.MBTiles plugin reads the file using sql.js, SQLite compiled to WebAssembly, and serves tiles from it as Leaflet requests them. The pattern: host or bundle the .mbtiles file, load it once, attach the layer. The costs are a heavier first load (the whole file's index comes into memory) and plugin maintenance risk, since the plugin is a community project rather than Leaflet core. For an app that offers users downloadable regions, one file per region, this is the architecture the professionals pick, and it is how most offline-first web mapping demos are built.

Method 3: Cache as You Browse, Seeded in Advance (Best for Web Apps)

The third architecture keeps the normal remote tile layer but interposes a cache: a service worker or an IndexedDB-backed plugin stores every tile the user views, so revisited areas work offline, and a seed step pre-downloads a chosen area before the trip. The established Leaflet implementation of this pattern is the PouchDB-based tile layer plugin: enable it with useCache: true, call seed(bounds, minZoom, maxZoom) to prefetch an area, and set cacheMaxAge (default 24 hours) for how long tiles stay fresh. Two gotchas decide whether it works at all. First, tiles must be served with CORS headers for the cache layer to store cross-origin tiles; without them the browser refuses and the cache stays empty. Second, browser storage is a quota, not a promise: IndexedDB space is shared, browser-managed, and evictable under pressure, so a seeded region is a strong intention, not a guarantee. Treat this method as graceful degradation for a web app, not as the foundation of a safety-critical field tool.

A laptop screen showing HTML code in soft focus
A laptop screen showing HTML code in soft focus

The Math That Picks Your Maximum Zoom

Tile counts grow by four per zoom level, and this arithmetic, not storage marketing, sets your limits:

CoverageZoom 12Zoom 14Zoom 16Zoom 18
Tiles per square of world at that zoom16.7 million total268 million total4.3 billion total68.7 billion total
One mid-size city, roughlyA few hundred tilesA few thousandTens of thousandsHundreds of thousands

Read the table as a warning about the last two zooms. A city pack at zoom 16 is a reasonable download; the same city at zoom 18 is sixteen times larger for detail most walkers never need, and a country at zoom 18 is not a download, it is a data center. Practical packs cap street detail around zoom 15 or 16, go lower for regional overviews, and use vector tiles or on-device rendering when deep zoom over wide areas is truly required. Every offline map product you have ever used made exactly this compromise; making it consciously is the whole skill.

The Rule That Is Not Optional: Do Not Bulk-Download the Public Tile Server

The tempting shortcut, scripting a download of every tile your area needs from tile.openstreetmap.org, is explicitly against the OpenStreetMap tile usage policy: bulk downloading and pre-seeding from the public tile servers is prohibited, and the servers will throttle or block it. The policy exists because those servers are a donated resource for live browsing, not a distribution channel. The legal sources for offline tiles are: tiles you render yourself from OSM data, commercial or community providers whose terms permit offline use and caching, and prebuilt MBTiles extracts sold or published for exactly this purpose. Our OpenStreetMap download guide covers getting the underlying data. Respecting this rule is not etiquette; it is the difference between an architecture and an abuse report.

Choosing Among the Three, in One Breath

If you are still deciding, decide by failure tolerance. The tile folder cannot partially fail: the files are there or they are not, and for a bounded area in a controlled app it is the choice that lets you sleep. MBTiles trades a little fragility (a plugin, a heavier load) for the enormous operational convenience of one file per region, and it is the choice for anything users download. The seeded cache is the only method that improves a normal online web app without changing its architecture, and it is the choice when offline is a bonus rather than a promise, a subway dead zone forgiven, a rural weekend softened. Mature projects sometimes layer them, cache for the everyday, MBTiles for the expedition mode, but each layer is a maintenance commitment, and the honest default for a first offline Leaflet build is the folder: boring, inspectable, and finished. Decide by asking what happens on the worst day, a user with no signal and no patience, and let the architecture that answers that day win.

A Fourth Option, With a Warning: Vector Tiles

Everything above ships raster tiles, pre-drawn pictures of the map. The modern alternative is vector tiles: compact geometry that the client draws at display time, which packs a continent into the space raster tiles need for a province and stays crisp at every zoom. In the Leaflet world this arrives through plugins (vector grid layers reading MBTiles or PMTiles-style archives) rather than through Leaflet core, and rendering moves to heavier libraries when projects outgrow the plugins. The offline logic is identical, ship the archive locally and point the layer at it, but the engineering weight is not: styling, labeling, and rendering performance become your problem in exchange for the size win. For one area at fixed zooms, raster remains the pragmatic choice, which is why the three methods above carry most real projects. Choose vector when coverage area, not simplicity, is the constraint that hurts.

Updates, Freshness, and Honest Testing

Offline maps go stale on a schedule you choose. For tile folders and MBTiles, version the package (region name plus date in the filename) and replace it wholesale rather than patching tiles, so a half-updated pyramid never mixes two vintages of the same street. For cached tiles, cacheMaxAge is your freshness dial, and the honest move is telling users the map's as-of date in the interface. Finally, test offline the way users will meet it: browser developer tools can simulate offline for a first pass, but the real test is airplane mode on a real phone, cold-starting the app with radios off, because service worker registration, storage eviction, and first-load behavior all differ from the desktop simulation. If it works there, it works.

Related Guides

Readers working through this topic usually need its closest companions too. These GPS and navigation guides cover the neighboring ground:

Frequently Asked Questions

Can Leaflet work fully offline?

Yes. Leaflet itself is a small JavaScript library that runs locally; what needs replacing is the tile source. Point the tile layer at a local z/x/y folder, an MBTiles file read with sql.js, or a seeded browser cache, and the map pans and zooms with no network at all.

What is the best way to store offline tiles for Leaflet?

For a single defined area, a pre-rendered z/x/y tile folder is simplest and most robust. For downloadable regions, MBTiles is the standard because one SQLite file ships and versions cleanly. For a general web app, a service worker or IndexedDB cache with a seeding step degrades most gracefully.

Can I just download tiles from OpenStreetMap's servers for my offline map?

No. OpenStreetMap's tile usage policy prohibits bulk downloading and pre-seeding from tile.openstreetmap.org. Render your own tiles from OSM data, use a provider whose terms allow offline caching, or obtain a prebuilt MBTiles extract made for offline use.

What zoom level should an offline tile pack go to?

Usually 15 or 16 for street-level detail. Tile counts multiply by four with each zoom level, so zoom 18 makes a pack sixteen times larger than zoom 16 for the same area. Cap the maximum zoom deliberately and let the math, not optimism, size the download.

Why is my seeded tile cache empty?

The usual cause is CORS: the tile server must send cross-origin headers or the browser will not let the cache layer store its tiles. The second cause is storage pressure: browsers can evict IndexedDB under quota pressure, so check that the cache survives a browser restart, not just the session that seeded it.

Photo credits: Christina Morillo (Pexels); Negative Space (Pexels). Photos are served from this site; follow the credit to the library page for the original.