Skip to content

Latest commit

 

History

History
412 lines (244 loc) · 13.9 KB

interactive-map.md

File metadata and controls

412 lines (244 loc) · 13.9 KB

default (InteractiveMap)

Since v3.0

This component renders MapboxGL and provides full interactivity support. It uses StaticMap underneath to render the final map component. This is the default exported component from react-map-gl.

import * as React from 'react';
import ReactMapGL from 'react-map-gl';

function App() {
  const [viewport, setViewport] = React.useState({
    longitude: -122.45,
    latitude: 37.78,
    zoom: 14
  });
  return (
    <ReactMapGL {...viewport} width="100vw" height="100vh" onViewportChange={setViewport} />
  );
}

Properties

Initialization

Inherit the following props from StaticMap:

  • attributionControl (Boolean)
  • disableTokenWarning (Boolean)
  • gl (WebGLContext)
  • mapboxApiAccessToken (String)
  • mapboxApiUrl (String)
  • mapOptions (Object)
  • preserveDrawingBuffer (Boolean)
  • preventStyleDiffing (Boolean)
  • reuseMaps (Boolean)
  • transformRequest (Function)

Map State

Inherit the following props from StaticMap:

  • mapStyle (String | Object | Immutable.Map)
  • width (Number | String)
  • height (Number | String)
  • latitude (Number)
  • longitude (Number)
  • zoom (Number)
  • bearing (Number)
  • pitch (Number)
  • altitude (Number)
  • viewState (Object)

Render Options

Inherit the following props from StaticMap:

  • style (Object)
  • visible (Boolean)
  • visibilityConstraints (Object)
getCursor (Function)

Accessor that returns a cursor style to show interactive state. Called when the component is being rendered.

Parameters

  • state - The current state of the component.
    • state.isDragging - If the map is being dragged.
    • state.isHovering - If the pointer is over an interactive feature. See interactiveLayerIds prop.

The default implementation of getCursor returns 'pointer' if isHovering, 'grabbing' if isDragging and 'grab' otherwise.

Interaction Options

maxZoom (Number)
  • default: 20

Max zoom level.

minZoom (Number)
  • default: 0

Min zoom level.

maxPitch (Number)
  • default: 85

Max pitch in degrees.

minPitch (Number)
  • default: 0

Min pitch in degrees.

scrollZoom (Boolean|Object)
  • default: true

Enable scroll to zoom. If an object is provided, may contain the following options to customize the scroll zoom behavior:

  • speed (Number) - Multiplier for the wheel delta. Default 0.01.
  • smooth (Boolean) - Smoothly transition to the new zoom. If enabled, will provide a slightly lagged but smoother experience. Default false.
dragPan (Boolean|Object)
  • default: true

Enable drag to pan. If an object is provided, may contain the following options to customize its behavior:

  • inertia (Number) - Enable momentum/inertia when the gesture ends. The value specifies after how long the panning comes to a stop, in milliseconds. Default 300.
dragRotate (Boolean)
  • default: true

Enable drag to rotate. If an object is provided, may contain the following options to customize its behavior:

  • inertia (Number) - Enable momentum/inertia when the gesture ends. The value specifies after how long the rotation comes to a stop, in milliseconds. Default 300.
doubleClickZoom (Boolean)
  • default: true

Enable double click to zoom.

touchZoom (Boolean|Object)
  • default: true

Enable multitouch zoom. If an object is provided, may contain the following options to customize its behavior:

  • inertia (Number) - Enable momentum/inertia when the gesture ends. The value specifies after how long the zooming comes to a stop, in milliseconds. Default 300.
touchRotate (Boolean|Object)
  • default: false

Enable multitouch rotate, including two-finger rotation to change bearing and three-finger swipe to change pitch. If an object is provided, may contain the following options to customize its behavior:

  • inertia (Number) - Enable momentum/inertia when the gesture ends. The value specifies after how long the rotation comes to a stop, in milliseconds. Default 300.
keyboard (Boolean|Object)
  • default: true

Enable keyboard navigation. If an object is provided, may contain the following options to customize its behavior:

  • zoomSpeed (Number) - speed of zoom using +/- keys. Default 2.
  • moveSpeed (Number) - speed of movement using arrow keys, in pixels.
  • rotateSpeedX (Number) - speed of rotation using shift + left/right arrow keys, in degrees. Default 15.
  • rotateSpeedY (Number) - speed of rotation using shift + up/down arrow keys, in degrees. Default 10.
touchAction (String)
  • default: 'none'

Allow browser default touch actions. Default none. See hammer.js doc.

By default, the map captures all touch interactions. This prop is useful for mobile applications to unblock default scrolling behavior. For example, use the combination dragPan: false and touchAction: 'pan-y' to allow vertical page scroll when dragging over the map.

eventRecognizerOptions (Object)
  • default: {}

Set options for gesture recognition. My contain the following fields:

  • pan - an object that is Hammer.Pan options. This gesture is used for drag events.
  • pinch - an object that is Hammer.Pinch options This gesture is used for two-finger touch events.
  • tripan - an object that is Hammer.Pan options. This gesture is used for three-finger touch events.
  • tap - an object that is Hammer.Tap options. This gesture is used for the onClick callback.
  • anytap - an object that is Hammer.Tap options. This gesture is used for the onNativeClick callback.
  • doubletap - an object that is Hammer.Tap options. This gesture is used for double click events.

For example, the following setting makes panning less sensitive and clicking easier on mobile:

const eventRecognizerOptions = isMobile ? {
  pan: {threshold: 10},
  tap: {threshold: 5}
} : {};

<MapGL
  eventRecognizerOptions={eventRecognizerOptions}
/>

Note that the value of this prop is used once when the component mounts. Subsequent changes will be ignored.

