Custom overlays

Getting your own HTML on the map, instead of the default markers, has always been a bit of a pain point with Google Maps. Custom marker icons get you so far, but what if you want to render dynamic content — bound data, click handlers, CSS animations? That's what an overlay is for.

What's an overlay?

Google's own docs call this an OverlayView. You add any HTML element to the map as an "overlay" by wiring it up directly with the Google Maps API in JavaScript. Doing that by hand gets messy fast. The guides show an example overlaying a section of a terrain map, which is neat, but the far more common use is custom HTML markers — markers with real data, real interactions, and real CSS, not just a static icon.

An OverlayView asks you to define three methods: onAdd, draw, and onRemove. In Ember terms those map almost exactly onto insert, render, and destroy — three things Ember components already do well. All that's really needed is to wait for the map to finish loading, then insert the component into the DOM and register it with the map. The Overlay component handles that (and more) so you don't have to.

Creating custom overlays

Create a custom overlay with the Overlay component. It works like most other components in this addon, with one twist: pass it a block, and that block renders on the map.

<GMap @lat={{51.5074}} @lng={{-0.1278}} @zoom={{12}}>
  <Overlay @lat={{51.5074}} @lng={{-0.1278}}>
    <div class="my-overlay">Hello, map!</div>
  </Overlay>
</GMap>

Your imagination is the limit here. The example below renders a set of fake rental prices, with a hover effect on each one.

Example

TIP

Hover over any price tag to see the hover effect. It's plain CSS — no JavaScript state involved.

Custom options

Two extra arguments beyond position control how the overlay sits on the map:

@paneName — which map pane to render the overlay in. See Google's MapPanes docs for the available options. Defaults to overlayMouseTarget.

@zIndex — sets the z-index CSS property on the overlay, for controlling stacking order against other overlays.

Positioning the overlay

DANGER

Your overlay content isn't centered on its coordinates by default. You have to do that yourself.

The overlay is positioned exactly at the coordinates you give it, but the content inside expands down and to the right, anchored at its top-left corner. In other words, the top-left of your content sits on the coordinate — rarely what you actually want.

The transform CSS property fixes this. Wrap your content in an element and apply the transform there, relative to its own size. A couple of common cases:

Centering overlay content

To center content directly over its coordinate, offset it by half its own width and height:

<Overlay @lat={{51.5074}} @lng={{-0.1278}}>
  <div style="transform: translate(-50%, -50%);">
    <div class="my-marker">📍</div>
  </div>
</Overlay>

Because the offset is a percentage, it scales with the content — if your element is 100px wide and 100px tall, the transform above moves it 50px up and 50px left, however big it ends up being.

Tooltip positioning

Another common need: center the overlay horizontally, but place it above the coordinate rather than on top of it. This suits tooltips, which usually have their "tip" pointing down from the middle-bottom of the element — exactly the pattern used in the price tooltips above.

<Overlay @lat={{51.5074}} @lng={{-0.1278}}>
  <div style="transform: translate(-50%, -100%);">
    <div class="my-tooltip">Rent: £1,200/mo</div>
  </div>
</Overlay>

Inline styles work, but for anything beyond a quick example you're better off adding a class to your own stylesheet instead:

.my-tooltip-anchor {
  transform: translate(-50%, -100%);
}

You're not limited to percentages either — pixels and any other CSS unit work the same way.