`), so your own CSS, Tailwind classes and components style them normally. Set these custom properties on `instant-map` or any ancestor to restyle the built-in card: `--im-card-width`, `--im-card-radius`, `--im-card-padding`, `--im-card-background`, `--im-card-color`, `--im-card-muted`, `--im-card-accent`, `--im-card-shadow`, `--im-card-font`, `--im-card-image-ratio` and `--im-card-placeholder`. The classes inside `.instant-map-card` are `.media`, `.badge`, `.body`, `.title`, `.subtitle`, `.foot`, `.price`, `.action` and `.close`, plus `.row` on the card itself for the row layout. See [Cards and popups](/docs/guides/popups/) for what each does.
## Declarative cards
[Section titled “Declarative cards”](#declarative-cards)
A `` that is a direct child of `` becomes the card. `{{title}}` and `{{data.beds}}` are filled as text, `data-if="field"` drops an element whose field is empty, `on…` attributes are removed, and an element with `data-close` closes the card. Links and image addresses accept only `http`, `https`, `mailto`, `tel` and relative addresses. See [Cards and popups](/docs/guides/popups/#4-a-template-in-your-html).
# HTTP API
> The /static and /tiles endpoints, every parameter, limits and error codes.
The image server is a Cloudflare Worker. It renders map images from vector tiles in the Rust renderer (compiled to WebAssembly) and caches every response at the edge.
* **Hosted:** `https://instantmap.org` works for prototypes and small sites, with no key and no guarantees.
* **Production:** run your own copy, which takes about ten minutes. See [Self-hosting](/docs/guides/self-hosting/).
Every image response sends `Access-Control-Allow-Origin: *` and `Cache-Control: public, max-age=604800, immutable`. A URL always renders the same picture, so caches, CDNs and email clients can keep it.
## Response headers
[Section titled “Response headers”](#response-headers)
| Header | Value |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cf-cache-status` | `HIT` when Cloudflare’s cache answered without running the Worker. The other headers in this table are then the ones stored with the picture when it was first served. |
| `x-instantmap-cache` | How the Worker produced the picture: `miss` when it was just drawn, `hit` when it came from the Worker’s own cache, `store` when it came from the optional `TILE_CACHE` R2 bucket. |
| `server-timing` | `upstream;dur=…`: the milliseconds spent fetching vector tiles when the picture was drawn. |
| `timing-allow-origin` | `*`, so pages on other origins can read the timing. |
| `x-attribution` | The attribution text. |
## Caching
[Section titled “Caching”](#caching)
A picture is cached under the request as the server understood it, not as it was written. Unknown query parameters, the order of parameters and different spellings of the same value (`zoom=12` and `zoom=12.0`) all share one cached picture, so adding a cache-busting parameter does not draw it again.
## `GET /health`
[Section titled “GET /health”](#get-health)
Returns `{ "ok": true, "renderer": "…" }` with `Cache-Control: no-store`. The `renderer` value changes when the renderer or the themes change. Use it for uptime checks.
## `GET /static`
[Section titled “GET /static”](#get-static)
One finished map image, with markers drawn in. Use it as the first frame of ``, in emails, in Open Graph images, or anywhere JavaScript can’t run.
```plaintext
https://instantmap.org/static?center=-97.74,30.27&zoom=12&size=1200x630&r=2&markers=-97.75,30.27,$420;-97.73,30.28,$385
```
| Parameter | Required | Format | Limits | Notes |
| ---------- | -------- | ------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `center` | yes | `lng,lat` | lng −180…180, lat −85.06…85.06 | |
| `zoom` | yes | number | 0…18 | Fractions allowed. |
| `size` | no | `WIDTHxHEIGHT` | 16…1280 each | Default `640x400`. CSS pixels. |
| `r` | no | `1` or `2` | | Pixel ratio. `2` doubles the output for retina screens. |
| `theme` | no | `daylight` · `midnight` · `paper` · `mono` | | Default `daylight`. |
| `colors` | no | `token:hex,token:hex` | 36 tokens | Overrides on top of `theme`. See [Themes](/docs/reference/themes/). |
| `markers` | no | `lng,lat[,label];…` | 2,000 entries with `clusters` | Labels over 10 characters are cut. A label may contain commas (`$6,850`); everything after the second comma is the label. Use `;` only between entries. |
| `clusters` | no | `lng,lat,count;…` | | Pre-clustered bubbles. `staticUrl()` writes these for you. |
| `cluster` | no | pixels | 0…120 | Merge distance for `markers`. Default `44`. `0` turns clustering off. |
| `v` | no | text | any | Style version. `staticUrl()` adds it so that browsers fetch a new image when the default look of a release changes. The server ignores it. |
| `format` | no | `jpg` · `png` | | Default `jpg`. JPEGs are progressive, at quality 86, or 72 when `r=2`. |
Build these URLs with [`staticUrl()`](/docs/reference/javascript/#staticurl) rather than by hand. `staticUrl()` clusters your markers in the same way the browser does and drops the ones outside the frame, so a URL for 50,000 markers stays short.
## `GET /tiles/{z}/{x}/{y}.jpg`
[Section titled “GET /tiles/{z}/{x}/{y}.jpg”](#get-tileszxyjpg)
512 px raster tiles for the interactive map. `{z}` runs 0 to 15. Beyond zoom 15 the map scales the zoom 15 tile.
| Variant | Example |
| -------- | ------------------------------------------------------------ |
| Standard | `/tiles/12/944/1652.jpg` |
| Retina | `/tiles/12/944/1652@2x.jpg` (JPEG quality 72; 1x is 86) |
| PNG | `/tiles/12/944/1652.png` |
| Themed | `/tiles/12/944/1652.jpg?theme=midnight&colors=accent:ff5a5f` |
Tiles never contain markers. Labels are placed per tile, so a `/static` image at a whole-number zoom is pixel for pixel the same picture as the tile mosaic. That is why the hand-off from the still image to the interactive map doesn’t flicker.
## Errors
[Section titled “Errors”](#errors)
| Status | Body | Cause |
| ------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `400` | A sentence naming the bad parameter, e.g. `zoom must be a number from 0 to 18` | Invalid input. Fix the request; retrying won’t help. |
| `405` | `method not allowed` | Only `GET`, `HEAD` and `OPTIONS` are served. |
| `429` | `too many uncached map requests, try again shortly` | Only on a server that has a render rate limit configured. Sent with `Retry-After`. Cached pictures are never limited. |
| `502` | `render failed` | The upstream vector tiles failed or the render crashed. Safe to retry. |
Upstream tile requests time out after 8 seconds and are tried once more before a request fails with `502`. Errors are never cached.
## Attribution
[Section titled “Attribution”](#attribution)
Map data is © OpenStreetMap contributors (ODbL), with tiles from Protomaps. `` shows the credit for you. When you use `/static` images on their own, show “© OpenStreetMap” near them. Each response also carries an `x-attribution` header with the text.
# JavaScript API
> Exports of instantmap, instantmap-js/server, instantmap-js/card and instantmap-js/brand, including staticUrl, posterHtml, brandTheme, clusterAt, themes and types.
The package has these entry points:
| Import | Use it in | Contains |
| ------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instantmap-js` | Browser code | Defines ``, plus `staticUrl`, `tileUrl`, `clusterAt`, themes, `brandTheme` and `brandThemeFromCss`. `posterHtml` is in `instantmap-js/server`. |
| `instantmap-js/server` | Servers, build scripts, edge functions, React Server Components | `staticUrl`, `tileUrl`, `posterHtml`, `clusterAt`, themes, colour helpers, `brandTheme` and `brandThemeFromCss`. Defines no element and never touches `window`. |
| `instantmap-js/react` | React 18 and 19, Next.js, Remix | The [`` component](/docs/reference/react/). |
| `instantmap-js/card` | Code that builds its own card | `defaultCard`, `cardFromTemplate`, `safeUrl`, `escapeHtml`, `CARD_CSS`. |
| `instantmap-js/brand` | Anywhere | `brandTheme`, `brandThemeFromCss`, and the `BrandInput` and `BrandTheme` types. |
| `instantmap-js/instant-map.js` | A script tag | The ready-built loader that defines ``. It is what `https://instantmap.org/instant-map.js` serves. |
All of them ship ES modules with TypeScript types.
The element is split in two. `instant-map.js` is a small loader, about 7 KB gzipped, that holds the element and its first image. The engine (tiles, gestures, markers, cards), about 11 KB gzipped, is fetched on the first sign of intent, or as the `load` attribute says.
## `staticUrl(options)`
[Section titled “staticUrl(options)”](#staticurloptions)
Returns the URL of a finished map image. This is the function that makes the first paint instant: render the URL into an `![]()
` on the server, and the browser shows the map before any JavaScript arrives.
```ts
import { staticUrl } from "instantmap-js/server";
const url = staticUrl({
center: [-97.7431, 30.2672],
zoom: 12,
width: 1200,
height: 630,
ratio: 2,
theme: "daylight",
markers: listings.map((listing) => ({ lng: listing.lng, lat: listing.lat, label: `$${listing.price}` })),
});
```
| Option | Type | Default | Notes |
| ----------------- | ----------------------------------------------- | -------------------------- | ------------------------------------------------------------------------- |
| `center` | `[lng, lat]` | required | |
| `zoom` | `number` | required | |
| `width`, `height` | `number` | required | CSS pixels, at most 1280 each. Use the element’s own aspect ratio. |
| `ratio` | `1 \| 2` | `1` | Use `2` for crisp images on retina screens. |
| `theme` | `"daylight" \| "midnight" \| "paper" \| "mono"` | `"daylight"` | |
| `colors` | `Partial>` | none | Token overrides. They are written to the address in alphabetical order. |
| `markers` | `{ lng, lat, label? }[]` | none | Any number. Clustered and cropped to the frame before they go in the URL. |
| `cluster` | `number \| false` | `44` | Same value you give the element. |
| `src` | `string` | `"https://instantmap.org"` | Your own server’s origin. |
| `format` | `"jpg" \| "png"` | `"jpg"` | |
## `posterHtml(options)`
[Section titled “posterHtml(options)”](#posterhtmloptions)
Returns a complete `` element as an HTML string, with its poster image inside, for templates that are not React: Express, Hono, Astro’s `set:html`, PHP, emails, Markdown.
```ts
import { posterHtml } from "instantmap-js/server";
const html = posterHtml({ center: [-0.1276, 51.5072], zoom: 11, width: 1280, height: 720, markers });
```
It takes every `staticUrl` option, plus:
* `alt`
* `className`
* `load`
It writes `center`, `zoom`, `theme`, `colors`, `load` and `src` as attributes on the element, so the live map starts with the same look as the image.
The string sets `aspect-ratio` from `width` and `height`, so the map holds its space before it loads. `ratio` defaults to `2` here.
## `clusterAt(markers, zoom, distance?)`
[Section titled “clusterAt(markers, zoom, distance?)”](#clusteratmarkers-zoom-distance)
The clustering function the element and the server both run. Use it when you need the same groups outside the map, for example a list that says “12 listings in this area”.
```ts
import { clusterAt } from "instantmap-js";
for (const group of clusterAt(markers, Math.floor(map.camera.zoom))) {
group.members; // Marker[]
}
```
Positions are in world pixels at that zoom. The result is the same whatever the viewport.
## `defineInstantMap(tagName?)`
[Section titled “defineInstantMap(tagName?)”](#defineinstantmaptagname)
`instantmap-js` calls this when imported. Call it yourself only to register the element under another tag name.
## `brandTheme(input)`
[Section titled “brandTheme(input)”](#brandthemeinput)
Builds a map theme from the colours of a style guide. Available from `instantmap-js`, `instantmap-js/server` and `instantmap-js/brand`.
```ts
import { brandTheme } from "instantmap-js/server";
const brand = brandTheme({ primary: "#e11d48", background: "#fff7ed", foreground: "#1c1917" });
// { theme: "daylight", colors: { … } }
staticUrl({ center, zoom, width, height, ...brand });
```
| Input | Type | Notes |
| ------------ | ------------------- | ------------------------------------------------------------------------------------- |
| `primary` | `string` | Required. Markers, clusters and highways. |
| `background` | `string` | The page colour. Land is a tint of it. |
| `foreground` | `string` | Text colour. Labels and outlines are mixed from it. |
| `accent` | `string` | The selected marker. Default: the foreground colour. |
| `water` | `string` | Default: a quiet blue leaning toward the brand colour. |
| `park` | `string` | Default: a quiet green. |
| `mode` | `"light" \| "dark"` | Default: decided from `background`. |
| `tint` | `number` | `0` to `1`. How strongly the brand colour tints land, water and roads. Default `0.5`. |
Colours can be `#rgb`, `#rrggbb`, `rgb()`, `hsl()` or a bare `h s% l%` triplet. It throws a `TypeError` if `primary` cannot be read. It returns `{ theme, colors }`, where `theme` is `"daylight"` or `"midnight"` and `colors` holds only the values that differ from that theme. Label and marker text colours are adjusted to stay readable.
Use it in `staticUrl({ ...brand })`, `posterHtml({ ...brand })`, ` from instantmap-js/react.
```tsx
import { InstantMap } from "instantmap-js/react";
console.log(marker.id)}
/>;
```
Works with React 18 and 19, on the client and on the server. The file starts with `"use client"`, so you can use it directly inside Next.js Server Components. On the server it renders the `` element with its poster `![]()
`, so the map is in the first HTML response.
## Props
[Section titled “Props”](#props)
| Prop | Type | Default | Notes |
| ----------------------------- | ----------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `center` | `[lng, lat]` | required | A new value jumps the map there. To animate, call `ref.current.flyTo()` instead. |
| `zoom` | `number` | required | A new value jumps the map there. |
| `markers` | `Marker[]` | `[]` | Pass a new array to update. Memoise it if you build it in render. |
| `theme` | `"daylight" \| "midnight" \| "paper" \| "mono"` | `"daylight"` | |
| `colors` | `Partial>` | none | Memoise it if you build it in render. Pass `undefined` to clear the overrides. |
| `cluster` | `number \| false` | `44` | |
| `selected` | `id \| null` | uncontrolled | Controls the selection. |
| `card` | `CardOptions` | `{}` | Options for the built-in card: `{ layout?, action?, target?, closeLabel? }`. See [Cards and popups](/docs/guides/popups/). Not used when `renderPopup` is set. |
| `cardImages` | `"visible" \| "hover" \| "off"` | `"visible"` | When card images are fetched ahead of a click. |
| `renderPopup` | `(marker) => ReactNode` or `null` | built-in card | Your own card, rendered through a portal, so context, state and Tailwind all work. `null` turns cards off. |
| `src` | `string` | `"https://instantmap.org"` | Your image server. |
| `load` | `"intent" \| "visible" \| "eager" \| "none"` | `"intent"` | |
| `scrollZoom` | `"cooperative" \| "always" \| "off"` | `"cooperative"` | |
| `posterWidth`, `posterHeight` | `number` | `1280`, `720` | Size of the first image. Match your container’s aspect ratio. |
| `alt` | `string` | `"Map"` | |
| `className`, `style` | | | Give the map a height here. |
## Event props
[Section titled “Event props”](#event-props)
| Prop | Called with |
| -------------------------------- | ------------------------------------------------------------------------------- |
| `onMarkerClick` | `(marker, event)`. Call `event.preventDefault()` to skip the default selection. |
| `onClusterClick` | `(cluster, event)`. Call `event.preventDefault()` to skip the default zoom. |
| `onMarkerEnter`, `onMarkerLeave` | `(marker)` |
| `onSelect` | `(marker \| null)` |
| `onMove`, `onMoveEnd` | `({ center, zoom })` |
| `onInteractive` | `()` |
Handlers are read from the latest render, so inline arrow functions don’t re-subscribe anything.
## Ref
[Section titled “Ref”](#ref)
The ref is the `` element itself, with every [method](/docs/reference/element/#methods):
```tsx
const map = useRef>(null);
(
)}
/>
```
Use `renderPopup={null}` when a click should navigate instead of opening a card, and handle `onMarkerClick`.
# Themes and colour tokens
> The four built-in themes and all 36 colour tokens you can override.
A theme is a palette of 36 colour tokens. The server draws the map with them and the browser draws markers, popups and controls with them, so the still image and the live map always match.
Pick a theme, then override any token:
```html
` element in a standalone Angular component. Server rendering puts the first image in the HTML, and the element takes over in the browser.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Define the element before Angular starts. If it is defined later, Angular binds `markers` to a plain element and the setter never runs.
src/main.ts
```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { App } from './app/app';
import('instantmap-js').then(() => bootstrapApplication(App, appConfig));
```
Allow the custom element in the component and build the poster URL.
src/app/app.ts
```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import type { Marker } from 'instantmap-js';
import { staticUrl } from 'instantmap-js/server';
import { listings } from './listings';
@Component({
selector: 'app-root',
schemas: [CUSTOM_ELEMENTS_SCHEMA],
templateUrl: './app.html',
styleUrl: './app.css',
})
export class App {
readonly center: [number, number] = [-97.74, 30.27];
readonly zoom = 12;
readonly markers: Marker[] = listings();
readonly poster = staticUrl({
center: this.center,
zoom: this.zoom,
width: 1200,
height: 640,
ratio: 2,
markers: this.markers,
});
}
```
src/app/app.html
```html
![Map of Austin]()
```
Size the map in the stylesheet, not with an inline `style`. Angular rewrites an inline `style` attribute on the element and removes the variables the map sets on itself.
src/app/app.css
```css
instant-map {
display: block;
position: relative;
height: 520px;
}
```
## Render the first image on the server
[Section titled “Render the first image on the server”](#render-the-first-image-on-the-server)
Create the app with server rendering and keep the render mode on `Server`.
src/app/app.routes.server.ts
```ts
import { RenderMode, ServerRoute } from '@angular/ssr';
export const serverRoutes: ServerRoute[] = [{ path: '**', renderMode: RenderMode.Server }];
```
Build, start the server and check the HTML:
```sh
ng build
node dist/angular/server/server.mjs
curl -s https://your-site.example/ | grep -o ']*static?[^>]*'
```
You should see an `![]()
` whose `src` points at `/static?`.
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Listen with `(markerclick)` and call methods through a template reference. Use a signal for anything the event changes, because a zoneless app does not refresh on a plain property.
src/app/app.ts
```ts
import { ElementRef, signal, ViewChild } from '@angular/core';
import type { InstantMapElement } from 'instantmap-js';
export class App {
@ViewChild('map') map?: ElementRef;
opened = signal('Click a price to open its card.');
showDowntown() {
void this.map?.nativeElement.flyTo({ center: [-97.743, 30.267], zoom: 15 });
}
onMarkerClick(event: Event) {
const { marker } = (event as CustomEvent<{ marker: Marker }>).detail;
this.opened.set(`${marker.title}, ${marker.label}`);
}
}
```
src/app/app.html
```html
`. Angular overwrites it and removes the theme variables the map sets on itself.
* Leaving out `CUSTOM_ELEMENTS_SCHEMA`. Angular rejects the unknown tag.
* Giving the map no height. It collapses to nothing.
* Leaving out `ngSkipHydration`. Hydration then fights the element for its children.
## Prompt for your agent
[Section titled “Prompt for your agent”](#prompt-for-your-agent)
```text
Add an Instant Map to my Angular app with server rendering. Follow https://instantmap.org/docs/frameworks/angular.md exactly. Import instantmap before bootstrapApplication, add CUSTOM_ELEMENTS_SCHEMA, build the poster URL with staticUrl from instantmap-js/server and render it as an img inside instant-map with ngSkipHydration, and size the element in CSS rather than with an inline style. Build, start the server, and confirm the HTML from curl contains an img with /static? in its src.
```
## Full example
[Section titled “Full example”](#full-example)
[examples/angular on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/angular)
# Astro
> Add Instant Map to an Astro page, with the first image rendered on the server.
You will end up with an Astro page that ships the first map image in the HTML and becomes an interactive map on the first hover, touch or scroll.
## Install
[Section titled “Install”](#install)
```bash
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Put your markers in a module so the page and the script share them.
src/lib/listings.ts
```ts
import type { Marker } from "instantmap-js";
export const center: [number, number] = [-97.7431, 30.2672];
export const zoom = 12;
export const listings: Marker[] = [
{ id: 1, lng: -97.75, lat: 30.26, label: "$120", title: "Apartment 1", subtitle: "$120 per night" },
{ id: 2, lng: -97.73, lat: 30.28, label: "$85", title: "Apartment 2", subtitle: "$85 per night" },
];
```
```astro
---
import { staticUrl } from "instantmap-js/server";
import { center, listings, zoom } from "../lib/listings";
const poster = staticUrl({ center, zoom, width: 1280, height: 720, ratio: 2, markers: listings });
---
```
Astro bundles the `
```
To check it, view the page source or run `curl`:
```bash
curl -s http://localhost:4321/ | grep "` inside ``.
## Markers, popups and events
[Section titled “Markers, popups and events”](#markers-popups-and-events)
* Use attributes for simple values: `center`, `zoom`, `theme`. Attributes are strings.
* Use properties for objects. Set `map.markers = listings` in the script. Astro cannot pass an array through an attribute.
* Listen with `addEventListener`:
```ts
map?.addEventListener("markerclick", (event) => {
const { marker } = (event as CustomEvent).detail;
console.log(marker.title);
});
```
* Call methods on the element, for example `map.fitBounds(listings, { padding: 40 })`.
Markers set from the script do not change the server image. Pass the same markers to `staticUrl` so the first image matches.
## Common mistakes
[Section titled “Common mistakes”](#common-mistakes)
* Do not use `client:only`. Astro would skip the server render and you lose the instant first image. Use a plain `
```
With a bundler, import the package and call `defineInstantMap()` once. A bare `import "instantmap-js"` is dropped by the bundler.
main.ts
```ts
import { defineInstantMap } from "instantmap-js";
defineInstantMap();
```
## Render the first image on the server
[Section titled “Render the first image on the server”](#render-the-first-image-on-the-server)
Without a poster the element builds its own first image in the browser. To have the image in the server HTML, put an `![]()
` inside the element that points at `/static`. `posterHtml()` from `instantmap-js/server` returns the whole element with the image inside.
server.ts
```ts
import express from "express";
import { posterHtml } from "instantmap-js/server";
const center: [number, number] = [-97.74, 30.27];
const markers = [
{ id: 1, lng: -97.75, lat: 30.27, label: "$420", title: "Apartment 1" },
{ id: 2, lng: -97.73, lat: 30.28, label: "$385", title: "Apartment 2" },
];
const app = express();
app.get("/", (_request, response) => {
const map = posterHtml({ center, zoom: 12, width: 1200, height: 640, markers, alt: "Map of Austin", className: "map" });
response.type("html").send(`
${map}
`);
});
app.listen(3000);
```
Hono, Fastify and any other Node or Bun server work the same way. Check the response:
```sh
curl -s https://your-site.example/ | grep -o ']*static?[^>]*'
```
You should see an `![]()
` whose `src` points at `/static?`.
### Python, PHP, Rails, Django
[Section titled “Python, PHP, Rails, Django”](#python-php-rails-django)
Any language can build the same URL. The image is `https://instantmap.org/static` with `center`, `zoom`, `size`, `r` and `markers` in the query string. Each marker is `lng,lat,label`, and markers are joined with `;`. See the [HTTP API](/docs/reference/http-api/) for every parameter. Keep `,` and `;` unescaped and encode everything else.
static_url.py
```py
from urllib.parse import urlencode
def static_url(center, zoom, markers, size=(1200, 640), ratio=2):
pins = ";".join(f"{m['lng']},{m['lat']},{m['label']}" for m in markers)
query = urlencode(
{
"center": f"{center[0]},{center[1]}",
"zoom": zoom,
"size": f"{size[0]}x{size[1]}",
"r": ratio,
"markers": pins,
},
safe=",;",
)
return f"https://instantmap.org/static?{query}"
```
Put the URL in an `![]()
` inside the element, then set the markers from JavaScript as above.
template.html
```html
```
The PHP version below was not run, because PHP is not installed on the machine that wrote this guide. Test it before you rely on it.
static_url.php
```php
"{$m['lng']},{$m['lat']},{$m['label']}", $markers));
$query = http_build_query([
'center' => "{$center[0]},{$center[1]}",
'zoom' => $zoom,
'size' => "{$width}x{$height}",
'r' => $ratio,
'markers' => $pins,
], '', '&', PHP_QUERY_RFC3986);
return 'https://instantmap.org/static?' . str_replace(['%2C', '%3B'], [',', ';'], $query);
}
```
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Markers are a property. Events bubble from the element, and methods are called on it.
events.js
```js
const map = document.getElementById("map");
map.addEventListener("markerclick", (event) => {
document.getElementById("opened").textContent = event.detail.marker.title;
});
map.addEventListener("select", (event) => {
console.log(event.detail);
});
document.getElementById("downtown").addEventListener("click", () => {
map.flyTo({ center: [-97.743, 30.267], zoom: 15 });
});
listItem.addEventListener("mouseenter", () => map.highlight(1));
listItem.addEventListener("mouseleave", () => map.highlight(null));
listItem.addEventListener("click", () => map.select(1));
```
## Common mistakes
[Section titled “Common mistakes”](#common-mistakes)
* Giving the map no height. It collapses to nothing.
* Setting `markers` as an attribute. It is a property, so assign `map.markers = ...`.
* Writing marker JSON into a script tag without escaping `<`. A label containing `` ends the script.
* Setting `markers` before the element is defined. Wait for `customElements.whenDefined("instant-map")`.
* Building the poster URL with a different `center` or `zoom` than the element. The image then jumps when the map loads.
* Expecting tiles outside the covered area. The tiles cover Austin only for now.
## Prompt for your agent
[Section titled “Prompt for your agent”](#prompt-for-your-agent)
```text
Add an Instant Map to my website. Follow https://instantmap.org/docs/frameworks/html.md exactly. Load the element from the script tag or import defineInstantMap from instantmap, give the element a fixed height, set markers as a property after customElements.whenDefined, and render the first image on the server as an img inside the element pointing at /static, using posterHtml from instantmap-js/server when the server is Node or Bun. Start the site and confirm the HTML from curl contains an img with /static? in its src.
```
## Full example
[Section titled “Full example”](#full-example)
[examples/html on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/html) and [examples/express on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/express)
# Next.js
> Render an Instant Map from a Server Component with the first image in the server HTML.
Use `instantmap-js/react` in the App Router. The map works in a Server Component and sends its first image in the HTML.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Render `InstantMap` in a Server Component. Do not wrap it in `dynamic(..., { ssr: false })`.
app/page.tsx
```tsx
import { InstantMap } from "instantmap-js/react";
import { listings } from "../lib/listings";
export default function Page() {
return (
![]()
` whose `src` points at `/static?`. The browser paints it before any JavaScript loads, then the interactive map takes over.
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Event handlers and refs need a Client Component. Mark the file `"use client"` and use the handle for camera calls.
app/listings-map.tsx
```tsx
"use client";
import { useRef, useState } from "react";
import { InstantMap, type InstantMapHandle } from "instantmap-js/react";
import type { Marker } from "instantmap-js";
import type { Listing } from "../lib/listings";
export function ListingsMap({ listings }: { listings: Marker[] }) {
const map = useRef>(null);
const [clicked, setClicked] = useState | null>(null);
return (
<>
setClicked(marker)}
alt="Map of stays in Austin"
style={{ height: 480, borderRadius: 12 }}
/>
);
}
```
Pass `listings` from the Server Component as a prop. Each marker needs `id`, `lng` and `lat`. `label`, `title`, `subtitle` and `href` are optional.
## Common mistakes
[Section titled “Common mistakes”](#common-mistakes)
* Passing a function prop such as `onMarkerClick` from a Server Component. Move it into a file with `"use client"`.
* Using `ref` in a Server Component. Refs only work in Client Components.
* Giving the map no height. Set `style={{ height: 480 }}` or a class that sets one.
## Prompt for your agent
[Section titled “Prompt for your agent”](#prompt-for-your-agent)
```text
Add an Instant Map to my Next.js App Router project. Follow https://instantmap.org/docs/frameworks/nextjs.md exactly. Render InstantMap from instantmap-js/react in a Server Component with a fixed height, and put onMarkerClick and refs in a separate "use client" file. Do not use next/dynamic with ssr: false. Run the build and confirm the server HTML contains an img with /static? in its src.
```
## Full example
[Section titled “Full example”](#full-example)
[examples/nextjs on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/nextjs)
# Nuxt
> Add Instant Map to a Nuxt 4 app, with the first image rendered on the server.
You will end up with a Nuxt page that ships the first map image in the server HTML and becomes an interactive map in the browser.
## Install
[Section titled “Install”](#install)
```bash
npm install instantmap-js
```
Tell Vue that `instant-map` is a custom element.
nuxt.config.ts
```ts
export default defineNuxtConfig({
compatibilityDate: "2026-11-01",
vue: { compilerOptions: { isCustomElement: (tag) => tag === "instant-map" } },
});
```
Register the element in the browser with a client plugin.
app/plugins/instantmap.client.ts
```ts
import { defineInstantMap } from "instantmap-js";
export default defineNuxtPlugin(() => {
defineInstantMap();
});
```
## Add the map
[Section titled “Add the map”](#add-the-map)
```vue
Selected: {{ clicked.title }}, {{ clicked.subtitle }}
![Map of Austin]()
```
## Render the first image on the server
[Section titled “Render the first image on the server”](#render-the-first-image-on-the-server)
`staticUrl` runs during server rendering and returns the URL of the first image. The `![]()
` is part of the HTML Nuxt sends, so the map shows before JavaScript loads. The element takes over in the browser.
To check it, build and preview, then look at the HTML the server sends:
```bash
npm run build
npm run preview
curl -s http://localhost:3000/ | grep "` inside ``. View source in the browser shows the same.
## Markers, popups and events
[Section titled “Markers, popups and events”](#markers-popups-and-events)
* `center` and `zoom` are attributes. Bind them with `:center` and `:zoom`.
* Markers are objects, so bind them as a property: `:markers.prop="listings"`.
* Listen with `@markerclick`, `@moveend` or any other event. The payload is in `event.detail`.
* Call methods through a template ref: `map.value?.fitBounds(...)`.
* Markers set as a property do not change the server image. Pass the same markers to `staticUrl`, as above.
## Common mistakes
[Section titled “Common mistakes”](#common-mistakes)
* Registering the element in a plain plugin. Use the `.client.ts` suffix, because the element needs the browser.
* Missing `isCustomElement`. Vue warns it cannot resolve `instant-map`.
* Wrapping the map in ``. You lose the server-rendered image, which is the point.
* Mismatched poster and element. Use the same `center`, `zoom` and size, or the image jumps on hydration.
* No height. Set one on the element.
* Calling `defineInstantMap()` from server code. Keep it in the client plugin. `instantmap-js/server` is the only entry that is safe there.
## Prompt for your agent
[Section titled “Prompt for your agent”](#prompt-for-your-agent)
```text
Add Instant Map to my Nuxt 4 app. Follow https://instantmap.org/docs/frameworks/nuxt.md
Set isCustomElement in nuxt.config.ts, register the element in app/plugins/instantmap.client.ts,
render the first image on the server with staticUrl from instantmap-js/server,
and bind markers with :markers.prop.
```
## Example
[Section titled “Example”](#example)
A full working project is at [examples/nuxt](https://github.com/williamrogersdev/instantmap/tree/master/examples/nuxt).
# React
> Use Instant Map in a React app with Vite, with custom popups and list hover sync.
Use `instantmap-js/react` in any React 18 or 19 client app. This page uses Vite.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
src/app.tsx
```tsx
import { InstantMap } from "instantmap-js/react";
import { listings } from "./listings";
export function App() {
return (
>(null);
const [selected, setSelected] = useState | null>(null);
return (
(
)}
/>
);
}
```
A client-only Vite app has no server HTML, so there is no first image to render on the server. For that, use [Next.js](/docs/frameworks/nextjs/) or [React Router](/docs/frameworks/react-router/).
## Common mistakes
[Section titled “Common mistakes”](#common-mistakes)
* Creating the markers array inside the component body on every render. Memoize it, or define it outside the component.
* Giving the map no height. It collapses to nothing.
* Two copies of React in the bundle, which fails with `Cannot read properties of null (reading 'useRef')`. This happens when `instantmap-js` is installed from a local folder. Add `resolve: { dedupe: ["react", "react-dom"] }` to `vite.config.ts`.
## Prompt for your agent
[Section titled “Prompt for your agent”](#prompt-for-your-agent)
```text
Add an Instant Map to my React and Vite app. Follow https://instantmap.org/docs/frameworks/react.md exactly. Use InstantMap from instantmap-js/react with a fixed height, renderPopup for the popup card, and a ref with highlight(id) to sync a list with the map. Memoize the markers array. Run the build and open the page to confirm the map loads with no console errors.
```
## Full example
[Section titled “Full example”](#full-example)
[examples/react-vite on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/react-vite)
# React Router
> Render an Instant Map in React Router v7 framework mode with the first image in the server HTML.
Use `instantmap-js/react` in React Router v7 framework mode. The loader supplies the markers and the server renders the first image.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Return the markers from the route loader and render `InstantMap` in the component.
app/routes/home.tsx
```tsx
import { InstantMap } from "instantmap-js/react";
import { listings } from "../listings";
import type { Route } from "./+types/home";
export function loader() {
return { listings };
}
export default function Home({ loaderData }: Route.ComponentProps) {
return (
![]()
` whose `src` points at `/static?`. The browser paints it before JavaScript loads.
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Use a ref for camera calls and `onMarkerClick` for clicks. Both work in the route component.
app/routes/home.tsx
```tsx
import { useRef, useState } from "react";
import { InstantMap, type InstantMapHandle } from "instantmap-js/react";
import type { Marker } from "instantmap-js";
import type { Listing } from "../listings";
import type { Route } from "./+types/home";
export default function Home({ loaderData }: Route.ComponentProps) {
const { listings } = loaderData;
const map = useRef>(null);
const [clicked, setClicked] = useState | null>(null);
return (
<>
` element in a Solid component. Solid has special prefixes for custom elements: `attr:` for attributes, `prop:` for properties and `on:` for events.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Call `defineInstantMap()` once before rendering. A bare `import "instantmap-js"` is dropped by the bundler, so the element never gets defined.
src/index.tsx
```tsx
import { defineInstantMap } from "instantmap-js";
import { render } from "solid-js/web";
import { App } from "./app";
defineInstantMap();
render(() => & {
ref?: InstantMapElement | ((element: InstantMapElement) => void);
"attr:center"?: string;
"attr:zoom"?: number | string;
"prop:markers"?: Marker[];
"on:markerclick"?: (event: InstantMapEventMap["markerclick"]) => void;
};
}
}
}
```
src/app.tsx
```tsx
import { staticUrl } from "instantmap-js/server";
import { listings } from "./listings";
const center: [number, number] = [-97.74, 30.27];
const zoom = 12;
const markers = listings();
const poster = staticUrl({ center, zoom, width: 1200, height: 640, ratio: 2, markers });
export function App() {
return (
);
}
```
## Render the first image on the server
[Section titled “Render the first image on the server”](#render-the-first-image-on-the-server)
A Vite and Solid app renders in the browser, so the server HTML has an empty root. The `/static` poster is the first map request once Solid renders, and the element swaps it for the live map. For a first image in the server HTML, render the same component with SolidStart.
Check what loads first:
```sh
npm run build
npm run preview
```
Open the page with the network panel on. The `/static?` image is the first map request.
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Use `on:markerclick` and a `ref` for camera calls.
src/app.tsx
```tsx
import { createSignal } from "solid-js";
import type { InstantMapElement } from "instantmap-js";
export function App() {
let map: InstantMapElement | undefined;
const [opened, setOpened] = createSignal("Click a price to open its card.");
return (
<>
setOpened(`${event.detail.marker.title}, ${event.detail.marker.label}`)}
attr:center={center.join(",")}
attr:zoom={zoom}
prop:markers={markers}
/>
` element directly in a SvelteKit page. The load function builds the first image on the server, and the element takes over in the browser.
## Install
[Section titled “Install”](#install)
```sh
npm install instantmap-js
```
## Add the map
[Section titled “Add the map”](#add-the-map)
Build the poster URL in `+page.server.ts` so it is part of the server HTML.
src/routes/+page.server.ts
```ts
import { staticUrl } from 'instantmap-js/server';
import { listings } from '$lib/listings';
const center: [number, number] = [-97.74, 30.27];
const zoom = 12;
export function load() {
const markers = listings();
return {
markers,
center,
zoom,
poster: staticUrl({ center, zoom, width: 1200, height: 640, ratio: 2, markers })
};
}
```
Define the element in `onMount`, then give it the markers. The element only exists in the browser, so import it there.
src/routes/+page.svelte
```svelte
```
## Render the first image on the server
[Section titled “Render the first image on the server”](#render-the-first-image-on-the-server)
The `![]()
` is inside the element and is rendered by SvelteKit, so it is in the HTML before any JavaScript runs. Check it:
```sh
curl -s https://your-site.example/ | grep -o ']*static?[^>]*'
```
You should see an `![]()
` whose `src` points at `/static?`.
## Markers, popups, events
[Section titled “Markers, popups, events”](#markers-popups-events)
Set `markers` as a property. Listen with an `on` attribute, and call methods on the bound element.
src/routes/+page.svelte
```svelte
>(null);
const [bounds, setBounds] = useState(null);
const [selected, setSelected] = useState(null);
const markers = useMemo(
() => listings.map((l) => ({ id: l.id, lng: l.lng, lat: l.lat, label: `$${l.price}`, title: l.title, image: l.photo, href: `/listings/${l.id}`, data: l })),
[listings],
);
const visible = bounds
? listings.filter((l) => l.lng >= bounds[0] && l.lng <= bounds[2] && l.lat >= bounds[1] && l.lat <= bounds[3])
: listings;
return (
setBounds(map.current?.bounds ?? null)}
onSelect={(marker) => {
setSelected(marker ? String(marker.id) : null);
if (marker) document.getElementById(`listing-${marker.id}`)?.scrollIntoView({ block: "nearest", behavior: "smooth" });
}}
/>
);
}
```
## Details that matter
[Section titled “Details that matter”](#details-that-matter)
* **Highlight, don’t select, on hover.** `highlight()` only lifts the pin. `select()` opens a card, and opening cards as the pointer crosses a list is noisy.
* **A highlighted marker inside a cluster** lifts the whole cluster, so the visitor still sees where it is.
* **Show all results** after a search: `map.fitBounds(markers, { padding: 64 })`.
* **On phones**, stack the map above the list at 40–50% of the viewport height. Keep the map’s `scroll-zoom` at `cooperative` so the page still scrolls past it.
# Markers and clusters
> Feed the map your data, keep it in sync, and control clustering.
## The shape
[Section titled “The shape”](#the-shape)
The map takes plain objects. Map your records to them once:
```ts
map.markers = stores.map((store) => ({
id: store.id, // unique, string or number
lng: store.longitude, // longitude first, always
lat: store.latitude,
label: store.openNow ? "Open" : undefined, // a short pill label, or nothing for a dot
title: store.name,
subtitle: store.address,
badge: store.isNew ? "New" : undefined,
image: store.photoUrl, // about 560 px wide, see Cards and popups
href: `/stores/${store.slug}`,
data: store, // the original record, typed through Marker
}));
```
| Field | Drawn as |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| `label` set | A pill with the text, for example `$420`, `4.8★`, `Open` or `12 min`. Ten characters at most. |
| no `label` | A dot in the theme’s `accent` colour. |
| several markers close together | A cluster bubble showing the count. Clicking it zooms in. |
The `title`, `subtitle`, `badge`, `image`, `href` and `label` fields fill the card that opens when a marker is clicked. See [Cards and popups](/docs/guides/popups/). Card photos are fetched ahead of the click for the markers nearest the centre, so serve them about 560 px wide, in WebP or AVIF, with long cache headers.
## Updating
[Section titled “Updating”](#updating)
Assign a new array. The map re-clusters (fast enough for tens of thousands of markers) and redraws on the next frame:
```js
map.markers = map.markers.filter((marker) => marker.data.price < maxPrice);
```
Changing the array keeps the camera, the open popup (if its marker is still there) and the selection.
## Clustering
[Section titled “Clustering”](#clustering)
```html
```
How the template is filled:
* `{{title}}`, `{{data.beds}}` and any other marker field or `data` path are replaced with the value as **text**. A value can never add markup.
* In `href`, `src` and similar address attributes, the value goes through the same address check as the built-in card. An address that fails the check removes the attribute.
* `srcset` and `style` attributes that contain a `{{…}}` are removed.
* An element with `data-if="field"` is dropped when that field is empty.
* Any `on…` attribute, such as `onclick`, is removed.
* An element with `data-close` (or a `button.close`) closes the card.
* The template must be a direct child of ``.
## Fast card images
[Section titled “Fast card images”](#fast-card-images)
The card opens with its photo already loaded when it can. The `card-images` attribute (the `cardImages` prop in React) controls this.
| Value | Behaviour |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `visible` (default) | When the map settles, the images of up to 8 single markers nearest the centre are fetched in idle time. |
| `hover` | Images are fetched only when the pointer is over a marker, and on press. |
| `off` | No fetching ahead. The card loads its photo when it opens. |
With `visible`, nothing is fetched ahead when the visitor has Save-Data on or a 2G connection. In every mode except `off`, an image is also fetched when the pointer is over its marker and when the marker is pressed. The map also adds a `preconnect` for up to two image origins.
To keep photos light:
* Serve card images about 560 px wide. The card is 264 px wide, so that covers a 2x screen.
* Use WebP or AVIF.
* Send long cache headers, such as `Cache-Control: public, max-age=31536000, immutable`, for images with versioned file names.
## Your own popup
[Section titled “Your own popup”](#your-own-popup)
`map.popup` decides what a selected marker shows:
| Value | Result |
| ------------------- | ------------------------------------------------------------------ |
| unset (the default) | The built-in card, or your `` if there is one. |
| a function | Your own renderer. |
| `null` | No card. |
```js
map.popup = (marker) => {
const card = document.createElement("article");
card.className = "my-card";
const heading = document.createElement("h3");
heading.textContent = marker.title;
const button = document.createElement("button");
button.textContent = "Add to cart";
button.onclick = () => addToCart(marker.id);
card.append(heading, button);
return card;
};
```
Return an element or an HTML string, or return `null` or an empty string to show nothing for that marker. The popup lives in your page, so your stylesheets, Tailwind and design-system classes apply.
Caution
A returned HTML string is inserted as markup. Escape any user content in it, or build elements and set `textContent`.
If you need the built-in card inside your own renderer, import it from `instantmap-js/card`:
```js
import { defaultCard } from "instantmap-js/card";
map.popup = (marker) => (marker.data.soldOut ? null : defaultCard(marker, { layout: "row" }));
```
`instantmap-js/card` also exports `cardFromTemplate`, `safeUrl`, `escapeHtml` and `CARD_CSS`.
### React
[Section titled “React”](#react)
```tsx
```
Always set `width` and `height` so the page doesn’t shift while the image loads. For anything above the fold, set `loading="eager"` and `fetchpriority="high"`.
## Build the URL in code
[Section titled “Build the URL in code”](#build-the-url-in-code)
```ts
import { staticUrl } from "instantmap-js/server";
const src = staticUrl({ center: [-73.9857, 40.7484], zoom: 14, width: 640, height: 360, ratio: 2, markers: [{ lng: -73.9857, lat: 40.7484 }] });
```
`staticUrl()` is a pure function with no dependencies. It runs in Node, Bun, Deno, Workers and the browser.
For other languages, build the query string yourself; the format is in the [HTTP API](/docs/reference/http-api/). Ruby, for example:
```ruby
params = { center: "#{lng},#{lat}", zoom: 13, size: "640x360", r: 2, markers: "#{lng},#{lat},$#{price}" }
url = "https://instantmap.org/static?#{URI.encode_www_form(params)}"
```
## Lighter images on slow connections
[Section titled “Lighter images on slow connections”](#lighter-images-on-slow-connections)
A 2× image is about three times the bytes of a 1× image. The element chooses for itself (see the [`detail` attribute](/docs/reference/element/)). When your server builds the address, it can do the same: browsers that support it send a `Save-Data: on` request header when the visitor has asked to save data.
```ts
const saveData = request.headers.get("save-data") === "on";
const src = staticUrl({ center, zoom, width: 640, height: 360, ratio: saveData ? 1 : 2 });
```
If you cache the page, add `Vary: Save-Data` to its response so the two versions are kept apart.
## Email
[Section titled “Email”](#email)
Email clients block scripts and many block CSS, but they all show images. Use `r=2`, keep the width at 600 or less, and link the image to the full page:
```html
```
Gmail and Outlook proxy and cache the image, which is fine: the URL always renders the same picture.
## Open Graph and social cards
[Section titled “Open Graph and social cards”](#open-graph-and-social-cards)
Use 1200×630 for link previews. Requests are capped at 1280 px per side, so use `r=1`:
```html
```
## PNG
[Section titled “PNG”](#png)
Add `format=png` for print, transparency workflows or pixel-exact tests. JPEG is three to five times smaller for the same map.
# Customising the look
> Build a map theme from your brand colours, pick a theme, recolour it with tokens, restyle controls and cards, and keep the first image in sync.
The look has four layers, from broadest to narrowest:
1. **Brand colours.** Give `brandTheme()` the colours from your style guide and it returns a theme and the colours to go with it.
2. **Theme.** One of `daylight`, `midnight`, `paper` or `mono`.
3. **Colour tokens.** Override any of the [36 tokens](/docs/reference/themes/) on top of the theme.
4. **CSS.** Restyle the controls, attribution and [cards](/docs/guides/popups/) like any other part of your page.
The server reads layers 1 to 3 too, so the first image is painted in your colours.
## Brand colours from your style guide
[Section titled “Brand colours from your style guide”](#brand-colours-from-your-style-guide)
`brandTheme()` turns a handful of colours into a whole map palette: land, water, parks, roads, labels, markers and clusters. Only `primary` is required.
```ts
import { brandTheme } from "instantmap-js"; // or "instantmap-js/server", or "instantmap-js/brand"
const brand = brandTheme({ primary: "#e11d48", background: "#fff7ed", foreground: "#1c1917" });
// { theme: "daylight", colors: { marker: "#…", cluster: "#…", land: "#…", … } }
```
| Input | Used for | Default |
| -------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------- |
| `primary` (required) | Markers, clusters and highways | |
| `background` | The page colour. Land is a tint of it. | Near-white, or near-black when `mode` is `"dark"` |
| `foreground` | Text colour. Labels and outlines are mixed from it. | Dark ink, or light ink on a dark background |
| `accent` | The selected marker | The foreground colour |
| `water` | Water | A quiet blue leaning toward `primary` |
| `park` | Parks and forests | A quiet green |
| `mode` | `"light"` or `"dark"` | Decided from `background` |
| `tint` | How strongly `primary` tints land, water and roads, from `0` (neutral) to `1` | `0.5` |
Colours can be `#rgb`, `#rrggbb`, `rgb()`, `hsl()`, or the bare `h s% l%` triplets that shadcn-style tokens use, such as `222.2 47.4% 11.2%`.
The result is `{ theme, colors }`. It builds on `daylight` (or `midnight` for dark brands) and lists only the colours that differ. Label and marker text colours are chosen so they stay readable against the colour behind them.
Spread it wherever you give a theme and colours:
```ts
import { staticUrl } from "instantmap-js/server";
const src = staticUrl({ center: [-122.42, 37.77], zoom: 12, width: 960, height: 480, ratio: 2, markers, ...brand });
```
```tsx
```
The `colors` attribute is a comma-separated list of `token:hex` pairs, without the `#`. Tokens are written in alphabetical order when the library builds the value for you, so the same colours always give the same address.
## Dark mode that follows the page
[Section titled “Dark mode that follows the page”](#dark-mode-that-follows-the-page)
```js
const media = matchMedia("(prefers-color-scheme: dark)");
const apply = () => (map.theme = media.matches ? "midnight" : "daylight");
media.addEventListener("change", apply);
apply();
```
On the server, pick the theme for the first image from the visitor’s `Sec-CH-Prefers-Color-Scheme` header, or from a cookie you set. For a brand with both a light and a dark set of colours, build two `brandTheme()` results and switch between them the same way.
## Quieter maps for data
[Section titled “Quieter maps for data”](#quieter-maps-for-data)
Use `mono` when your markers carry the meaning and the map is only context:
```html
{{ opened() }}
``` ## Common mistakes [Section titled “Common mistakes”](#common-mistakes) * Starting Angular before `import('instantmap-js')` finishes. `markers` is then bound to an undefined element and never reaches the map. * Putting `style="..."` on `{clicked ? `Opened ${clicked.title}` : "Click a pin"}
-
{listings.slice(0, 40).map((listing) => (
- map.current?.highlight(listing.id)} onPointerLeave={() => map.current?.highlight(null)} > {listing.title} {listing.subtitle} ))}
{clicked ? `Opened ${clicked.title}` : "Click a pin"}
{opened()}
); } ``` ## Common mistakes [Section titled “Common mistakes”](#common-mistakes) * Writing `center="..."` or `markers={...}` without a prefix. Solid sets them as properties and the element ignores them. Use `attr:` for strings and `prop:` for the markers array. * Writing `onMarkerClick`. Solid lowercases event names for custom elements. Use `on:markerclick`. * Importing `instantmap-js` for its side effect only. Call `defineInstantMap()`. * Giving the map no height. It collapses to nothing. ## Prompt for your agent [Section titled “Prompt for your agent”](#prompt-for-your-agent) ```text Add an Instant Map to my SolidJS app. Follow https://instantmap.org/docs/frameworks/solid.md exactly. Call defineInstantMap() from instantmap before render, declare instant-map in the solid-js JSX IntrinsicElements, and use attr:center, attr:zoom, prop:markers and on:markerclick on the element. Render a staticUrl poster img from instantmap-js/server inside it and give the map a fixed height. Build and confirm the page loads a /static? image first. ``` ## Full example [Section titled “Full example”](#full-example) [examples/solid on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/solid) # SvelteKit > Render an Instant Map in SvelteKit with the first image in the server HTML. Use the `{opened}
``` ## Common mistakes [Section titled “Common mistakes”](#common-mistakes) * Importing `instantmap-js` at the top of the file. It touches `customElements`, which does not exist on the server. Import it inside `onMount`. * Giving the map no height. It collapses to nothing. * Setting `markers` as an attribute. It is a property, so assign `map.markers = ...`. * Building the poster URL in the browser. The server HTML then has no first image. ## Prompt for your agent [Section titled “Prompt for your agent”](#prompt-for-your-agent) ```text Add an Instant Map to my SvelteKit app. Follow https://instantmap.org/docs/frameworks/sveltekit.md exactly. Build the poster URL with staticUrl from instantmap-js/server in +page.server.ts, render it as an img inside the instant-map element, and import instantmap inside onMount before setting map.markers. Give the map a fixed height. Build, start the server, and confirm the HTML from curl contains an img with /static? in its src. ``` ## Full example [Section titled “Full example”](#full-example) [examples/sveltekit on GitHub](https://github.com/williamrogersdev/instantmap/tree/master/examples/sveltekit) # Vue > Add Instant Map to a Vue 3 app with Vite. You will end up with a Vue 3 component that shows an interactive map with markers, reacts to marker clicks and can fit the view to your data. ## Install [Section titled “Install”](#install) ```bash npm install instantmap-js ``` Tell Vue that `instant-map` is a custom element, not a component. vite.config.ts ```ts import vue from "@vitejs/plugin-vue"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "instant-map" } }, }), ], }); ``` ## Add the map [Section titled “Add the map”](#add-the-map) ```vue Selected: {{ clicked.title }}, {{ clicked.subtitle }}-
{visible.map((l) => (
- map.current?.highlight(l.id)} onPointerLeave={() => map.current?.highlight(null)} > {l.title}, ${l.price} ))}
{{title}}
{{subtitle}} · {{data.beds}} beds
Open {{label}}