AntV L7: a WebGL engine for large geospatial datasets, and when it is the wrong layer to pick

What AntV L7 does that a general mapping library does not

Most JavaScript map libraries start from the map: tiles, panning, markers, popups. L7 starts from the data. The README describes it as a WebGL-based large-scale geospatial data visualization and analysis engine, and the naming note is explicit: L stands for Location, 7 for the seven continents, a nod to global location data. The stated audience is map charts, BI dashboards, and spatial information systems in GIS, transport, power, land, agriculture and city domains.

The distinction matters in practice. If your job is to place twenty pins on a city map, a conventional mapping library is simpler. If your job is to render a few hundred thousand points, color them by a numeric field, size them by another, and let the user zoom without the frame rate collapsing, the rendering pipeline is the product. L7's README frames this as 2D and 3D integrated rendering of large data volumes, with visual variables (color, size, texture, direction, volume) mapped from fields in your dataset.

It is a rendering engine, not an analysis engine in the server sense. The README's phrase is visual analysis, and everything in the documented API surface is about drawing and interaction. There is no documented spatial join, no server-side tiling pipeline, no coordinate transformation toolkit. Teams that need those should treat L7 as the last mile, not the whole stack.

Scene, Layer and the basemap adapter: how the pieces fit

L7's architecture is a two-level object model. A Scene owns the container, the basemap and the camera. Layers are attached to the Scene and each layer binds a data source to a shape, a size mapping, a color mapping and a style block. The README's own example constructs a Scene with a Mapbox basemap, then builds a PointLayer whose size and color both read from a field called mag.

The basemap is deliberately abstracted behind an adapter. The README states that L7 hides the differences between basemaps so that users only deal with the data layer, and it names two: AMap, described as the legally compliant geographic basemap in China, and Mapbox for international business needs. That adapter boundary is the most consequential design decision in the project, because it is also the boundary where compliance, API keys and vendor terms live. Swapping adapters is a code change, but it is not a neutral one.

Data intake is intentionally loose. The README lists CSV, JSON and GeoJSON, and says custom formats can be defined without complex spatial data conversion. In other words, L7 does not force your data through a GeoJSON-shaped pipeline before it can be drawn; you supply a parser and a field mapping. The trade-off is that correctness of geometry is your responsibility, and the engine will happily draw whatever coordinates you hand it.

Layer types are grouped by geometry: point layers (bubble, scatter, symbol, 3D bar, cluster, composite, custom marker), line layers (path, 2D and 3D arcs including great-circle routes, isolines), polygon layers (fill and 3D fill), heatmaps (classic, hexagonal, grid) and raster. If your visualization is not expressible as one of those, you are writing a custom layer against the WebGL internals, which the README does not walk through.

Installing @antv/l7 and drawing a first point layer

The README gives a single install command and then two code blocks. There is no scaffolding CLI and no project template in the documented quickstart; you add the packages to an existing front-end project. The package name is scoped, and the basemap adapter lives in a separate package, so a minimal setup pulls two dependencies.

npm install @antv/l7

After installing, the README's initialization example imports Scene from @antv/l7 and Mapbox from @antv/l7-maps. Note that the install line above names only @antv/l7; the Mapbox adapter is imported from @antv/l7-maps, so that package has to be present in your project for this snippet to resolve.

import { Scene } from '@antv/l7';
import { Mapbox } from '@antv/l7-maps';

const scene = new Scene({
  id: 'map',
  map: new Mapbox({
    style: 'light',
    pitch: 0,
    center: [107.054293, 35.246265],
    zoom: 4.056,
  }),
});

The id value refers to a DOM element that must already exist in your page. The center is a longitude and latitude pair, and the README does not document what happens if the element is missing.

The second block adds a layer. It imports PointLayer, chains source, shape, size, color and style, and then calls scene.addLayer.

import { PointLayer } from '@antv/l7';

const pointLayer = new PointLayer()
  .source(data)
  .shape('circle')
  .size('mag', [1, 25])
  .color('mag', ['#5B8FF9', '#5CCEA1'])
  .style({
    opacity: 0.3,
    strokeWidth: 1,
  });

scene.addLayer(pointLayer);

The data variable is not defined in the README snippet. The size call maps the mag field onto a 1 to 25 pixel range and the color call maps the same field onto a two-stop gradient, which is the data-driven pattern the project is built around. If you see nothing on screen, the first things to check are that the container element has a height and that your data field is actually named mag or has been renamed to match.

Where L7 stops being the right tool

