Mapkick

Create beautiful JavaScript maps with one line of Ruby. No more fighting with mapping libraries!

🔥 For static maps, check out Mapkick Static, and for charts, check out Chartkick

Installation

Add this line to your application’s Gemfile:

gem "mapkick-rb"

Mapkick uses Mapbox GL JS v1. To use tiles from Mapbox, create a Mapbox account to get an access token and set ENV["MAPBOX_ACCESS_TOKEN"] in your environment (or set Mapkick.options[:access_token] in an initializer).

Then follow the instructions for your JavaScript setup:

Importmap (Rails 7 default)
esbuild, rollup.js, or Webpack
Webpacker (Rails 6 default)
Sprockets

Importmap

In config/importmap.rb, add:

pin "mapkick/bundle", to: "mapkick.bundle.js"

And in app/javascript/application.js, add:

import "mapkick/bundle"

esbuild, rollup.js, or Webpack

Run:

yarn add mapkick

And in app/javascript/application.js, add:

import "mapkick/bundle"

Note: For rollup.js, this requires format: "iife" in rollup.config.js.

Webpacker

Run:

yarn add mapkick

And in app/javascript/packs/application.js, add:

import "mapkick/bundle"

Sprockets

In app/assets/javascripts/application.js, add:

//= require mapkick.bundle

Maps

Point map

<%= js_map [{latitude: 37.7829, longitude: -122.4190}] %>

Area map

<%= area_map [{geometry: {type: "Polygon", coordinates: ...}}] %>

Data

Data can be an array

<%= js_map [{latitude: 37.7829, longitude: -122.4190}] %>

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

<%= js_map cities_path %>

Point Map

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

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

{
  latitude: ...,
  longitude: ...,
  label: "Hot Chicken Takeover",
  tooltip: "5 stars",
  color: "#f84d4d"
}

Area Map

Use geometry with a GeoJSON Polygon or MultiPolygon

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

{
  geometry: {type: "Polygon", coordinates: ...},
  label: "Hot Chicken Takeover",
  tooltip: "5 stars",
  color: "#0090ff"
}

Options

Id, width, and height

<%= js_map data, id: "cities-map", width: "800px", height: "500px" %>

Marker color

<%= js_map data, markers: {color: "#f84d4d"} %>

Show tooltips on click instead of hover

<%= js_map data, tooltips: {hover: false} %>

Allow HTML in tooltips (must sanitize manually)

<%= js_map data, tooltips: {html: true} %>

Map style

<%= js_map data, style: "mapbox://styles/mapbox/outdoors-v12" %>

Zoom and controls

<%= js_map data, zoom: 15, controls: true %>

Refresh data from a remote source every n seconds

<%= js_map url, refresh: 60 %>

Pass options directly to the mapping library

<%= js_map data, library: {hash: true} %>

See the documentation for Mapbox GL JS for more info

Global Options

To set options for all of your maps, create an initializer config/initializers/mapkick.rb with:

Mapkick.options[:height] = "400px"

Sinatra and Padrino

Download mapkick.bundle.js and include it manually.

<script src="mapkick.bundle.js"></script>

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:

git clone https://github.com/ankane/mapkick.git
cd mapkick
bundle install
bundle exec rake test