Getting Started


The Raster component is responsible for initializing the mapbox-gl-js instance and making this available to any map layers rendered within it.


sourceURL pointing to Zarr group
variableName of array containing variable to map
climArray of limits for the color range, [min, max]
colormapArray of vec3 arrays, each representing an RGB value to sample from
selector(N/A for 2D datasets) Object to index into non-spatial dimensions, maps variable name (string) to value (any) or array of values
optional props
modeDisplay mode -- one of 'texture', 'grid', 'dotgrid''texture'
versionVersion of Zarr spec source data conforms to'v2'
projectionProjection in which source data is stored (independent of map rendering in Web Mercator)'mercator'
orderArray specifying whether the x, y dimensions are inverted from left -> right and top -> bottom, respectively[1, 1]
fillValueValue to map to null-9999
displayBoolean expressing whether contents should be drawn to canvas or nottrue
opacityNumber value for alpha value used when painting to canvas1
indexValue that, when changed, triggers a clear and redraw of the canvas0
regionOptionsObject containing a setData callback and an optional selector object (falls back to Raster-level selector if not provided)
fragFragment shader to use in place of default
uniformsObject mapping custom uniform names (string) to values (float) for use in fragment shader
setLoadingCallback to track any pending requests
setMetadataLoadingCallback to track any metadata and coordinate requests made on initialization
setChunkLoadingCallback to track any requests of new chunks
setMetadataCallback that is invoked with .zmetadata value once fetched


Single values

The selector prop is required for any dataset > 2D (dimensions other than lat, lng). This will commonly be wired up to user input. For example, rendering a single time point from a monthly dataset might look something like:

const [month, setMonth] = useState('January')
return (
<MonthInput value={month} onChange={setMonth} />
<Raster {...props} selector={{month}}>

Multiple values

You may also be interested in using multiple values along a particular dimension at once. You can include arrays of values in selector to handle this.

Each element in the values arrays selector is mapped and stored in a custom uniform for access in the fragment shader. For string array values, the value will be used directly. Otherwise, the array value will be appended to the selector. For example, {month: ['jan', 'feb', 'mar']} will generate the uniforms jan, feb, and mar while {month: [1, 2, 3]} will generate the uniforms month_1, month_2, and month_3.

Because the selector values dictate uniform definition, array-based selector values must not change between renders. Fully integrating with the selected values requires custom shader logic (see below).

Custom shader logic

You may provide custom fragment shader logic using the frag prop. This logic will have access to colormap, clim, fillValue, opacity, custom uniforms, and variables derived from data (variable for a 2D selection, otherwise following the logic in "Multiple values" above).

For example, a layer that allows user to select a subset of values to average over might look like:

selector={{measure: ['one', 'two', 'three']}}
include_one: range.includes('one') ? 1 : 0,
include_two: range.includes('two') ? 1 : 0,
include_three: range.includes('three') ? 1 : 0,
float sum = 0.0
if (include_one == 1.0) {
sum = sum + one;
if (include_two == 1.0) {
sum = sum + two;
if (include_three == 1.0) {
sum = sum + three;
float average = sum / (include_one + include_two + include_three)
float rescaled = (average - clim.x)/(clim.y - clim.x);
gl_FragColor = texture2D(colormap, vec2(rescaled, 1.0));

Regional data

See the RegionPicker docs for guidance using the regionOptions prop.


You may use any combination of the loading callback props to track the loading state of a particular Raster layer. The last value passed to each of the three callbacks, setLoading, setMetadataLoading, and setChunkLoading are overlaid on the map below.

CarbonPlan is a registered nonprofit public benefit corporation in California with 501(c)(3) status.
X,Y: 0000,0000