L7 renders. It does not edit, and the README documents no editing mode, no drawing tools and no feature-attribute editing. If your users need to draw a polygon on the map and have it persisted as an editable feature, that is a different kind of application. The project's own ecosystem list points at L7Draw and L7Editor as separate repositories, which is a fair signal that editing was deliberately kept out of the core.

The second boundary is spatial computation. Buffer analysis, point-in-polygon joins, routing, geocoding and reprojection are not in the documented feature set. You either precompute them and ship the results as data, or you run them in another service. Teams coming from desktop GIS often assume an engine that draws polygons can also answer questions about them; here it cannot.

The third boundary is basemap dependency. Because the basemap sits behind an adapter, your application inherits the terms, the keys and the availability of whichever provider you choose. The README frames AMap as the compliant domestic option and Mapbox as the international one, which is honest about the constraint but also means L7 alone does not give you a basemap. Offline intranet deployment is listed as a supported scenario, but the README does not document the tile hosting setup that would require; that is the piece to confirm before you promise it to anyone.

Finally, there is the release cadence question. The repository is not archived and the last push to master was 2026-09-08, but the most recent release listed is v2.22.5 from 2025-03-11. Commits landing on master and a published npm package are different things. If your deployment depends on the published artifact rather than a git checkout, the release history is the number that matters to you.

L7 versus deck.gl and MapLibre-based stacks

The closest comparison in the same problem space is deck.gl, which also renders large geospatial datasets on the GPU and also separates layers from the basemap. The difference in approach is where the abstraction sits. deck.gl is a layer framework that expects to be paired with a map library such as Mapbox GL JS or MapLibre GL JS, and its layer model is functional and composition-heavy. L7 packages the scene and the basemap adapter into its own object model, so a Scene owns the camera and the layers attach to it directly. That makes L7's quickstart shorter for the common case and makes it harder to swap the rendering layer out while keeping the rest of your map code.

MapLibre GL JS is a different comparison. It is a map renderer with its own style spec, and while it can draw data-driven layers, its strength is the map itself: styles, sources, tiles, interaction. It does not offer L7's typed layer catalog, and it does not ship point clustering, 3D arcs, isolines or hexagonal heatmaps as named layer types. If your visualization is mostly a styled basemap with modest data overlays, MapLibre is the smaller dependency.

There is also the ecosystem question. The README lists L7Draw, L7Plot, LarkMap, L7VP and L7Editor as related projects, and L7Plot in particular appears in the search terms people use around this project. That is a real advantage if you are already inside the AntV family, and a real cost if you are not, because the surrounding tools are where chart-oriented and dashboard-oriented use cases are meant to live. Choosing L7 without those means writing more of the presentation layer yourself.

Licence, upgrade cost and what the monorepo implies

The README states that the project's code and documentation are released under the MIT licence, and the repository carries a LICENSE.md at the top level. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a plain statement of the licence text, not legal advice, and if your organisation has a licence review process the MIT terms are short enough to read in full.

The upgrade cost is shaped by the monorepo. The root package.json is named l7-monorepo, marked private, and declares [email protected] as the package manager, with workspaces under packages/. Publishing goes through changesets: the scripts include changeset, publish-version and publish-packages, and publish-packages runs the build, a size limit check and then changeset publish. For a consumer this means version numbers are coordinated across the @antv/l7 packages rather than released independently, so upgrading the core and the map adapter together is the normal path.

For contributors the entry cost is higher than a single-package project. The root scripts include separate unit and integration Jest configs (jest.config.ts and jest.e2e.config.ts), lint and format scripts driven by shell scripts under scripts/, stylelint for CSS and Less, husky for git hooks, and commitlint. There is a legacy/ directory alongside packages/, which is worth understanding before you assume every file you find is current code. The repository also carries skills/ and .claude/ directories, but nothing in the README describes what they are for.

Editorial conclusion

Adopt L7 if you are building a TypeScript web application that needs to draw large point, line, polygon, heat and raster layers over a basemap, and you are willing to bind your rendering code to the Scene and Layer API. Do not adopt it if you need a full desktop GIS, server-side spatial analysis, or a framework-agnostic mapping library that you can swap out later. Before committing, verify three things yourself: that the basemap package you intend to use (@antv/l7-maps with Mapbox or AMap) matches your compliance and network requirements, that the layer types you need exist in the current release rather than only in the examples site, and that the last push date on the master branch, 2026-09-08, reflects a cadence you can live with, since the most recent published release listed is v2.22.5 from 2025-03-11.

Frequently asked questions

Official sources

1. antvis/L7 on GitHub
2. License: MIT
3. Project website
4. README
5. Releases