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 basic 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
• sample: Renders encoded raster data by sampling values and colorizing them based on a color scale
• grid: Renders a grid of points as symbols by sampling encoded raster data at those grid points
• contour: Renders isolines by sampling encoded raster data
• particle: Renders vector data from encoded rasters, such as wind speed or ocean currents, as particle flow fields
• heatmap: Renders the density of vector point data
• icon: Renders vector point features as images custom GLSL shaders
• text: Renders text labels from vector point features
• symbol: Controls how icons and text elements are placed on the map

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>;
    sample: Partial<SampleStyleSpec>;
    grid: Partial<GridStyleSpec>;
    contour: Partial<ContourStyleSpec>;
    particle: Partial<ParticleStyleSpec>;
    heatmap: Partial<HeatmapStyleSpec>;
	icon: Partial<IconStyleSpec>;
	text: Partial<TextStyleSpec> | Array<Partial<TextStyleSpec>>;
	symbol: Partial<SymbolStyleSpec>;
}

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: {}

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;
}

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';
}

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;
}

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; };
		normalized: boolean;
		interpolate: boolean;
	};
	multiband: boolean;
	offset: number;
	meld: boolean;
	drawRange: { min: number; max: number; };
}

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: {
	spacing: number;
}

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: {
	type: 'circle' | 'bar';
	count: number;
	density: ParticleDensity;
	size: number;
	speedFactor: number;
	trails: boolean;
	trailsFadeFactor: number;
	dropRate: number;
	dropRateBump: number;
}

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;
}

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;
}

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)'
]

Icon

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.

icon: {
	image: string | { id: string; url: string; sdf?: boolean; };
	atlas: { ids: Array<string>; interval?: number; };
	size: { width: number; height: number; };
	anchor: 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
	offset: { x: number; y: number; };
	padding: number | [number, number];
	rotation: number;
	animated: boolean;
	shader: string;
	shaderOnBeforeCompile: (shader: { vertex: string; fragment: string }) => void;
	uniforms: Record<string, any>;
	factor: number;
}

Text

Text style properties control how text gets rendered on a map from vector features. Use these properties on conjunction with symbol to define the style for a text layer.

text: {
	value: string | { 
		property: string | Array<string>; 
		transform?: (value: string | number, units?: string) => string | number; 
	};
	size: number;
	font: string;
	weight: 'normal' | 'bold';
	color: string | Color;
	outlineColor: string | Color;
	opacity: number;
	align: 'left' | 'center' | 'right';
	transform: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
	anchor: 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
	offset: { x: number; y: number; };
	rotation: number;
	letterSpacing: number;
	lineHeight: number;
	maxWidth: number;
}

Multiple text labels per feature

Multiple text labels can be rendered for a single feature by providing an array of text style objects in the text property of the layer's paint object. Each text style object should contain the same properties as a single text style object, but with different values for each text label. This is useful for rendering multiple data-driven text labels for a single feature, such as a city name and population, where each can be configured with different styles:

text: [
	{
		value: { 
			property: 'name' 
		},
		size: 13,
		weight: 'bold',
		align: 'center',
		anchor: 'center'
	},
	{
		value: { 
			property: 'population', 
			transform: (value) => {
				const pop = value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
				return `Population: ${pop}`;
			}
		},
		size: 10,
		color: '#333',
		transform: 'uppercase',
		anchor: 'top',
		offset: { x: 0, y: 10 },
		letterSpacing: 0.1
	}
]

Symbol

Symbol style properties are applied to icon and text elements and control how they get placed on a map. These properties include controlling whether symbols can overlap with each other and/or other layer symbols, how they pitch and rotate with the map, etc.

symbol: {
	key: string;
	rank: string | { property: string; direction: 'asc' | 'desc'; };
	fadeOpacity: boolean;
	pitchWithMap: boolean;
	rotateWithMap: boolean;
	sizeAttenuation: boolean;
	allowOverlap: boolean;
	overlapMode: 'layer' | 'map';
}