MapView

Code

import { MapView } from "@fadymondy/nasaq/web";import { Truck } from "lucide-react";export function Fleet() {  return (    <MapView      label="Fleet"      layers={[{ id: "vans", label: "Vans", labelAr: "الشاحنات", tone: "info" }]}      pins={[{ id: "v1", lat: 24.7136, lng: 46.6753, label: "Van 12", labelAr: "شاحنة 12", layer: "vans", tone: "info", icon: Truck, status: "Moving", statusAr: "تتحرك" }]}      routes={[{ id: "r1", layer: "vans", label: "Route A", points: [{ lat: 24.71, lng: 46.67 }, { lat: 24.75, lng: 46.72 }] }]}      tileUrl="https://tile.example.com/{z}/{x}/{y}.png"      attribution="© Example maps"    />  );}

Charts & Maps · stable

Live examples and controls: MapView in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/map-view.json

Where things are. MapView draws pins and route lines over a base that is either your tile server or a quiet grid of latitude and longitude lines. It has a legend with layer toggles, zoom and pan, a scale bar and a card for the selected pin. There is no map library and no key: Nasaq does not ship a tile service, so set tileUrl to one you are allowed to use, and show its credit with attribution.

When to useCopy Anchor Link

• A fleet, delivery, branch or field-team view where place matters more than the numbers.
• Next to a list: select a row and show its pin (GeoList is the ranked-table cousin).

When not to useCopy Anchor Link

• Turn-by-turn navigation, geocoding or address search: these need a routing service.
• Tens of thousands of pins: clustering is done in the browser on every zoom, and it is built for hundreds. Filter with layers or cluster on the server first.

ImportCopy Anchor Link

import { MapView, type MapPin, type MapLayer, type MapRoute } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

import { MapView } from "@fadymondy/nasaq/web";
import { Truck } from "lucide-react";

export function Fleet() {
  return (
    <MapView
      label="Fleet"
      layers={[{ id: "vans", label: "Vans", labelAr: "الشاحنات", tone: "info" }]}
      pins={[{ id: "v1", lat: 24.7136, lng: 46.6753, label: "Van 12", labelAr: "شاحنة 12", layer: "vans", tone: "info", icon: Truck, status: "Moving", statusAr: "تتحرك" }]}
      routes={[{ id: "r1", layer: "vans", label: "Route A", points: [{ lat: 24.71, lng: 46.67 }, { lat: 24.75, lng: 46.72 }] }]}
      tileUrl="https://tile.example.com/{z}/{x}/{y}.png"
      attribution="© Example maps"
    />
  );
}

AnatomyCopy Anchor Link

MapView                       data-slot="map-view"  dir="ltr"  role="group" (map)
├─ tiles (img) or grid (svg)  base
├─ svg                        areas (data-slot="map-areas"): one polygon each, data-area
├─ svg                        routes: casing + line + start and end dots
├─ button[data-pin]           one per visible pin, in a ContextMenuActions when pinActions is set
├─ button[data-cluster]       a count bubble for pins that are close together (see Clustering)
├─ legend                     layers panel (collapsed by default): toggles, zones, routes with their length
├─ [data-picked-point]        draggable pin while `pickedPoint` is set
├─ svg + [data-vertex]        dashed shape and draggable vertices while `editing` (data-slot="map-edit-shape")
├─ toolbar                    Remove last point, Finish shape (data-slot="map-edit-toolbar")
├─ zoom in, zoom out, fit     buttons at the inline end
├─ scale bar, attribution
├─ section                    location card of the selected pin
└─ section[data-slot=map-cluster-card]   list of the pins in a cluster at the max cluster zoom

APICopy Anchor Link

ClusteringCopy Anchor Link

Pins are grouped by their distance in px on the same Web Mercator projection the map draws with, so a bubble depends on the zoom and never on where you have panned to. Zooming in pulls the pins apart and the bubbles split; zooming out merges them again.

• A bubble shows the number of pins, grows with it (36 to 64 px) and uses the brand action colour.
• Click, or Enter or Space, zooms and centres so the pins of the bubble fit, at least one step in.
• From zoom 16 (MAP_CLUSTER_MAX_ZOOM, or maxZoom if lower) only pins on the same spot stay together, so pins with equal coordinates cannot cluster forever. Activating such a bubble lists its pins in the card; choose one to select it.
• The selected pin is never inside a bubble: it stays a pin, and the bubble count leaves it out.
• Pins that are hidden by a layer are not counted. Routes are not clustered.

<MapView pins={manyPins} clusterRadius={80} renderCluster={(c) => <span className="text-caption">{c.count}</span>} />

Geometry helpers (no React)Copy Anchor Link

mapProject, mapUnproject, mapToScreen, mapFromScreen, mapFit, mapPanBy, mapZoomAt, mapDistance, mapPointInPolygon(point, ring) (even-odd hit test), mapRouteLength, mapFormatCoordinates, mapBounds, and for clustering mapCluster(pins, zoom, { radius, maxZoom, selectedId }) and mapClusterExpand(pins, view, size) (the view to move to and whether to list the pins).

AccessibilityCopy Anchor Link

• Every pin is a button named by its label; the selected one says so and has aria-pressed.
• Every bubble is a button named like "12 pins, zoom in" ("12 pins, show the list" at the max cluster zoom).
• Everything the map shows is also in the legend (counts, routes with length) and the card, as text.
• Zoom buttons and the fit button work without a pointer; wheel zoom only adds a shortcut.

RTL & i18nCopy Anchor Link

• The canvas is always dir="ltr": a map does not mirror. The legend, the card and the buttons follow the page direction, and the buttons swap sides.
• Coordinates and lengths are Latin digits, isolated with bdi.
• Pins carry labelAr, detailAr and statusAr.

Styling & tokensCopy Anchor Link

Bubbles use the brand action colour with a card-colour border and a soft ring. Status tones use nq-info, nq-success, nq-warning, nq-danger and the brand action colour; route casing uses the card colour so lines stay readable on dark tiles.

Do / Don'tCopy Anchor Link

• Do show the tile provider's credit.
• Do put the same information in a list next to the map for people who cannot use a pointer.
• Do keep a list next to a clustered map: a bubble is a shortcut to the pins, not the only way to them.
• Do not use colour alone: pins carry an icon and the card carries a status word.
• Do not point tileUrl at a service whose terms forbid your traffic.

RelatedCopy Anchor Link

• GeoList
• EntityList
• ContextMenu

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-charts-maps-map-view--docs