Leaflet Butter Smooth Zoom

Butter-smooth wheel zoom handler for Leaflet with inertia-style zooming, plus optional vector hiding while zooming.

Demo

Live demo: https://hexadeciman.github.io/Leaflet.ButterSmoothZoom/

Features

• Inertia-style wheel zoom with configurable easing and end delay.
• Keeps line weights and circle markers in place while zooming (no marker drifting).
• Works with Leaflet and React-Leaflet.

Install

npm install leaflet-butter-smooth-zoom

yarn add leaflet-butter-smooth-zoom

pnpm add leaflet-butter-smooth-zoom

Usage (Leaflet, ESM)

import 'leaflet-butter-smooth-zoom';
import L from 'leaflet';

const map = L.map('map', {
  butterSmoothZoom: true,
  butterSmoothScale: 0.0042,
  butterSmoothEasing: 0.38,
  butterSmoothEndDelay: 140,
  butterSmoothHideVectors: false,
  butterSmoothButtonZoomDelta: 1,
  butterSmoothZoomAnimationDuration: 0.125
});

Usage (React-Leaflet)

import 'leaflet-butter-smooth-zoom';
import { MapContainer, TileLayer } from 'react-leaflet';

<MapContainer
  center={[40.73061, -73.935242]}
  zoom={13}
  scrollWheelZoom={false}
  butterSmoothZoom
  butterSmoothScale={0.0042}
  butterSmoothEasing={0.38}
  butterSmoothEndDelay={140}
  butterSmoothButtonZoomDelta={1}
>
  <TileLayer
    url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
    attribution="&copy; OpenStreetMap contributors"
  />
</MapContainer>;

Usage (script tag)

This repo ships a standalone browser build of the plugin: Leaflet.ButterSmoothZoom.js.

<link
  rel="stylesheet"
  href="https://unpkg.com/[email protected]/dist/leaflet.css"
/>
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
<script src="https://unpkg.com/leaflet-butter-smooth-zoom@latest/Leaflet.ButterSmoothZoom.js"></script>

Load Leaflet first, then the plugin. It registers L.Map.ButterSmoothZoom and the butterSmoothZoom handler.

Options

• butterSmoothZoom (boolean): Enable the handler.
• butterSmoothScale (number): Wheel delta multiplier. Higher values zoom faster.
• butterSmoothEasing (number): Interpolation factor per frame. Higher values feel snappier.
• butterSmoothEndDelay (number): Delay before final tile settle after wheel stops (ms).
• butterSmoothHideVectors (boolean): Toggle .smooth-wheel-hide class during zoom.
• butterSmoothButtonZoomDelta (number): Zoom step used by the +/- controls while enabled.
• butterSmoothZoomAnimationDuration (number): Zoom button animation duration in seconds (default 0.125).

CSS helper (optional)

If you enable butterSmoothHideVectors, add this to your app CSS:

.leaflet-container.smooth-wheel-hide .leaflet-overlay-pane,
.leaflet-container.smooth-wheel-hide .leaflet-marker-pane,
.leaflet-container.smooth-wheel-hide .leaflet-shadow-pane {
  opacity: 0;
  transition: opacity 120ms ease;
}