UI Layers

Marker

L.Marker is used to display clickable/draggable icons on the map. Extends Layer.

USAGE EXAMPLE

L.marker([50.5, 30.5]).addTo(map);

Creation

Factory Description
L.marker(<LatLng> latlng, <Marker options> options?) Instantiates a Marker object given a geographical point and optionally an options object.

Options

Option Type Default Descripion
Icon Icon * Icon instance to use for rendering the marker. See Icon documentation for details on how to customize the marker icon. If not specified, a common instance of L.Icon.Default is used.
draggable Boolean false Whether the marker is draggable with mouse/touch or not.
keyboard Boolean true Whether the marker can be tabbed to with a keyboard and clicked by pressing enter.
title String '' Text for the browser tooltip that appear on marker hover (no tooltip by default).
alt String '' Text for the alt attribute of the icon image (useful for accessibility).
zIndexOffset Number 0 By default, marker images zIndex is set automatically based on its latitude. Use this option if you want to put the marker on top of all others (or below), specifying a high value like 1000 (or high negative value, respectively).
opacity Number 1.0 The opacity of the marker.
riseOnHover Boolean false If true, the marker will get on top of others when you hover the mouse over it.
riseOffset Number 250 Text for the browser tooltip that appear on marker hover (no tooltip by default).
title String '' The z-index offset used for the riseOnHover feature.
pane String 'markerPane' Map pane where the markers icon will be added.
bubblingMouseEvents Boolean false When true, a mouse event on this marker will trigger the same event on the map (unless L.DomEvent.stopPropagation is used).

Events

In addition to shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Event Data Descripion
move Event Fired when the marker is moved via setLatLng or by dragging. Old and new coordinates are included in event arguments as oldLatLng, latlng.

Dragging events

Event Data Descripion
dragstart Event Fired when the user starts dragging the marker.
movestart Event Fired when the marker starts moving (because of dragging).
drag Event Fired repeatedly while the user drags the marker.
dragend DragEndEvent Fired when the user stops dragging the marker.
moveend Event Fired when the marker stops moving (because of dragging).

Methods

Method Returns Descripion
toGeoJSON() Object Returns a GeoJSON representation of the marker (as a GeoJSON Point Feature).
getLatLng() LatLng Returns the current geographical position of the marker.
setLatLng(<LatLng> latlng) this Changes the marker position to the given point.
setZIndexOffset(<Number> offset) this Changes the zIndex offset of the marker.
setIcon(<Icon> icon) this Changes the marker icon.
setOpacity(<Number> opacity) this Changes the opacity of the marker.

Tooltip methods inherited from Layer

Method Returns Descripion
bindTooltip(<String|HTMLElement|Function|Tooltip> content, <Tooltip options> options?) this Binds a tooltip to the layer with the passed content and sets up the necessary event listeners. If a Function is passed it will receive the layer as the first argument and should return a String or HTMLElement.
unbindTooltip() this Removes the tooltip previously bound with bindTooltip.
openTooltip(<LatLng options> latlng?) this Opens the bound tooltip at the specificed latlng or at the default tooltip anchor if no latlng is passed.
closeTooltip() this Closes the tooltip bound to this layer if it is open.
toggleTooltip() this Opens or closes the tooltip bound to this layer depending on its current state.
isTooltipOpen() boolean Returns true if the tooltip bound to this layer is currently open.
setTooltipContent(<String|HTMLElement|Tooltipoptions> content) this Sets the content of the tooltip bound to this layer.
getTooltip() Tooltip Returns the tooltip bound to this layer.

Properties

Interaction handlers

Interaction handlers are properties of a marker instance that allow you to control interaction behavior in runtime, enabling or disabling certain features such as dragging (see Handler methods). Example:
marker.dragging.disable();

Property Type Descripion
dragging Handler Marker dragging handler (by both mouse and touch). Only valid when the marker is on the map (Otherwise set marker.options.draggable).

Popup

Used to open popups in certain places of the map. Use Map.openPopup to open popups while making sure that only one popup is open at one time (recommended for usability), or use Map.addLayer to open as many as you want.

