Mapkick.js

Create beautiful, interactive maps with one line of JavaScript

Maps
ankane/mapkick.jschartkick.com/mapkick-jsmapkick

README

Mapkick.js


Create beautiful, interactive maps with one line of JavaScript

See it in action

For charts, check out Chartkick.js

Installation


Mapkick supports Mapbox and MapLibre.

Mapbox


First, create a Mapbox account to get an access token.

Download [mapkick.js](https://unpkg.com/mapkick) and add in the `` of your HTML file:

  1. ```html
  2. <link href="https://api.mapbox.com/mapbox-gl-js/v2.12.0/mapbox-gl.css" rel="stylesheet" />
  3. <script src="https://api.mapbox.com/mapbox-gl-js/v2.12.0/mapbox-gl.js"></script>
  4. <script src="mapkick.js"></script>
  5. <script>
  6.   mapboxgl.accessToken = "YOUR-TOKEN"
  7. </script>
  8. ```

MapLibre


Download [mapkick.js](https://unpkg.com/mapkick) and add in the `` of your HTML file:

  1. ```html
  2. <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet" />
  3. <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
  4. <script src="mapkick.js"></script>
  5. <script>
  6.   Mapkick.options = {style: "https://demotiles.maplibre.org/style.json"}
  7. </script>
  8. ```

Getting Started


Create a map

  1. ```html
  2. <div id="map" style="height: 400px;"></div>
  4. <script>
  5.   new Mapkick.Map("map", [{latitude: 37.7829, longitude: -122.4190}])
  6. </script>
  7. ```

Maps


Point map

  1. ```javascript
  2. new Mapkick.Map("map", [{latitude: 37.7829, longitude: -122.4190}])
  3. ```

Area map

  1. ```javascript
  2. new Mapkick.AreaMap("map", [{geometry: {type: "Polygon", coordinates: ...}}])
  3. ```

Data


Data can be an array

  1. ```javascript
  2. new Mapkick.Map("map", [{latitude: 37.7829, longitude: -122.4190}])
  3. ```

Or a URL that returns JSON (same format as above)

  1. ```javascript
  2. new Mapkick.Map("map", "/restaurants")
  3. ```

Or a callback

  1. ```javascript
  2. function fetchData(success, fail) {
  3.   success([{latitude: 37.7829, longitude: -122.4190}])
  4.   // or fail("Data not available")
  5. }

  7. new Mapkick.Map("map", fetchData)
  8. ```

Point Map


Use latitude or lat for latitude and longitude, lon, or lng for longitude

You can specify an icon, label, tooltip, and color for each data point

  1. ```javascript
  2. {
  3.   latitude: ...,
  4.   longitude: ...,
  5.   icon: "restaurant",
  6.   label: "Hot Chicken Takeover",
  7.   tooltip: "5 stars",
  8.   color: "#f84d4d"
  9. }
  10. ```

Maki icons are supported (depending on the map style, only some icons may be available)

Area Map


Use geometry with a GeoJSON Polygon or MultiPolygon

You can specify a label, tooltip, and color for each data point

  1. ```javascript
  2. {
  3.   geometry: {type: "Polygon", coordinates: ...},
  4.   label: "Hot Chicken Takeover",
  5.   tooltip: "5 stars",
  6.   color: "#0090ff"
  7. }
  8. ```

Options


Marker color

  1. ```javascript
  2. new Mapkick.Map("map", data, {markers: {color: "#f84d4d"}}
  3. ```

Show tooltips on click instead of hover

  1. ```javascript
  2. new Mapkick.Map("map", data, {tooltips: {hover: false}})
  3. ```

Allow HTML in tooltips (must sanitize manually)

  1. ```javascript
  2. new Mapkick.Map("map", data, {tooltips: {html: true}})
  3. ```

Map style

  1. ```javascript
  2. new Mapkick.Map("map", data, {style: "mapbox://styles/mapbox/outdoors-v12"})
  3. ```

Zoom and controls

  1. ```javascript
  2. new Mapkick.Map("map", data, {zoom: 15, controls: true})
  3. ```

Pass options directly to the mapping library

  1. ```javascript
  2. new Mapkick.Map("map", data, {library: {hash: true}})
  3. ```

See the documentation for Mapbox GL JS and MapLibre GL JS for more info

Global Options


To set options for all of your maps, use:

  1. ```javascript
  2. Mapkick.options = {
  3.   style: "mapbox://styles/mapbox/outdoors-v12"
  4. }
  5. ```

Live Updates


Refresh data periodically from a remote source to create a live map

  1. ```javascript
  2. new Mapkick.Map("map", url, {refresh: 10}) // seconds
  3. ```

Show trails

  1. ```javascript
  2. new Mapkick.Map("map", url, {trail: true, refresh: 10})
  3. ```

Use the id attribute to identify objects

  1. ```javascript
  2. [
  3.   {id: "bus-1", lat: ..., lon: ...},
  4.   {id: "bus-2", lat: ..., lon: ...}
  5. ]
  6. ```

Set trail length

  1. ```javascript
  2. new Mapkick.Map("map", url, {trail: {len: 10}, refresh: 10})
  3. ```

Replay Data


  1. ```javascript
  2. new Mapkick.Map("map", data, {replay: true})
  3. ```

Use the id attribute to identify objects and the time attribute for when the data was measured

  1. ```javascript
  2. [
  3.   {id: "bus-1", lat: ..., lon: ..., time: t0},
  4.   {id: "bus-2", lat: ..., lon: ..., time: t0},
  5.   {id: "bus-1", lat: ..., lon: ..., time: t1},
  6.   {id: "bus-2", lat: ..., lon: ..., time: t1}
  7. ]
  8. ```

Times can be a Date, a timestamp (or sequence number), or a string (strings are parsed)

History


View the changelog

Contributing


Everyone is encouraged to help improve this project. Here are a few ways you can help:

- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features

To get started with development:

  1. ```sh
  2. git clone https://github.com/ankane/mapkick.js.git
  3. cd mapkick.js
  4. npm install
  5. npm run build-dev
  6. ```