Reference
Layer Styles

Layer Styles

MapsGL layer styles are fully customizable and support a variety of options depending on the type of data being rendered.

The following layer render styles are supported:

  • raster: Renders static raster imagery
  • fill: Renders vector polygon geometry as filled shapes
  • stroke: Renders vector polygon and polyline geometry as lines
  • circle: Renders vector points as circles
  • symbol: Renders vector points as images, glyphs or custom GLSL shaders
  • sample: Renders encoded data by sampling values and colorizing them based on a color scale
  • grid: Renders a grid of points as symbols by sampling encoded data at those grid points
  • contour: Renders isolines by sampling encoded data
  • particle: Renders vector data, such as wind speed or ocean currents, as particle flow fields
  • heatmap: Renders the density of vector point data

Layer paint styles are defined using the paint property when configuring your layer. Each style type listed above should be provided as its own property in your paint object:

paint: {
	opacity: number;
 
	// Specific render style options
    raster: Partial<RasterStyleSpec>;
    fill: Partial<FillStyleSpec>;
    stroke: Partial<StrokeStyleSpec>;
    circle: Partial<CircleStyleSpec>;
    symbol: Partial<SymbolStyleSpec>;
    sample: Partial<SampleStyleSpec>;
    grid: Partial<GridStyleSpec>;
    contour: Partial<ContourStyleSpec>;
    particle: Partial<ParticleStyleSpec>;
    heatmap: Partial<HeatmapStyleSpec>;
}
OptionDescriptionDefault
opacityType: number ()Opacity the entire layer will be drawn.1

See each supported style type below for the available customization options and their defaults.

Raster

Raster style properties control how raster tiles get rendered on a map, such as static image tiles like PNG or JPG.

raster: {
	opacity: number;
}
OptionDescriptionDefault
opacityType: number ()Opacity the image will be drawn.1

Fill

Fill style properties control how one or more polygons (and associated outlines) get rendered on a map. These properties also control the fill for circles and other vector shapes.

fill: {
	color: string | Color;
	opacity: number;
}
OptionDescriptionDefault
colorType: string or Color ()Color of the fill. Value can be a hex color code or in the form of rgba() to adjust the opacity of the fill without affecting the stroke opacity.#000000
opacityType: number ()Opacity of the fill layer, including any stroke associated with the geometry.1

Stroke

Stroke style properties control how one or more polylines get rendered on a map. These properties also control strokes around circles and other vector shapes.

stroke: {
	color: string | Color;
	thickness: number;
	opacity: number;
	lineJoin: 'bevel' | 'round' | 'miter';
	lineCap: 'butt' | 'round' | 'square';
}
OptionDescriptionDefault
colorType: string or Color ()Color of the stroke. Value can be a hex color code or in the form of rgba() to adjust the opacity of the stroke without affecting the opacity of other lines in the same layer.#000000
thicknessType: number ()Line thickness in points.2
opacityType: number ()Opacity of the stroke layer.1
lineJoinType: bevel, round or miter ()Controls the method of how lines are joined:
- bevel: Squares off the edges of a segment by extending the line a distance of one-half the line's width beyond the segment endpoint.
- round: Rounds off the corners of a segment by filling half a circle centered at the common endpoint of connected segments. The radius for these rounded corners is equal to one-half the line width.
- miter: Connected segments are joined by extending their outside edges to connect at a single point, with the effect of filling an additional lozenge-shaped area.
round
lineCapType: butt, round or square ()Controls the method of how the ends of lines are drawn:
- butt: Squares off the ends of a line at the exact endpoint of the line.
- round: Rounds off the ends of a line by filling half a circle centered on the line's endpoints. The radius for these rounded corners is equal to one-half the line width.
- square: Squares off the ends of a line by extending the line a distance of one-half the line's width beyond the endpoints.
round

Circle

Circle style properties control how circles get rendered on a map. Use these properties in conjunction with fill and stroke above to define the style for a circle layer.

circle: {
	radius: number;
}
OptionDescriptionDefault
radiusType: number ()Radius of the circle in points.6

Symbol

Symbol style properties control how icons, glyphs or instanced geometries get rendered on a map. Custom WebGL fragment shader programs can be provided for highly custom visualizations and effects for each instance on the map.

symbol: {
	size: { width: number; height: number; };
	anchor: '';
	offset: { x: number; y: number; };
	rotation: number;
	animated: boolean;
	shader: string;
	uniforms: Record<string, any>;
	factor: number;
	billboard: boolean;
	atlas: TextureAtlas;
}
OptionDescriptionDefault
sizeType: { width: number; height: number; } ()Size of the symbol in screen points.{ width: 20, height: 20 }
anchorType: top-left, top, top-right, left, center, right, bottom-left, bottom, or bottom-right ()Determines the point from which rotations take place.center
offsetType: { x: number; y: number; } ()Symbol translation relative to its map position in screen points.{ x: 0, y: 0 }
rotationType: number ()Symbol rotation in radians. Rotation will take place around the symbol's configured anchor point.0
animatedType: boolean ()Whether the symbol is animated. For performance optimizations, only set this to true if you are using a custom shader program that requires animation.false
shaderType: string ()A custom WebGL fragment shader (opens in a new tab) used to render the symbol.
uniformsType: Record<string, any> ()An object containing a set of uniforms and their values when using a custom shader for rendering the symbol.
factorType: number ()A value that can be assigned per instance based on the underlying data for that instance. This value is assigned as a uniform for the WebGL program and can be used in custom shaders to customize rendering based on each instance's factor value.1
billboardType: boolean ()Determines whether the symbol always faces the camera regardless of the camera's pitch or rotation. If false, the symbol faces up so that it always appears on the map surface.false