USAGE EXAMPLE
If you want to just bind a popup to marker click and then open it, it's really easy:

marker.bindPopup(popupContent).openPopup();

Path overlays like polylines also have a bindPopup method. Here's a more complicated way to open a popup on a map:

var popup = L.popup()
    .setLatLng(latlng)
    .setContent('<p>Hello world!<br />This is a nice popup.</p>')
    .openOn(map);

Creation

Factory Description
L.popup (<Popup options> options?,<Layer> source?) Instantiates a Popup object given an optional options object that describes its appearance and location and an optional source object that is used to tag the popup with a reference to the Layer to which it refers.

Options

Option Type Default Descripion
maxWidth Number 300 Max width of the popup, in pixels.
minWidth Number 50 Min width of the popup, in pixels.
maxHeight Number null If set, creates a scrollable container of the given height inside a popup if its content exceeds it.
autoPan Boolean true Set it to false if you don't want the map to do panning animation to fit the opened popup.
autoPanPaddingTopLeft Point null The margin between the popup and the top left corner of the map view after autopanning was performed.
autoPanPaddingBottomRight Point null The margin between the popup and the bottom right corner of the map view after autopanning was performed.
autoPanPaddingBottomRight Point null The margin between the popup and the bottom right corner of the map view after autopanning was performed.
autoPanPadding Point Point(5, 5) Equivalent of setting both top left and bottom right autopan padding to the same value.
keepInView Boolean false Set it to true if you want to prevent users from panning the popup off of the screen while it is open.
closeButton Boolean true Controls the presence of a close button in the popup.
autoClose Boolean true Set it to false if you want to override the default behavior of the popup closing when another popup is opened.
closeOnClick Boolean * Set it if you want to override the default behavior of the popup closing when user clicks on the map. Defaults to the map's closePopupOnClick option.
className String '' A custom CSS class name to assign to the popup.

Methods

Method Returns Description
getLatLng() LatLng Returns the geographical point of popup.
setLatLng( latlng) this Sets the geographical point where the popup will open.
getContent() String|HTMLElement Returns the content of the popup.
setContent(<String|HTMLElement|Function> htmlContent) this Sets the HTML content of the popup. If a function is passed the source layer will be passed to the function. The function should return a String or HTMLElement to be used in the popup.
getElement() String|HTMLElement Alias for getContent()
update() null Updates the popup content, layout and position. Useful for updating the popup after something inside changed, e.g. image loaded.
isOpen() Boolean Returns true when the popup is visible on the map.
bringToFront() this Brings this popup in front of other popups (in the same map pane).
bringToBack() this Brings this popup to the back of other popups (in the same map pane).
openOn(<Map> map) this Adds the popup to the map and closes the previous one. The same as map.openPopup(popup).

Tooltip

Used to display small texts on top of map layers.

USAGE EXAMPLE

marker.bindTooltip("my tooltip text").openTooltip();

Note about tooltip offset. Leaflet takes two options in consideration for computing tooltip offseting:

  • the offset Tooltip option: it defaults to [0, 0], and it's specific to one tooltip. Add a positive x offset to move the tooltip to the right, and a positive y offset to move it to the bottom. Negatives will move to the left and top.
  • the tooltipAnchor Icon option: this will only be considered for Marker. You should adapt this value if you use a custom icon.

Creation

Factory Description
L.tooltip(<Tooltip options> options?, <Layer> source?) Instantiates a Tooltip object given an optional options object that describes its appearance and location and an optional source object that is used to tag the tooltip with a reference to the Layer to which it refers.

Options

Option Type Default Descripion
pane String 'tooltipPane' Map pane where the tooltip will be added.
offset Point Point(0, 0) Optional offset of the tooltip position.
direction String 'auto' Direction where to open the tooltip. Possible values are: right, left, top, bottom, center, auto. auto will dynamicaly switch between right and left according to the tooltip position on the map.
permanent Boolean false Whether to open the tooltip permanently or only on mouseover.
sticky Boolean false If true, the tooltip will follow the mouse instead of being fixed at the feature center.
interactive Boolean false If true, the tooltip will listen to the feature events.
opacity Number 0.9 Tooltip container opacity.