@antv/l7-mapkit

React components for AntV L7 geospatial visualization library. Built on React 18+ and @antv/l7 2.25+.

Features

• 🎯 Flat Props API - Direct props like colorField, sizeValues, shape instead of nested objects
• ⚡ Event Handling - Events directly attached to components (onClick, onMouseEnter) without separate event components
• 🧩 Composable - Component composition pattern inspired by mapcn design philosophy
• 📦 TypeScript First - Complete type definitions with JSDoc documentation
• 🤖 LLM Friendly - Includes llms.txt and comprehensive API docs for AI assistants
• 🗺️ Multiple Maps - Supports GaodeMap (高德) and built-in Map (no third-party dependency)

Installation

npm install @antv/l7-mapkit @antv/l7 @antv/l7-maps

Quick Start

import { GaodeMapScene, PointLayer } from '@antv/l7-mapkit';

const data = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', geometry: { type: 'Point', coordinates: [120.19, 30.26] }, properties: { value: 80 } },
    { type: 'Feature', geometry: { type: 'Point', coordinates: [121.47, 31.23] }, properties: { value: 120 } },
  ],
};

function App() {
  return (
    <GaodeMapScene
      style={{ width: '100%', height: '400px' }}
      mapConfig={{ zoom: 7, center: [120.5, 30.8] }}
    >
      <PointLayer
        source={data}
        colorField="value"
        colorValues={['#fee5d9', '#fc4e2a', '#800026']}
        size={8}
        shape="circle"
        onClick={(e) => console.log(e.feature.properties)}
      />
    </GaodeMapScene>
  );
}

Components

Scene Components

• <GaodeMapScene> - Gaode Map container component
• <MapScene> - Built-in map container (no third-party dependency)

Layer Components

All layer components share the same flat props interface:

• <PointLayer> - Point/scatter layer
• <LineLayer> - Line/path layer (supports arc, greatcircle shapes)
• <PolygonLayer> - Polygon/area layer
• <HeatmapLayer> - Heatmap layer (2D/3D/hexagon/grid)
• <RasterLayer> - Raster/tile layer
• <ImageLayer> - Image overlay layer
• <CityBuildingLayer> - 3D building layer

Interactive Components

• <Marker> - Map marker with custom React content
• <MarkerLayer> - Batch markers with clustering support
• <Popup> - Map popup with custom React content
• <Control> - Built-in controls (zoom/scale/logo/layerSwitch/etc.)
• <CustomControl> - Custom control with any React content
• <LoadImage> / <LoadImages> - Load image resources

Hooks

• useScene() - Get current Scene instance (must be used inside Scene components)
• useLayer() - Get current Layer instance (must be used inside layer children)

Layer Props Reference

Prop	Type	Description
source	any	Data source (GeoJSON/array/URL) required
sourceConfig	object	Data parser config { parser: { type: 'json', x: 'lng', y: 'lat' } }
color	string	Fixed color value
colorField	string	Color mapping field name
colorValues	string[] | fn	Color mapping values or callback
size	number	Fixed size in pixels
sizeField	string	Size mapping field name
sizeValues	number[] | fn	Size mapping range [min, max]
shape	string	Shape type (circle/triangle/arc/etc.)
style	object	Layer style { opacity, stroke, strokeWidth }
filterField	string	Filter field name
filterValues	any[] | fn	Filter values or callback
animate	object	Animation config { enable, speed, trailLength }
active	boolean | object	Hover highlight
select	boolean | object	Click selection
onClick	fn	Click event handler
onMouseEnter	fn	Mouse enter handler
onMouseLeave	fn	Mouse leave handler
onLoaded	fn(layer, scene)	Layer loaded callback

Migration from 2.x

L7-MapKit 3.0 is a complete rewrite with breaking changes:

Before (2.x)

<PointLayer
  source={{ data }}
  color={{ field: 'value', values: ['red', 'blue'] }}
  size={{ field: 'count', values: [5, 20] }}
/>
<LayerEvent type="click" handler={handleClick} />

After (3.0)

<PointLayer
  source={data}
  colorField="value"
  colorValues={['red', 'blue']}
  sizeField="count"
  sizeValues={[5, 20]}
  onClick={handleClick}
/>

Key changes:

• ✅ Flat props instead of nested objects
• ✅ Events directly on components (no LayerEvent/SceneEvent)
• ✅ All class components converted to function components with hooks
• ✅ Only GaodeMap and built-in Map supported (Mapbox removed)
• ✅ React 18+ only (uses useId, strict mode safe)

Documentation

• Full API Reference
• LLM-friendly docs

Development

# Install dependencies
npm install

# Type check
npm run type-check

# Build
npm run build

# Watch mode
npm run dev

License

MIT