HOW to Use `env()` Parameters in GeoServer for Dynamic Labels

A Complete Guide for WMS + OpenLayers Users

1. Introduction

In modern Web GIS applications, users often need dynamic control over map labels—for example:

Switching label fields (name, population, category)
Changing font size or color from a UI
Improving readability using halos
Adjusting labels without creating multiple styles

GeoServer provides a powerful but safe mechanism for this using env() parameters in Styled Layer Descriptors (SLDs).

This article explains what env() is, why it exists, and how to use it step by step for dynamic labeling in WMS services.

2. What Are `env()` Parameters?

env() parameters are request-time variables that GeoServer allows you to pass into an SLD via a WMS request.

They act as controlled, named placeholders, not arbitrary URL parameters.

Key characteristics:

Evaluated at render time
Passed via &env=
Secure and cache-aware
Supported only where GeoServer explicitly allows them (e.g., labels, colors, sizes)

3. Why GeoServer Uses `env()` Instead of Arbitrary Parameters

GeoServer intentionally blocks arbitrary WMS parameters for styling because:

Arbitrary parameters break tile caching
They can introduce SQL or expression injection
They make styles unpredictable

env() is GeoServer’s safe compromise:

Flexible
Explicit
Controlled

4. When Should You Use `env()`?

Use env() when you need:

Dynamic label fields
UI-driven label changes
One reusable style instead of many
Server-side rendering (WMS)

Do not use env() if:

You need unlimited logic → use client-side (OpenLayers vector)
You need SQL-level changes → use PostGIS views

5. Basic Concept: How `env()` Works

General syntax in SLD:


<ogc:Function name="env">
  <ogc:Literal>parameter_name</ogc:Literal>
  <ogc:Literal>default_value</ogc:Literal>
</ogc:Function>

WMS request:


&env=parameter_name:value

If the parameter is not provided, GeoServer uses the default value.

6. Step-by-Step: Creating a Dynamic Label Style

Step 1: Create a New Style in GeoServer

Go to GeoServer → Styles
Click Add a new style
Name it: dynamic_label
Choose SLD

Step 2: Full Working SLD for Dynamic Labels

Example: Point Layer Labeling


<?xml version="1.0" encoding="UTF-8"?>
<StyledLayerDescriptor version="1.0.0"
                       xmlns="http://www.opengis.net/sld"
                       xmlns:ogc="http://www.opengis.net/ogc"
                       xmlns:xlink="http://www.w3.org/1999/xlink"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="http://www.opengis.net/sld
                                           http://schemas.opengis.net/sld/1.0.0/StyledLayerDescriptor.xsd">

  <NamedLayer>
    <Name>default_polygon</Name>

    <UserStyle>
      <Title>Default Polygon</Title>
      <Abstract>A sample style that draws a polygon</Abstract>

      <FeatureTypeStyle>
        <Rule>
          <Name>rule1</Name>
          <Title>Gray Polygon with Black Outline</Title>

          <!-- Polygon -->
          <PolygonSymbolizer>
            <Fill>
              <CssParameter name="fill">#cccccc</CssParameter>
            </Fill>
            <Stroke>
              <CssParameter name="stroke">#000000</CssParameter>
              <CssParameter name="stroke-width">1</CssParameter>
            </Stroke>
          </PolygonSymbolizer>

          <!-- Labels -->
          <TextSymbolizer>

            <Label>
              <ogc:Function name="property">
                <ogc:Function name="env">
                  <ogc:Literal>label_field</ogc:Literal>
                  <ogc:Literal>dist_name</ogc:Literal>
                </ogc:Function>
              </ogc:Function>
            </Label>

            <Font>
              <CssParameter name="font-family">Arial</CssParameter>
              <CssParameter name="font-size">
                <ogc:Function name="env">
                  <ogc:Literal>fontSize</ogc:Literal>
                  <ogc:Literal>11</ogc:Literal>
                </ogc:Function>
              </CssParameter>
            </Font>

            <Halo>
              <Radius>
                <ogc:Function name="env">
                  <ogc:Literal>haloSize</ogc:Literal>
                  <ogc:Literal>2</ogc:Literal>
                </ogc:Function>
              </Radius>
              <Fill>
                <CssParameter name="fill">
                  <ogc:Function name="env">
                    <ogc:Literal>haloColor</ogc:Literal>
                    <ogc:Literal>#ffffff</ogc:Literal>
                  </ogc:Function>
                </CssParameter>
              </Fill>
            </Halo>

            <Fill>
              <CssParameter name="fill">
                <ogc:Function name="env">
                  <ogc:Literal>fontColor</ogc:Literal>
                  <ogc:Literal>#000000</ogc:Literal>
                </ogc:Function>
              </CssParameter>
            </Fill>

            <VendorOption name="conflictResolution">true</VendorOption>

          </TextSymbolizer>
        </Rule>
      </FeatureTypeStyle>
    </UserStyle>
  </NamedLayer>
</StyledLayerDescriptor>

✔ Save

✔ Validate

✔ Assign to your layer

7. Passing `env()` Parameters in WMS Requests

Single parameter


&env=label_field:population

Multiple parameters


&env=label_field:population;fontSize:14;fontColor:#ff0000;haloSize:3

Rules:

Use semicolon (;) as separator
No spaces
Case-sensitive parameter names

8. Using `env()` with OpenLayers

OpenLayers WMS Source


const wmsSource = new ol.source.TileWMS({
  url: 'https://yourserver/geoserver/wms',
  params: {
    LAYERS: 'workspace:layername',
    STYLES: 'dynamic_label',
    env: 'label_field:name;fontSize:11'
  },
  serverType: 'geoserver'
});

Dynamically update labels


function updateLabel(field, size) {
  wmsSource.updateParams({
    env: `label_field:${field};fontSize:${size}`,
    _t: Date.now() // optional cache bust
  });
}

9. Scale-Dependent Dynamic Labeling

Add inside <Rule>:


<MinScaleDenominator>25000</MinScaleDenominator>
<MaxScaleDenominator>100000</MaxScaleDenominator>

This allows labels to:

Appear only at certain zoom levels
Reduce clutter
Improve performance

10. What Can Be Controlled with `env()`?

Property	Supported
Label field	✅
Font size	✅
Font color	✅
Halo size	✅
Halo color	✅
Rotation	✅
Visibility	✅

11. Limitations of `env()`

❌ Cannot inject SQL
❌ Cannot execute arbitrary functions
❌ Cannot override geometry
❌ Must be predefined in SLD

This is by design.

12. Performance & Caching Considerations

env() parameters are tile-cache aware
Different env values = different tiles
Use reasonable defaults
Avoid excessive variations

13. Best Practices

✔ Use one reusable SLD
✔ Always define default values
✔ Validate attribute names from UI
✔ Combine with scale rules
✔ Use halos for readability

14. Common Use Cases

Administrative boundary labels
City labels (name ↔ population)
Asset IDs vs asset names
Thematic maps with UI controls
Professional GIS portals

15. Conclusion

The env() function is the most powerful and safe way to achieve dynamic labeling in GeoServer WMS.

It provides:

Flexibility
Security
Performance
Clean architecture

For GeoServer + OpenLayers applications, env() Chould be your first choice for server-side dynamic styling.

IT and Web GIS Solutions

Search This Blog