# Map
<flow-map> The map component displays a map to build geospatial visualizations.
Use the map component, and its associated sub-components, to build a geospatial visualization. The resulting map supports zooming and panning, interactivity with map features and a range of styling options.
See the following sub-components for more details:
- Map Data Source - provides a source of geospatial data to display on the map.
- Map Layer - provides a styled visual map layer.
- Map Icon - registers a custom icon to use on the map.
- Map Data Join - specifies non-geospatial data to join to map features.
- Map Parameter - specifies additional parameters for data sources and data joins.
Combined with Flo.w RDF reactive state, the map components support a declarative approach to designing map-based visualizations.
# Building a Map
The two key parts of a map-based visualization are one or more geospatial data source provided by the Map Data Source component and one or more visible layers provided by Map Layer components to display geospatial data as points, lines, polygons, icons and text. By combining data sources and styling map layers complex geospatial visualization can be built.
See the [Designing a Map] guide for techniques and best practices (TBD).
# Choosing a Base Style
Specify which base map to use by specifying the map-style attribute. Four standard styles are provided by Flo.w, which can be selected when configuring a Flo.w application. The standard styles can also be customized.
positron- a minimal light base map style.darkmatter- a minimal dark base map style.fjord- a minimal blue base map style.osm-bright- a rich base map style showing amenities, land type, transport hubs etc.
map-style can also be set to an external URL returning a complete Maplibre style specification (opens new window) in JSON format. For example:
<!-- A Location Insights Explorer map -->
<flow-map
map-style="https://locationinsights.co.uk/maps/50a23b94-249f-488e-9dbc-8b44143f1669/style.json"...>
</flow-map>
<!-- A Mapbox studio map -->
<flow-map
map-style="mapbox://styles/robinsummerhill/cj85rkv1v1yi92rk2h6qn1j0u?access_token=pk.eyJ1Ijoicm9iaW5zdW1tZXJoaWxsIiwiYSI6IndJNjdoc1UifQ.uKj4tO3T3wlFFCwcJLJlTg"...>
</flow-map>
# Map Control Slots
Use HTML slots to add controls, headers and footers to the map. See the example below.
Four control slots are available for adding control content to the map:
top-lefttop-rightbottom-leftbottom-right
TIP
When placed within a Drawer Container component, map slots will reposition to accommodate open drawers.
# Interactivity
Add event listeners to the map to handle interaction events such as clicking or double-clicking on map features. By default, click events and feature hover effects are generated for all map layers. To disable interactivity for a particular layer, set the interactive map layer attribute to false.
# Hover Styling
By default, the mouse cursor changes to a pointer when hovered over a map feature on an interactive layer. It is also possible to style the hovered feature using the feature state property @@hover, which is applied automatically.
# Programmatic Control of the Map
Common methods for controlling the map programmatically are available on the Map component itself. For greater control, you can access the lower-level FlowCoreMap JavaScript instance or the underlying Maplibre GL JS (opens new window) instance.
Using the Maplibre GL JS instance, you have full access to the Maplibre GL JS Map API (opens new window). Note, however, that certain operations such as modifying layers will be overwritten by Flo.w RDF map updates.
// Get FlowCoreMap instance by name from map registry.
const flowCoreMap = await context.maps.getMap('map1');
// Get FlowCoreMap instance from Map component
const flowCoreMap = await document.getElementById('map1').getMap();
// Access Maplibre GL JS map instance
flowCoreMap.maplibreMap.fitBounds([[-1, 51], [0, 52]], {padding: 20});
# Examples
# Map Control Slots
The example below demonstrates the use of map control slots to add controls, headers and footers to a map.
# Map Popups
The example below demonstrates how to display a popup when a feature is clicked.
The popup template is defined using a Map Popup component. A Data Table component is used in the popup template to display a table of the selected feature's properties.
The circles map layer is also styled to indicate the selected feature using the feature state property @@selected.
# Hover Styling
Use the feature state property @@hover to style hovered features. Note that the feature-id attribute must be specified to ensure each feature is uniquely identifiable.
# Programmatic Control of the Map
The example below shows how to get access to the full API of the underlying Maplibre GL JS map instance. Click the button to set the pitch of the map.