Grafu Maps

A React component library for building interactive map visualizations, including pre-built map layers, deck.gl integrations, and utilities for geospatial data rendering. Leverages Material UI for styled components, and DeckGL and Mapbox for mapping components.

A product of the SimonComputing Technology Innovations Lab

Installation

# Use NPM, yarn, or PNPM
npm install @simoncomputing/grafu-base
npm install @simoncomputing/grafu-maps

Required Peer Dependencies

The maps and custom layers are built on deck.gl and Mapbox. At a minimum, this library requires installing these packages:

# DeckGL
npm install @deck.gl/core@^9.1.14
npm install @deck.gl/layers@^9.1.14
npm install @deck.gl/react@^9.1.14
npm install @deck.gl/widgets@^9.1.14

# Mapbox
npm install mapbox-gl@^3.14.0

# Material UI
npm install @mui/material@^6.5.0
npm install @emotion/react@^11.14.0
npm install @emotion/styled@^11.14.0

Styling

The following stylesheet must be linked in your index.html:

<link href="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css" rel="stylesheet" />

Basic Example

const props = {
    featureType: 'state',
    data: [
        { value: 1, group: 'VA'},
        { value: 2, group: 'MD'},
        { value: 0, group: 'PA'},
        { value: 3, group: 'NY'},
    ]
}

<BaseMap
    mapboxToken={getMapboxToken()}
    layers={[new GeoFeatureShadeLayer(props)]}
/>

Documentation & Demo

This project uses Storybook to document and demonstrate the components. URL COMING SOON.

Release History

Details for every release are documented in CHANGELOG.md

Exports

Components

BaseMap is the primary export of this package — a fully styled, interactive map component with built-in support for custom user interactions. More documentation can be found here

To assist in creating custom map components in your application, the following components are also exported:

1. LayerSelectorButton
2. StyleSelectorButton
3. ZoomControl
4. MapLegendPanel
5. MapTooltip
6. MapActionContainer

Layers

Grafu Maps ships a collection of map layers built on top of DeckGL, abstracting away common boilerplate so you can get a map up and running with minimal configuration.

Documentation can be found here

Utilities

To assist state management for custom map components, 2 hooks are exported from the library:

1. useMapLayers: layer management
2. useMapView: view management

The are also exported helpers useful for handling:

1. State data
2. Region data
3. County, State, Region, and Country topology for geo feature
4. Aggregating data on specific key