More powerful ways to custom style spatial data
By: Anand Thakker
Today we’re introducing Mapbox GL expressions, available in the latest version of Mapbox GL JS (v0.41.0). Expressions build on data-driven styling, a feature that allows you to dynamically style spatial data based on its properties. Use expressions to take data-driven styling one step further with more flexible and powerful operations. Style data with multiple feature properties at once, apply conditional logic, and manipulate data with arithmetic and string operations for a more sophisticated relationship between your data and how it is styled.
Previously, a data-driven (or zoom-driven) style property was defined using a stop function — essentially a “ramp” relating a feature property or zoom value to style values. For example, here’s how you would style color circles on a green-to-red scale based on a feature’s danger property:
Stop functions enable dynamic, finely-tuned map designs that take advantage of rich vector data, but they do have some limitations:
- One property at a time: Property functions, like the one above, can only reference a single feature property, so the only way to make use of multiple properties in your data using stops is to make multiple layers.
- Simple input-output pairs: Stop functions are, by definition, based on a simple set of input-output pairs. This means that more complex control, for example, using arithmetic or conditional logic, isn’t possible.
Enter expressions
We built expressions to remove these limitations. Expressions enable us to specify not just a set of input-output pairs, but also many other kinds of relationships between the input and output, including arithmetic operations, string transformations, and conditional logic. Here are some examples of how they go beyond what stop functions can do.
Arithmetic
Sometimes, you need to do a little math. A classic example is when you’re visualizing quantitative data with circles. Since a circle’s visual size on the screen is really its area, the right way to scale circle-radius is with the square root of the input data. With expressions, this is quite straightforward:
Below, I’ve created a map that styles population data using this expression. Check out more examples of what’s possible with expressions in this tutorial.
In this map, the expression is saying, “make the circle radius the square root of the population feature (scaled down to 10,000s of persons).” Compare this with how we’d have to do it before using stop functions:
The designer’s intent is much less clear here. Also, the result is inaccurate because this function must be defined using a fixed number of stops; the actual circle size for a feature with, say, population: 3000000 would have to be interpolated between 10 and 31.6.
Conditional logic
A common challenge in designing and building maps is handling inconsistent data. Suppose you want to use bilingual labels for place names on your map, but your data includes some features with both a local name and an English one, some with only a local name, and others with only an English name. Specifying how your labels should work in each of these cases is straightforward with the new expressions syntax:
As in the previous example, there is a way to achieve approximately the same result without expressions, but it has real drawbacks. In this case, it would require using three separate (but repetitive) layers, and that number would only increase if we tried to accommodate more languages or more sophisticated rules.
What does this mean for developers and designers?
Data-driven styling is a powerful tool for making dynamic, highly individualized map styles, especially for building maps with large or complex datasets. With the launch of expressions, we’re amplifying this power. Check out the Mapbox GL style specification for the full list of expressions and an extensive list of all of the different style properties they let you control. We’re excited to see what you design with expressions.
Please note that existing style sheets will continue to work as before, including those that use stop-based functions. In the coming months, we’re also planning to roll out support for expressions in our Mobile SDKs and in Mapbox Studio. Mobile developers using runtime styling APIs will need to update their code to expressions in order to start using the next major SDK release, launching in the coming months. Stay tuned for more updates on using expressions for mobile.
Get started using expressions
Check out this tutorial to get moving fast. The Mapbox GL style specification docs include a full list of available expressions. You can use this quick interactive tool to see how you can convert stop functions in your existing styles into expressions.
Show us what you build with expressions on Twitter using the tag #BuiltWithMapbox, or ping me with any questions or ideas!
Announcing Expressions in GL JS was originally published in Points of interest on Medium, where people are continuing the conversation by highlighting and responding to this story.