Mapbox Data Visualization Patterns

Data Visualization Patterns Skill

Comprehensive patterns for visualizing data on Mapbox maps. Covers choropleth maps, heat maps, 3D extrusions, data-driven styling, animated visualizations, and performance optimization for data-heavy applications.

When to Use This Skill

Use this skill when:

• Visualizing statistical data on maps (population, sales, demographics)
• Creating choropleth maps with color-coded regions
• Building heat maps or clustering for density visualization
• Adding 3D visualizations (building heights, terrain elevation)
• Implementing data-driven styling based on properties
• Animating time-series data
• Working with large datasets that require optimization

Visualization Types

Choropleth Maps

Best for: Regional data (states, counties, zip codes), statistical comparisons

Pattern: Color-code polygons based on data values

map.on('load', () => {
  // Add data source (GeoJSON with properties)
  map.addSource('states', {
    type: 'geojson',
    data: 

step vs interpolate: The example above uses interpolate for smooth color gradients. For discrete color buckets (e.g., “low / medium / high”), use ['step', ['get', 'population'], '#f0f0f0', 500000, '#fee0d2', 2000000, '#fc9272', 10000000, '#de2d26'] instead. Prefer step when data has natural categories or when exact boundary values matter.

Color Scale Strategies:

// Linear interpolation (continuous scale)
'fill-color': [
  'interpolate',
  ['linear'],
  ['get', 'value'],
  0, '#ffffcc',
  25, '#78c679',
  50, '#31a354',
  100, '#006837'
]

Heat Maps

Best for: Point density, event locations, incident clustering

Pattern: Visualize density of points

map.on('load', () => {
  // Add data source (points)
  map.addSource('incidents', {
    type: 

Best Practices

Color Accessibility

// Use ColorBrewer scales for accessibility
// https://colorbrewer2.org/

// Good: Sequential (single hue)
const sequentialScale = ['#f0f9ff', '#bae4ff', '#7fcdff', '#0080ff', '#001f5c'];

// Good: Diverging (two hues)
const divergingScale = ['#d73027', '#fc8d59', '#fee08b', '#d9ef8b'

Error Handling

// Handle missing or invalid data
map.on('load', () => {
  map.addSource('data', {
    type: 'geojson',
    data: dataUrl
  });

  map.addLayer({
    id: 'data-viz',
    type: 'fill',
    source: 

Data Size Rule

• < 1 MB: Use GeoJSON directly
• 1–10 MB: Consider either GeoJSON or vector tiles depending on complexity
• > 10 MB: Use vector tiles (upload to Mapbox as tileset)

See references/performance.md (opens in a new tab) for implementation details.

Reference Files

For additional visualization patterns, load the relevant reference file:

• references/clustering.md (opens in a new tab) — Point clustering, custom cluster properties, clustering vs heatmap comparison
• references/3d-extrusions.md (opens in a new tab) — 3D building extrusions, custom data sources, data-driven heights
• references/circles-lines.md (opens in a new tab) — Circle/bubble maps, line data visualization, traffic flow styling
• references/animation.md — Time-series animation, real-time data updates, smooth transitions

Resources

• Mapbox Expression Reference (opens in a new tab)
• ColorBrewer (opens in a new tab) - Color scales for maps
• Turf.js (opens in a new tab) - Spatial analysis
• Simple Statistics (opens in a new tab) - Data classification
• Data Visualization Tutorials (opens in a new tab)