Sample

Sample style properties control how encoded data gets rendered on a map. Sample rendering is performed by sampling values from the underlying data and mapping it to a desired result, such as color fill, contour line, etc.

sample: {
	expression: 'number' | 'vector' | 'sum' | 'diff';
	channel: 'r' | 'g' | 'b' | 'a' | 'rg' | 'gb' | 'rb' | 'ra' | 'ga' | 'ba' | 'rgb' | 'gba' | 'rgba';
	quality: DataQuality;
	interpolation: InterpolationMode;
	smoothing: number;
	colorscale: {
		stops: Array<number | string>;
		interval: number;
		range: { min: number; max: number; };
		interpolate: boolean;
		normalized: boolean;
	};
	opacity: number;
	multiband: boolean;
	offset: number;
	meld: boolean;
	drawRange: { min: number; max: number; };
}
OptionDescriptionDefault
expressionType: number, vector, sum, or diff ()Determines how data should be sampled from the encoded data texture:
- number: Value is a float sampled from a single band.
- vector: Value is a vector sampled and calculated from two bands.
- sum: Value is a float sampled and calculated as the sum of two bands.
- diff: Value is a float sampled and calculated as the difference of two bands.
number
channelType: string ()Color band(s) to sample from the encoded data. If performing an expression operation, such as vector, sum or diff, then two bands must be provided.r
qualityType: DataQuality ()Controls the data resolution that gets requested by the layer's data source and rendered to the map. Data will be interpolated when rendering to the map to ensure low resolution/quality data is still smooth. Supported data quality values include:
- exact: Data tiles will be requested and rendered 1:1 with map tiles and zoom level. This setting results in the highest data resolution but the lowest bandwidth and rendering optimization.
- high: Data will be scaled slightly to share the same data tiles across 1 or 2 map zoom levels.
- medium: Data will be minimally scaled resulting in slightly higher data resolution than normal at some map zoom levels.
- normal: Data will be scaled to share the same data tiles across multiple map zoom levels. This setting provides a good balance between data resolution and reduced request bandwidth and rendering performance.
- low: Data will be moderately scaled resulting in slightly less data resolution than normal at some map zoom levels.
- minimal: Data will be scaled extensively to share the same data tiles across 3-5 map zoom levels. This results in drastically reduced data resolution but the highest bandwidth and rendering optimization.
DataQuality.normal
interpolationType: InterpolationMode ()Type of interpolation to perform on the data. Supported data interpolation values include:
- none: Disables interpolation and renders the data at its native resolution, which will often result in blocky and pixelization.
- bilinear: Renders data using bilinear interpolation which is the most performance but often results in artifacts and blockiness depending on the data.
- bicubic: Renders the data using bicubic interpolation which provides the smoothest output.
- biquadratic: Renders the data using biquadratic interpolation which can result in better output than bilinear. This interpolation value is rarely used in favor of bicubic.
InterpolationMode.bilinear
smoothingType: number ()Amount of smoothing to apply on the data from 0 (no smoothing) to 1 (full smoothing). Increasing this value is useful for low resolution data sets or when higher detail is not desired or needed.0
colorscaleType: object ()Defines how pixels get rendered based on the encoded data.
colorscale.stopsType: Array<number | string> ()Defines the color scale used to color pixels based on the underlying data values or as normalized values (from 0 to 1). Value should be provided in value, color pairs for each color stop, where value is the value (interpolated position) for that color stop, and color is a hexidecimal color string, rgba() value, or Color instance.[0, '#000', 1, '#ff0000']
colorscale.intervalType: number ()Interval for which color stops are desired within the data range. This value must be in the same unit as the values provided in colorscale.stops and the encoded data. If set to 0, then the color scale will be linearly interpolated between color stops to produce a smooth gradient.0
colorscale.rangeType: { min: number; max: number; } ()Defines the data range the color scale represents.{ min: 0, max: 1 }
colorscale.interpolateType: boolean ()Whether color values between the defined color stops should be interpolated. If true, then colors will be linearly interpolated and appear more gradient-like. If false, then values in between color stops will use the next lowest color stop resulting in only the provided color stops being rendered.true
colorscale.normalizedType: boolean ()Whether the color scale should be calculated using normalized values, meaning in the range of 0 and 1 regardless of the underlying encoded data. This is useful when wanting to apply a simple color scale whose stops are not tied to specific data values.false
opacityType: number ()Overall opacity of the sample fill layer.1
offsetType: number ()Normalized amount to shift the interpolated sample values from 0 to 1. This is typically used for expression operations like diff where interpolated values can be negative and you need to start values half way (0.5) between the colorscale.range.0
meldType: boolean ()Whether data should be interpolated between intervals during animation playback. If true, then data will smoothly transition between data intervals, otherwise the result will appear stepped.true
drawRangeType: { min: number; max: number; } ()Limits the data range that should be rendered from the sampled data. If not provided, then the full data range will be rendered by default.

