Skip to content

Styling

The MapLibre styling can be attached to a query via the style: key of the YAML front-matter.

---
style: ... your MapLibre style here ...
---
... your query here ...

The value of the style: key can contain:

  • a URL to a MapLibre style
  • a full MapLibre style object
  • a Ultra MapLibre style

Ultra MapLibre styles

In order to simplify the use of MapLibre styles, Ultra implements a number of features.

Query result styling

In order to allow for easy styling of the query results, Ultra allows you to specify a style with only the layer for your query results.

For example, to render query results with a purple MapLibre circle layer:

---
style:
  layers:
    - type: circle
      paint:
        circle-color: purple
---
nwr[shop]({{bbox}}); out center;

Extending a specific basemap style

To specify what style to add result styling to, use the extends key.

For example, to render the purple circles on the Protomaps light basemap:

---
style:
  extends: https://styles.trailsta.sh/protomaps-light.json
  layers:
    - type: circle
      paint:
        circle-color: purple
---
nwr[shop]({{bbox}}); out center;

Layer source & id

In the above examples, the layer definitions are lacking both source and layers keys.

Layers don't need to specify an ID, and if the source is not specified, it will be set to to the source containting the query results.

Automatic paint and layer keys

In order to reduce the mental overhead of remember what keys are paint options and which are layout options, Ultra will automatically move them from the layer object into the appropriate options object.

For example, the above purple circle layer can be implemented as:

---
style:
  layers:
    - type: circle
      circle-color: purple
---
nwr[shop]({{bbox}}); out center;

Sandwiching layers

In order to place your layers below existing style layers, you can use the beforeLayerId: key.

Example

PNG sprites via HTTPS

In order to facilitate adding icons to the map that don't exist in the basemap's sprites, if icon-image is set to an HTTPS URL to a PNG image, Ultra will automatically download it and add it to the Map's images.

Example

Bundled Sprites

In order to simplify the creation of POI maps, Ultra bundles the Maki and Temaki sprites and adds them to your style as SDFs allowing for easy styling of icons.

Example:

---
style:
  layers:
    - type: symbol
      icon-image: maki:bus
      icon-color: white
      icon-halo-color: '#6486f5'
      icon-halo-width: 5
---

Fallback fontstack

Since not all MapLibre styles have the same glyphs, Ultra will default to using Noto Sans Regular if the speficied(or default) fontstack is not available.