clickRadius (Number)
  • default: 0

Radius to detect features around a clicked point.

controller (Object)

A map controller instance to replace the default map controller.

This object must implement the following interface:

  • events - An array of subscribed events
  • handleEvent(event, context) - A method that handles interactive events
interactiveLayerIds (Array)
  • default: null

A list of layer ids that are interactive. If specified:

  • Pointer event callbacks will only query the features under the pointer of these layers.
  • The getCursor callback will receive isHovering: true when hover over features of these layers.

If not specified:

  • Pointer event callbacks will query the features under the pointer of all layers.
  • The getCursor callback will always receive isHovering: false.

Transitions

transitionDuration (Number)
  • default: 0

Duration of transition in milliseconds. If specified, the map's viewport will smoothly move from the previous props to the current one.

transitionInterpolator (Object)
  • default: new LinearInterpolator()

An interpolator object that defines the transition behavior between two map states. react-map-gl offers two interpolators:

  • LinearInterpolator - similar to Mapbox's easeTo behavior.
  • FlyToInterpolator - similar to Mapbox's flyTo behavior.

You may import them as follows:

import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl';

<ReactMapGL transitionDuration={1000} transitionInterpolator={new FlyToInterpolator()}>

For details about using transition interpolators, see transitions.

transitionEasing (Function)
  • default: t => t

Easing function that maps a value from [0, 1] to [0, 1]. Check out http://easings.net/ for common easing curves.

transitionInterruption (Number)
  • default: TRANSITION_EVENTS.BREAK

What to do if an ongoing transition is interrupted by another transition. There are 4 options:

  • TRANSITION_EVENTS.BREAK - Start new transition from the current view.
  • TRANSITION_EVENTS.SNAP_TO_END - Jump to the end of the previous transition before starting the new transition.
  • TRANSITION_EVENTS.IGNORE - Complete the previous transition and ignore the new viewport change.
  • TRANSITION_EVENTS.UPDATE - Continue the ongoing transition but change its destination to the new viewport.

You may import the constants as follows:

import {TRANSITION_EVENTS} from 'react-map-gl';

Callbacks

Inherit the following props from StaticMap:

  • onLoad (Function)
  • onResize (Function)
  • onError (Function)
onViewportChange (Function)

Callback that is fired when the map's viewport properties should be updated. If not supplied, the map is not interactive.

onViewportChange(viewState, interactionState, oldViewState);

Arguments:

  • viewState (Object) The next viewport properties, including: width, height, latitude, longitude, zoom, bearing, pitch, altitude, maxZoom, minZoom, maxPitch, minPitch, transitionDuration, transitionEasing, transitionInterpolator, transitionInterruption.
  • interactionState (Object) The current interaction that caused this viewport change. See onInteractionStateChange for possible fields.
  • oldViewState (Object) The current viewport properties.
onViewStateChange (Function)

A newer version of the onViewportChange callback. Both are supported and provide equivalent functionality.

onViewStateChange({viewState, interactionState, oldViewState});
onInteractionStateChange (Function)

Callback that is fired when the user interacted with the map.

onInteractionStateChange(interactionState)

Possible fields include:

  • interactionState.inTransition (Boolean)
  • interactionState.isDragging (Boolean)
  • interactionState.isPanning (Boolean)
  • interactionState.isRotating (Boolean)
  • interactionState.isZooming (Boolean)

Note:

  • onInteractionStateChange may be fired without onViewportChange. For example, when the pointer is released at the end of a drag-pan, isDragging are reset to false, without the viewport's longitude and latitude changing.
onHover (Function)

Called when the mouse moves over the map (without button pressed). Receives a PointerEvent object.

onClick (Function)

Called when the map is single clicked. Receives a PointerEvent object. This event is not fired on double click therefore there may be a delay between pointer up and the event.

onNativeClick (Function)

Called when the map is clicked. Receives a PointerEvent object. This event is fired twice on double click.

onDblClick (Function)

Called when the map is double clicked. Receives a PointerEvent object.

onMouseDown (Function)

Called when a pointing device (usually a mouse) is pressed within the map. Receives a PointerEvent object.

onMouseMove (Function)

Called when a pointing device (usually a mouse) is moved within the map. Receives a PointerEvent object.

onMouseUp (Function)

Called when a pointing device (usually a mouse) is released within the map. Receives a PointerEvent object.

onTouchStart (Function)

Called when a touchstart event occurs within the map. Receives a PointerEvent object.

onTouchMove (Function)

Called when a touchmove event occurs within the map. Receives a PointerEvent object.

onTouchEnd (Function)

Called when a touchend event occurs within the map. Receives a PointerEvent object.

onMouseEnter (Function)

Called when a pointing device (usually a mouse) enters a visible portion of one of the interactive layers, defined by the interactiveLayerIds prop. Receives a PointerEvent object.

onMouseLeave (Function)

Called when a pointing device (usually a mouse) leaves a visible portion of one of the interactive layers, defined by the interactiveLayerIds prop. Receives a PointerEvent object.

onWheel (Function)

Called when a wheel event occurs within the map. Receives a PointerEvent object.

onMouseOut (Function)

Called when a point device (usually a mouse) leaves the map's canvas. Receives a PointerEvent object.

onContextMenu (Function)

Called when the context menu is activated. Prevent default here to enable right button interaction.

Default: event => event.preventDefault()

onTransitionStart (Function)

Callback that is fired when a transition is triggered.

onTransitionInterrupt (Function)

Callback that is fired when an ongoing transition is interrupted by another transition.

onTransitionEnd (Function)

Callback that is fired when a transition is complete.

Methods

Inherit the following methods from StaticMap:

  • getMap()
  • queryRenderedFeatures(geometry, parameters)

Source

interactive-map.js