Grid

Grid style properties control how gridded content gets rendered on a map. Grid layers will render a grid of symbols or text in a grid layout and sample underlying encoded data at each grid point to determine how each symbol is displayed. Symbol instances rendered at grid points are projected in screen space, not map space, which means they will remain the same size on screen regardless of map zoom level.

grid: {
	symbol: 'arrow' | 'wind-barb';
	spacing: number;
}
OptionDescriptionDefault
symbolType: arrow, or wind-barb ()The built-in symbol type to render in the grid.arrow
spacingType: number ()Spacing between grid points at whole number map zoom levels (e.g. 3, or 10, not 3.487). A lower spacing value will result in a higher density of symbol instances.30

Since a grid layer simply renders a series of symbol instances in a grid format, see the symbol style options as well for controlling what gets rendered.

Particle

Particle style properties control how flow field particles get rendered on a map. Particles are used to represent vector data and flow fields, such as wind speed and direction or ocean waves and currents.

particle: {
	count: number;
	density: ParticleDensity;
	size: number;
	speed: number;
	trails: boolean;
	trailsFade: number;
	dropRate: number;
	dropRateBump: number;
}
OptionDescriptionDefault
countType: number ()Total number of particles to render for a single particle tile where a single particle tile is typically used for the visible map region. Keeping this value as a power-of-two will result in the best performance (e.g. 1024, 4096, 16384, 65536 or 262144.65536
densityType: ParticleDensity ()An alternative to count that controls the total number of particles to render. Where count will always show the same number of particles regardless of map viewport size, density will automatically calculate the number of particles based on the viewport size in order to maintain a relatively consistent density across viewports and screen sizes. Supported density values include:
- count: Falls back to the count value.
- minimal: Least amount of particles will be rendered. This density setting may not provide enough speed and direction information on the map since coverage is minimal.
- low: Slightly less particle density than normal, allowing the most visibiilty to content underneath while providing good speed and direction information.
- normal: Provides a good amount of particles and speed and direction information while still allowing a good portion of content underneath to remain visible.
- high: Slightly higher particle density than normal while still allowing some content underneath to remain visible.
- extreme: Highest density that will essentially fill the layer with particle data, preventing content underneath from being visible. Note that overall map performance may be affected with this setting for some hardware configurations.
ParticleDensity.count
sizeType: number ()Size of the particles in screen points.2
speedType: number ()Speed factor of the particle movement. A value of 1 will use the default speed.1
trailsType: boolean ()Whether or not particle trails should be rendered. If false, then only the particles and their current positions will be rendered.true
trailsFadeType: number ()Amount particle trails should fade between frames between 0 and 1. A higher value will result in particle trails fading out slowly and longer trails, whereas lower numbers will result in shorter trails.0.98
dropRateType: number ()Rate at which a particle will restart at a random position to avoid degeneration. A higher drop rate will result in faster repositioning and less overall movement.0.01
dropRateBumpType: number ()Factor applied to the dropRate and calculated velocity to further control the overall particle drop rate.0.01

Contour

Contour style properties control how contoured data gets rendered on a map. Contour layers are rendered by sampling encoded data and interpolating values in real-time.

contour: {
	interval: number;
	majorInterval: number;
}
OptionDescriptionDefault
intervalType: number ()Determines the value interval for which to draw contour lines for. This value must be in the same units as the data source.1
majorIntervalType: number ()Determines the value interval for which to draw major, or thicker, contour lines for. If this value is 0, then major contour lines will not be rendered. This value must be in the same units as the data source.0

Heatmap

Heatmap style properties control how the density of points in an area gets rendered on a map.

heatmap: {
	color: Array<number | string>';
	radius: number;
	blur: number;
	intensity: number;
	weight: number;
	opacity: number;
}
OptionDescriptionDefault
colorType: Array<number | string> ()Defines the normalized (0 to 1) color scale used to color pixels based on its density value, where 0 is none and 1 being the highest density.
radiusType: number ()Radius of influence of each data point in screen points.20
blurType: number ()Controls how much to fade out the edges of each point based on its radius, reducing its overall influence on neighboring points.1
intensityType: number ()Value that is multiplied with the weight value to calculate the final weight of a point. A value larger than 1 biases the output color towards the higher end of the color scale, whereas a value less than 1 biases the output color towards the lower end of the color scale.1
weightType: number ()Amount of weight to give each point.1
opacityType: number ()The overall opacity of the layer.1

The default color scale used for the color property is:

[
    0, 'rgba(0, 0, 0, 0)',
    0.2, 'rgba(0, 0, 255, 0.2)',
    0.45, 'rgba(0, 255, 0, 0.5)',
    0.85, 'rgba(255, 255, 0, 1)',
    1, 'rgba(255, 0, 0, 1)'
]