brand-ui — MapPlanImage

import { MapPlanImage } from "@elabs-ai/components-maps";

Install

npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-maps

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui MapPlanImage component (from @elabs-ai/components-maps) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look MapPlanImage up before writing code: `npx -y @elabs-ai/components-cli docs MapPlanImage` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-maps is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-maps` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-maps`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Avoid

One baked-in-colour picture for every theme — a white floor plan either glares or swallows the data ink on a dark theme. Prefer vector-only, else swap the asset on the resolved theme, else desaturate it and dim it.
Tearing the component down to hide a floor — set `visible` (a visibility change) or swap `src`, so nothing refetches and nothing cross-fades.
Zooming a raster far past its native resolution — past roughly 2× it is mush; the shapes stay crisp, so let them carry the detail.

Works with

Used inside

MapCanvas

Pairs with

Examples

6 live examples

Over One Wing

One wing only: `extent` places the picture in plan units, not across the whole plan.

Floor Swap

A floor swap: the same source, a new drawing — no refetch, no cross-fade.

Hidden

`visible={false}` toggles the layer’s visibility; the source stays, so nothing reloads.

Loading

Nothing loaded yet: the canvas keeps the plan’s shape and says so once.

Missing Picture

The picture failed; the plan did not. `onError` reports it and the shapes stay, so the consumer decides what the gap should look like.

API

`MapPlanImage`

Prop	Type	Description
`src`required	`MapPlanImageSource \| { light: MapPlanImageSource; dark: MapPlanImageSource }`	The plan picture. Pass `{ light, dark }` to swap it with the theme.
`alt`	`string`	What the picture shows, for anyone who cannot see it ("Level 3 floor plan, 14 rooms around a central core"). A plan drawn into WebGL has no accessible name of its own, so this is the only description of it.
`id`	`string`	Optional identifier for the source/layer. Auto-generated if not provided.
`extent`	`{ x: number; y: number; width: number; height: number }`	Where the picture sits, in PLAN units. Defaults to the whole plan extent, so a single full-bleed plan needs nothing here. Use it to place one wing, one machine cell or one carriage inside a larger plan.
`coordinates`	`MapLibreGL.Coordinates`	The four corners in lng/lat (top-left, top-right, bottom-right, bottom-left) — an escape hatch that also works on an ordinary geographic canvas, like Leaflet's `imageOverlay`. Wins over `extent`.
`opacity`	`number`	Opacity, 0–1 (default 1). A photographic or ink-heavy plan usually reads best held back around 0.35 so the data drawn on top stays the focus.
`visible`	`boolean`	Hide the picture without tearing the source down — a multi-floor switch (default true).
`resampling`	`"linear" \| "nearest"`	`"nearest"` keeps CAD line art crisp when zoomed past its native resolution.
`beforeId`	`string`	MapLibre layer id to insert this layer before (z-order control).
`onLoad`	`() => void`	Fired once the picture has been fetched and decoded.
`onError`	`(error: Error) => void`	Fired when the picture cannot be loaded. The plan itself keeps working without it.

Theming

The tokens each state resolves to. Change the token and every theme follows.

State	Token
surface	`always a --card layer under the raster at raster-opacity 0.30–0.40: the picture is context, the shapes are the ink`