Restricting the map's extent

Often, there are situations where you are interested in showing data to the user, but only for a specific area, which your available data corresponds to (a country, a region, a city, and so on).

In this case, there is no point in allowing the user to explore the whole world, so you need to limit the extent the user can navigate.

In this recipe, we present some ways to limit the area that a user can explore. You can find the source code in ch01/ch01-map-extent/. We'll end up with a restricted extent of the USA like in the following screenshot:

How to do it…

1. Create the HTML to house the map and include the OpenLayers dependencies.
2. Create your JavaScript file and set up a geographic extent:

   var extent = ol.proj.transformExtent(
     [-125.0011, 24.9493, -66.9326, 49.5904],
     'EPSG:4326', 'EPSG:3857'
   ); 

3. Create the map instance with some layers and a restricted view, as follows:

   new ol.Map({
     layers: [
       new ol.layer.Tile({
         source: new ol.source.Stamen({
           layer: 'watercolor'
         })
       }),
       new ol.layer.Tile({
         source: new ol.source.Stamen({
           layer: 'terrain-labels'
         }),
         extent: extent
       })
     ],
     target: 'js-map',
     view: new ol.View({
       zoom: 6,
       minZoom: 5,
       center: [-12100000, 3400000],
       extent: extent
     })
   });

How it works…

When you launch this recipe on your web browser, you'll notice that you cannot pan outside the restricted extent. Let's take a look at how this was accomplished:

var extent = ol.proj.transformExtent(
  [-125.0011, 24.9493, -66.9326, 49.5904],
  'EPSG:4326', 'EPSG:3857'
);

We've put together a bounding box which covers the United States. This extent is in longitude and latitude coordinates, but the map view is in a different projection (EPSG:3857). We need to convert our longitude and latitude extent into the map view projection.

The ol.proj.transformExtent projection helper method provides such a utility. We pass in the array of coordinates as the first parameter. The second parameter informs OpenLayers that the provided coordinates are in longitude and latitude (EPSG:4326). The final parameter tells OpenLayers what we'd like the coordinates to be converted into (EPSG:3857). This returns with an ol.Extent array we can use on the map. We store this array in a variable, namely extent, as we'll use it in a few places around the code:

new ol.Map({
  layers: [
    new ol.layer.Tile({
      source: new ol.source.Stamen({
        layer: 'watercolor'
      })
    }),
    new ol.layer.Tile({
      source: new ol.source.Stamen({
        layer: 'terrain-labels'
      }),
      extent: extent
    })
  ],

When we create the new map instance, we make use of the Stamen tile services. The background layer is made up of the watercolor layer, and the foreground layer is made up from the terrain-labels layer.

For the terrain-labels layer, we restrict the extent of the layer with our custom bounding box. It means that this layer will not request for tiles outside this extent.

view: new ol.View({
  zoom: 6,
  minZoom: 5,
  center: [-12100000, 3400000],
  extent: extent
})

When we create the view, we pass our bounding box into the extent property of the view. Passing the extent to view is where the navigation restriction gets enforced. If we hadn't passed the extent to view, the user could pan around the map as they wish.

We also set minZoom to 5, which accompanies the extent restriction quite well. It prevents the user from zooming far out and beyond the USA (our extent). This retains the user within the points of interest.

See also

• The Moving around the map view recipe