Map Embed

A map on CARTO's near-monochrome basemap. A full-colour street map fights everything drawn on top of it; a greyscale ground lets the marker be the only saturated thing on screen.

src/components/ui/map-embed.tsx

About

From the component's own source, where it was written.

A map, drawn from raster tiles.

The look is near-monochrome by default. A full-colour street map fights everything drawn on top of it; a greyscale ground lets a marker, a route or a heat layer be the only saturated thing on screen, which is why analytics products use styles like CARTO's Dark Matter.

Those styles need an API key, so the default source here is OpenStreetMap's standard tiles — genuinely keyless — desaturated in CSS instead. invert after grayscale turns the light basemap dark, which lands close to Dark Matter with no token and no third-party account. It is a filter rather than a real dark cartography, and it is worth being honest that it approximates one.

OSM's Tile Usage Policy asks that their servers not carry a production product's traffic. For anything past local work and internal tools, pass tiles as a function pointing at your own or a keyed provider; filter={null} then turns the CSS treatment off when that style is already monochrome.

Tiles are plain <img> elements in a grid — no iframe, no mapping library, so no third-party JavaScript or cookies. The remaining exposure is the tile requests themselves, the same as any remote image. This is a static view by design: anything needing pan and zoom wants MapLibre, not this.

Install

npx astralyx-ui add map-embed

Usage

import { MapEmbed } from '@/components/ui/map-embed'

<MapEmbed lat={51.5074} lng={-0.1278} label="Trafalgar Square, London" />

Composer

Change the props and the source below follows.

Trafalgar Square, London© OpenStreetMap contributorsOpen map

Props

theme

zoom

monochrome filtermarker

tsx

<MapEmbed
  lat={51.5074}
  lng={-0.1278}
  zoom={14}
  theme="dark"
  label="Trafalgar Square"
/>

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`MapEmbed`

Extends Omit<ComponentProps<'figure'>, 'children'>.

Prop	Type	Default	Description
lat	number	required	—
lng	number	required	—
zoom	number	14	—
tiles	TileSource	'osm'	OpenStreetMap's keyless tiles by default. CARTO's Dark Matter and Positron need an API key, so the monochrome look here comes from a CSS filter instead. Pass `(z, x, y) => url` for your own or a keyed provider — OSM's usage policy asks their servers not carry production traffic.
theme	MapTheme	'dark'	'dark' inverts a greyscale raster to a dark ground; 'light' desaturates it. 'auto' renders both layers and lets CSS pick, so the theme toggle costs no tile requests.
filter	string \| null	—	Overrides the CSS treatment. `null` leaves tiles alone — right when your provider already serves a monochrome style.
marker	boolean	true	—
label	ReactNode	—	Place name, shown in the caption and used as the image description.
eager	boolean	true	Set false to hold the tiles behind a click, which is where a consent gate goes.
height	number \| string	280	—
linkOut	boolean	true	—
loadLabel	ReactNode	'Load map'	—
consentNote	ReactNode	—	—
attribution	ReactNode	—	Overrides the CARTO/OpenStreetMap credit. It is rendered by default because both providers require it.
linkLabel	ReactNode	'Open map'	—

Functions

Function	Signature	Description
mapFilters	{ readonly dark: 'grayscale(1) invert(1) brightness(0.92) contrast(1.08)'; readonly light: 'grayscale(1) brightness(1.04) contrast(0.96)'; }	Desaturation applied to a full-colour raster. `invert` after `grayscale` is what produces the dark ground; the brightness and contrast nudges stop roads blowing out to white and keep labels legible.
projectMercator	(lat: number, lng: number, zoom: number) => { x: number; y: number; }	Longitude/latitude to fractional tile coordinates at a zoom level.
osmUrl	(z: number, x: number, y: number) => string	OSM standard. Keyless; no retina variant and no dark style of its own.

Types

Type	Definition	Description
`MapTheme`	'dark' \| 'light' \| 'auto'	A map, drawn from raster tiles.
`TileSource`	'osm' \| ((z: number, x: number, y: number) => string)	—

Behaviour

Topic	Detail	Description
rendering	raster tiles	Plain `<img>` tiles in a grid — no iframe, no mapping library, no third-party JavaScript or cookies. The remaining exposure is the tile requests, the same as any remote image.
interaction	none	A static view. Anything needing pan and zoom wants MapLibre; this is deliberately not that.