This is the technical documentation for the “layers” block in Tangram’s scene file. For a conceptual overview of the way Tangram applies styles to data, see the Filters Overview and the Styles Overview.

layers

The layers element is a required top-level element in the scene file. It has only one kind of sub-element: a layer name, which defines individual layers with a layer filter.

layers:
    earth:
        ...

layer name

Required string. Can be anything. No default.

layers:
    landuse:
        ...

Note: If a layer filter is not specified in a data parameter, Tangram will attempt to use the layer name as the filter. See Layer Name Shortcut.

layer parameters

data

Required parameter. Defines the beginning of a data block. Usable by top-level layers only. No default.

layers:
    landuse:
        data: { source: osm }

filter

Optional object or function. No default.

A filter element may be included once in any layer or sublayer. Only features matching the filter will be included in that layer (and its sublayers). For more on the filtering system, see Filters Overview.

layers:
    roads:
        data: { source: osm }
        filter: { kind: highway }

enabled

Optional Boolean. Allows layer to be turned off and on. Default is true.

layers:
    landuse:
        data: { source: osm }
        enabled: false

Unlike the draw-level visible parameter, once set, the enabled parameter cannot be overridden by any descendant layers. This is useful for culling large portions of the layer tree, e.g. for layer-toggle controls and/or overlays.

[This parameter was renamed from visible to avoid confusion with the -draw-level visible parameter. Layer-level visible parameters will be supported through v0.12, but will be deprecated in a future release.]

draw

Required parameter. Defines the beginning of a draw block. For draw parameters, see the draw entry.

layers:
    landuse:
        data: { source: osm }
        draw:
            ...

sublayer name

Optional string. Can be anything except the other sublayer parameters: “draw”, “filter”, and “properties”. No default.

Defines a sublayer. Sublayers can have all layer parameters except data, and can be nested.

All parameters not explicitly defined in a sublayer will be inherited from the parent layer, including draw, properties, and filter definitions. Note that filter objects in different sublayers may match simultaneously – see the Filters Overview.

layers:
    landuse:
        data: { source: osm }
        filter: ...
        draw: ...
        sublayer:
            filter: ...
            draw: ...
        sublayer2:
            filter: ...
            draw: ...
            subsublayer:
                filter: ...
                draw: ...

data parameters

source

Required string, naming one of the sources defined in the sources block.

data:
    source: osm

layer

Optional string or [strings], naming a top-level named object in the source datalayer. In GeoJSON, this is a FeatureCollection. If a layer is not specified, the layer name will be used.

data:
    source: osm
    layer: buildings

The above layer refers to the below object:

{"buildings":
    {"type":"FeatureCollection","features":[
        {"geometry":"..."}
    ]}
}

Because the layer name is the same as the name of the GeoJSON object, the data object’s layer parameter can be omitted. Most of our examples, use this form.

layer:
    buildings:
        data: { source: osm }

When an array of layer names may is used as the value of the layer parameter, the corresponding data layers will be combined client-side. This allows easy styling of multiple layers at once:

layer:
    labels:
        data: { source: osm, layer: [buildings, pois] }
        filter: { name: true }
        draw:
            text:
                ...

The above example combines the “buildings” and “pois” layers into a new layer called “labels”, for drawing with the text draw style.

draw parameters

See the draw entry.