Sources@knitui/map

SVG Icon

SvgImage registers an SVG resource as a named MapLibre image so a SymbolLayer can draw it as a fixed-size icon (iconImage + iconSize) that stays the same screen size at every zoom level — the usual pin/marker behaviour. SVG resources are rasterized to a bitmap via react-native-svg on both web and native (identical output on each platform); the marker is then drawn on the GPU by MapLibre, so a single icon backs thousands of markers with no per-marker DOM or native view. Raster resources (a source asset, or a non-SVG uri) are registered directly.

WebiOSAndroid8 own props7 examples

Stories Source Open in Storybook

import { SvgImage } from "@knitui/map";

Playground

Loading playground…

Playground

<SvgImage
  id="pin"
  svg={pin("#ef4444")}
  width={40}
  height={40}
/>

Examples

Fixed Size Icons

The SVG pin is drawn as a 40px icon at three cities. Zoom in/out — the pins keep their pixel size instead of scaling with the map.

Loading example…

Fixed Size IconsSource Storybook

From Url

The icon is loaded from a URL rather than inline markup. An .svg (or data:image/svg+xml) URL is fetched and rasterized; here we use a data: URL so the story runs offline, but any CORS-enabled https://…/pin.svg works the same way.

Loading example…

From UrlSource Storybook

Data Driven Icons

Several distinct icons registered at once via SvgImages, with each marker choosing its icon from its category property through a data-driven iconImage expression. Still a single GPU SymbolLayer.

Loading example…

Data Driven IconsSource Storybook

Ten Thousand Markers

10,000 SVG-icon markers, unclustered — every point is its own symbol. iconAllowOverlap/iconIgnorePlacement keep them all visible (no collision thinning), which is the stress case for this many symbols.

Loading example…

Ten Thousand MarkersSource Storybook

Ten Thousand Data Driven

10,000 markers across three icon types selected by category, unclustered. One rasterized bitmap per type, one GPU SymbolLayer drawing them all.

Loading example…

Ten Thousand Data DrivenSource Storybook

Ten Thousand Clustered

The same 10,000 points, clustered. The source aggregates dense points into count bubbles (cluster); a CircleLayer + SymbolLayer render the clusters (sized/colored by point_count), and individual leaves fall back to the SVG pin. Zoom in to break clusters apart.

Loading example…

Ten Thousand ClusteredSource Storybook

Fifty Thousand Clustered

50,000 markers, clustered — the recommended way to show this many points. supercluster aggregates dense points into count bubbles that split apart as you zoom in, keeping the visible symbol count low at every zoom and well under MapLibre's per-bucket symbol limit.

Loading example…

Fifty Thousand ClusteredSource Storybook

Props

Prop	Type	Default	Description
`id` required	`string`	—	Image id referenced by a `SymbolLayer` via `iconImage`.
`height`	`number \| undefined`	—	Target height in CSS pixels. Defaults to the SVG's intrinsic height.
`pixelRatio`	`number \| undefined`	—	Multiplier for the rasterized bitmap resolution (crispness). Default `1`.
`sdf`	`boolean \| undefined`	—	Render as a signed-distance-field icon (recolorable via `iconColor`).
`source`	`ImageEntry \| undefined`	—	Pre-rasterized image registered as-is (a `require()` asset or `{ uri }`). Skips rasterization; takes precedence over `svg`/`uri`.
`svg`	`string \| undefined`	—	Inline SVG markup. Rasterized to a bitmap on both web and native.
`uri`	`string \| undefined`	—	URL of a resource. An `.svg` (or `data:image/svg+xml`) URL is fetched and rasterized; any other URL (`.png`, `.jpg`, …) is registered directly as a raster. Ignored when `svg` or `source` is provided.
`width`	`number \| undefined`	—	Target width in CSS pixels. Defaults to the SVG's intrinsic width.