Overlay API

Add an Overlay

Use EarthInstance.addOverlay( properties )

var myoverlay = myearth.addOverlay( {
	location: { lat: 40.689, lng: -74.046 },
	content : '<strong> New York </strong>',
	className : 'my-text-overlay',
	depthScale : 0.5
} );

Overlay Properties

location (lat/lng object)

{ lat: 0, lng: 0 }

The geo location where the overlay is placed.

offset (float)

0

Distance to the earth surface.

content (html string)

Text or HTML content of the overlay.
See Overlay HTML

className (string)

CSS class(es) for overlay styling.
See Overlay HTML

containerScale (float)

0

0.0 - 1.0

Values greater than 0 adapt the overlay scaling to the size of the earth container.
Example: Overlay containerScale

zoomScale (float)

1

0.0 - 1.0

Values greater than 0 adapt the overlay scaling to the earth zoom.
Example: Overlay zoomScale

depthScale (float)

0

0.0 - 1.0

Values greater than 0 adapt the overlay scaling to the distance to the camera.
Example: Overlay depthScale

visible (boolean)

true

occlude (boolean)

true

Set to false if you want the overlay to always stay in front of the earth.
Example: Occlusion

Advanced:

Overlay Methods

animate( property, value, animationProperties ) returns AnimationInstance

property

Name of the animatable property (String)

value

Target value

animationProperties

Object of animation properties

Example: Animatable Properties

stopAllAnimations( triggerComplete, jumpToEnd )

triggerComplete

(boolean) default: false | Calls the complete functions

jumpToEnd

(boolean) default: false | Sets the properties immediately to their end values

Stops all animations of this object. To stop a specific animation use AnimationInstance.stop()

remove( )

Removes the overlay permanently.

Overlay Events

occlusion

The event is triggered when the overlay is added and when the occluded property changes.
Example: Occlusion

Regular JavaScript Events

You can register events for HTML elements of your overlay content.

var myoverlay = myearth.addOverlay( {
	location: { lat: 40.689, lng: -74.046 },
	content : '<button class="my-button">click me</button>'
} );


/* You can access children by using querySelector on the overlay element */
myoverlay.element.querySelector('.my-button').addEventListener( 'click', function( ) {

	alert( 'button was clicked!' );
	
	/* You can access the OverlayInstance by the overlay property of the overlay element */
	this.closest('.earth-overlay').overlay.visible = false;	

} );

<a href="https://miniature.earth/">I'm clickable by default</a>
<div>Not clickable</div>
<div style="pointer-events: all;" onclick="alert('click!')">I've been made clickable</div>

Overlay CSS Classes

earth-overlay

Every overlay element has this CSS class.

earth-occluded

This CSS class is added as long as the overlay location is on the backside of the earth.

.earth-overlay {
	transition: opacity 0.5s ease;
}
.earth-occluded {
	opacity: 0.5; /* semi-transparent if location is on the backside of the earth */
}

earth-overlay-top / earth-overlay-left

This CSS class is added as long as the overlay is on the upper (or left) half of the container.

.earth-overlay-top {
	...
}
.earth-overlay:not(.earth-overlay-top) { /* bottom */
	...
}

See Overlay Styles

Overlay HTML

An overlay is made up of this HTML code:

<div id="myearth" class="earth-container earth-ready">
	<canvas width="960" height="960"></canvas>
	
	<div class="earth-overlay (earth-occluded)" style="transform: ...; z-index: ...">
		<div class="className"> content </div>
	</div>
	
</div>

Overlay Position

The top left corner of your content is placed at the lat/lng location. To change this position you can use styles like these:

<style>
.my-overlay-above {
	transform: translate(-50%, -100%);
	background-color: white;
	color: black;
	padding: 1em;
}
</style>

var myoverlay = myearth.addOverlay( {
	location: { lat: 40.689, lng: -74.046 },
	className : 'my-overlay-above',
	content : 'This content is centered above the location.'
} );