HMLR Map Component

A flexible, OpenLayers-based mapping component for the GOV.UK Prototype Kit, with built-in support for British National Grid (BNG) projection and GeoJSON boundary visualization.

Features

British National Grid (EPSG:27700) projection support
GeoJSON boundary loading and visualization
Customizable styling with preset and custom color schemes
Multiple layers with individual styling and visibility controls
Interactive features with hover effects and click events
Flexible sizing and positioning options
Feature selection from GeoJSON collections

How to use

Install the package

First, install the package to your prototype. In terminal run the following command:

npm install hmlr-map

Import the Component

Set the values of the map in your HTML template. (This currently only works as a nunjucks macro):

{% from "hmlrMap.njk" import hmlrMap %}

Basic Example

{{ hmlrMap({
  alt: "Map of Plymouth",
  caption: "Example map with default settings"
}) }}

Configuration Options

All parameters are optional with defaults provided.

Basic Parameters

Parameter	Type	Default	Description
`alt`	String	-	Alternative text for accessibility
`caption`	String	-	Caption displayed below the map
`coords`	String	`248050, 53750`	Center coordinates in BNG format (Easting, Northing)
`zoom`	Number	`15`	Initial zoom level (1-18)
`use_draw_tools`	String	`"true"`	Enable drawing tools (requires separate components to set Drawing Mode)
`height`	String	`500px`	Map height (any valid CSS value)
`width`	String	`100%`	Map width (any valid CSS value)

Layer Configuration

Parameter	Type	Default	Description
`layers`	Array	`null`	Array of layer configuration objects (see Layer Options below)
`layer_controls`	String	`"false"`	Enable layer visibility checkboxes (`"true"` or `"false"`)
`tile_url`	String	OSM tiles	Custom base map tile URL (e.g., CartoDB, Mapbox)

Layer Options

Each layer in the layers array can have the following properties:

Property	Type	Default	Description
`path_to_geometry`	String	-	Path to GeoJSON file (required for each layer)
`description`	String	Filename	Label for layer control checkbox
`geometry_index`	Number	`null`	Select specific feature from collection (0-based index)
`interactive`	String	`"false"`	Enable click/hover interactions (`"true"` or `"false"`)
`style`	String/Object	`"BLUE"`	Layer styling (see Styling Options below)

Styling Options

Preset String Styles

Combine color and line style keywords (case-insensitive):

Colors:

