# Maps

Drag this ETOPO1 globe to orbit; explore layers and exports in the [maps workbench](/maps).

## A first map

```ts
import { createGlyphMap, glyphMapGlobe } from "@glyphcss/maps";

const host = document.querySelector<HTMLElement>("#map")!;
const map = createGlyphMap(host, {
  view: { center: [0, 20], span: 140, cols: 140, rows: 63 },
  projection: glyphMapGlobe({ exaggeration: 24 }),
  layers: [{ type: "background", color: "#05070c" }],
});

map.on("click", ({ lngLat }) => console.log(lngLat));
map.fitBounds({ west: -74, east: -34, south: -56, north: 13 });
// On unmount: map.destroy();
```

Install with `npm install @glyphcss/maps`. Add a [raster layer](/maps/layers/#raster) with elevation data for terrain. No React/Vue bindings: mount/destroy the handle in your framework's lifecycle.

## Coordinates and navigation

```ts
const { col, row, visible } = map.project([-58.38, -34.6]);
const lngLat = map.unproject([70, 20]);
map.scene.setOptions({ charMode: "halfblock" });
```

- Coordinates: `[longitude, latitude]`; `span`: degrees across; vertical extent: `span * rows / cols`.
- `unproject` returns `null` off-surface; `autoSize: true` derives the grid from the host.
- Drag pans/orbits; wheel zooms; Ctrl/right-drag tilts/turns. Touch supports pinch, twist, and two-finger tilt.
- Set initial renderer options through `scene`; the widget owns camera and grid dimensions.

## Handle reference

| Task | Methods |
|---|---|
| View | `setView`, `getView`, `getMaxSpan`, `fitBounds`, `flyTo`, `resize`, `idle` |
| Camera | `setTilt`, `getTilt`, `getMaxTilt`, `setBearing`, `getBearing`, `setProjection`, `setWalk`, `getWalk` |
| Layers | `addLayer`, `removeLayer`, `moveLayer`, `getContourFieldRange`, `addMarker` |
| Lighting | `setSun`, `getSun`, `getSunDirection`, `getSubsolarPoint`, `setKeyLight`, `getKeyLight`, `getKeyLightDirection`, `setShadow`, `getShadow` |
| Lifecycle | `on`, `off`, `getAttributions`, `destroy`; properties: `host`, `scene` |

Events: `load`, `move`, `zoom`, `click`, `sun`. Unsubscribe: `off(type, handler)`, same handler.

## Attribution and data

```ts
const credits = map.getAttributions();
// Display each credit's name, license, url, and optional date.
```

Display credits for mounted sources; OpenStreetMap requires attribution. The browser-safe root includes projections/providers; `@glyphcss/maps/node` adds `loadGlyphMapSource` for Esri ASCII Grid files.

Continue with [projections](/maps/projections), [layers](/maps/layers), [navigation](/maps/camera), [terrain](/maps/terrain), or [OpenStreetMap](/maps/openstreetmap).