"RED" - GOV.UK red (#d4351c)
"GREEN" - GOV.UK green (#00703c)
"BLUE" - GOV.UK blue (#003078)

Line Styles:

"DASH" - Dashed line [5, 5]
"DOT" - Dotted line [1, 5]

Special Styles:

"HIDDEN" - Invisible geometry (useful for interactive-only layers)
"HATCHED" - Diagonal line pattern fill (experimental)

Examples:

style: "RED DASH"
style: "GREEN"
style: "BLUE DOT"
style: "green HATCHED"
style: "hidden"

Custom Object Styles

For complete control, use an object with OpenLayers styling properties:

style: {
  fill: {
    color: "#d4351c33"  // RGBA hex: color + alpha (33 = 20% opacity)
  },
  stroke: {
    color: "#d4351c",
    width: 2,
    lineDash: [4, 4]  // [dash length, gap length]
  }
}

Color Format: Use RGBA hex format for transparency: #RRGGBBAA

Example: #d4351c33 = red with 20% opacity (33 hex = 51 decimal = 20%)
Hex to Percentage Converter

Examples

Example 1: Custom size and location

{{ hmlrMap({
  alt: "Map of Cornwall, showing a field north of Liskeard",
  caption: "Custom size, coordinates and zoom",
  coords: "225000, 65000",
  zoom: 15,
  height: "400px",
  width: "620px"
}) }}

Example 2: Loading external geoJSON

{{ hmlrMap({
  alt: "Map showing boundary data",
  caption: "Loading external GeoJSON with auto-fit",
  layers: [{
    path_to_geometry: "/public/data/boundary.json"
  }]
}) }}

Example 3: Custom styling

{{ hmlrMap({
  alt: "Map with custom styled boundary",
  caption: "Custom styling with dashed red line",
  coords: "225000, 65000",
  zoom: 15,
  layers: [{
    path_to_geometry: "/public/data/boundary.json",
    style: {
      fill: {
        color: "#d4351c33"
      },
      stroke: {
        color: "#d4351c",
        width: 2,
        lineDash: [4, 4]
      }
    }
  }]
}) }}

Example 4: Selecting a single feature using geometry_index

{{ hmlrMap({
  alt: "Single feature selection",
  caption: "Selecting feature 3 from a collection",
  layers: [{
    path_to_geometry: "/public/data/fields.json",
    geometry_index: 3,
    style: "BLUE"
  }],
  width: "100%",
  height: "390px"
}) }}

Example 5: Interactive hidden geometry

{{ hmlrMap({
  alt: "Interactive map",
  caption: "Hidden geometry with click events",
  zoom: 15.5,
  layers: [{
    path_to_geometry: "/public/data/overlaps.geojson",
    style: "hidden",
    interactive: "true"
  }]
}) }}

Example 6: Multiple layers with custom map tile and layer controls

{{ hmlrMap({
  alt: "Multi-layer map",
  caption: "Layered boundaries with visibility controls",
  layer_controls: "true",
  layers: [
    {
      path_to_geometry: "/public/data/inspire_data.geojson",
      description: "INSPIRE data",
      interactive: "true",
      style: {
        fill: { color: "#4c2c9222" },
        stroke: { color: "#4c2c9211", width: 0.5 }
      }
    },
    {
      path_to_geometry: "/public/data/layer1.geojson",
      style: {
        fill: { color: "#d4351c01" },
        stroke: { color: "#d4351c", width: 2 }
      }
    },
    {
      path_to_geometry: "/public/data/layer2.geojson",
      description: "Custom description",
      style: {
        fill: { color: "#00703c11" },
        stroke: { color: "#00703c", width: 2 }
      }
    },
    {
      path_to_geometry: "/public/data/layer3.geojson",
      description: "Blue boundary",
      style: "BLUE"
    }
  ],
  zoom: 14.5,
  tile_url: 'https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png'
}) }}

Example 7: Hatched fill

{{ hmlrMap({
  alt: "Map with hatched pattern",
  caption: "Experimental canvas hatching",
  layers: [{
    path_to_geometry: "/public/data/layer1.geojson",
    interactive: "true",
    style: "green HATCHED"
  }]
}) }}

Example 8: Drawing tools

{{ hmlrMap({
      alt: "HMLR map component",
      caption: "© Crown copyright and database rights 2025 Ordnance Survey AC0000000XXX. Use of this data is subject to Ordnance Survey",
      width: "100%",
      height: "100%",
      use_draw_tools: "true",
      layer_controls: "false",
      layers:[
        {
          description:"Registrations (INSPIRE)",
          interactive: "true",
          style: {
            fill: {
              color: "#4c2c9244"
            },
            stroke: {
              color: "#4c2c9299",
              width: 1
            }
          }
        },
          {
          description:"Postcode",
          style: {
            fill: {
              color: "#d4351c33"
            },
            stroke: {
              color: "#d4351c",
              width: 3,
              lineDash: [10, 6]
            }
          }
        }
      ],
      tile_url: 'https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png'
    }) }}

Interactive Features

Click Events

When a layer has interactive: "true", clicking on features dispatches a custom event:

document.addEventListener('hmlrMapClickEvent', (event) => {
  const feature = event.detail.message;
  console.log('Clicked feature:', feature);
  
  // Access feature properties
  const properties = feature.values_;
  console.log('Feature ID:', properties.INSPIREID);
});

Hover Effects

Interactive layers automatically show:

Cursor change to pointer
Highlight styling on hover
Click handling

Coordinate System

The component uses British National Grid (BNG) / EPSG:27700:

Easting: Horizontal position (typically 0-700000)
Northing: Vertical position (typically 0-1300000)
Format: "easting, northing" (e.g., 225000, 65000)

GeoJSON files must use BNG coordinates. The map automatically centers on loaded geometries if default coordinates are used.

GeoJSON Format

The component expects standard GeoJSON with BNG coordinates:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[...]]
      },
      "properties": {
        "INSPIREID": 12345,
        "name": "Property Name"
      }
    }
  ]
}

Dependencies

OpenLayers
Proj4js
GOV.UK Frontend (for styling)

License

This component is experimental and provided as-is for use with the GOV.UK Prototype Kit.

Support

For issues and questions, refer to the test prototype which includes working examples.

Version

Current version: 1.0.0 (Experimental)

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
assets		assets
macros		macros
.gitignore		.gitignore
eslint.config.mjs		eslint.config.mjs
govuk-prototype-kit.config.json		govuk-prototype-kit.config.json
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md

Folders and files

Latest commit

History

Repository files navigation

HMLR Map Component

Features

How to use

Install the package

Import the Component

Basic Example

Configuration Options

Basic Parameters

Layer Configuration

Layer Options

Styling Options

Preset String Styles

Custom Object Styles

Examples

Example 1: Custom size and location

Example 2: Loading external geoJSON

Example 3: Custom styling

Example 4: Selecting a single feature using geometry_index

Example 5: Interactive hidden geometry

Example 6: Multiple layers with custom map tile and layer controls

Example 7: Hatched fill

Example 8: Drawing tools

Interactive Features

Click Events

Hover Effects

Coordinate System

GeoJSON Format

Dependencies

License

Support

Version

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages