MapScale

Ground scale

Local ground resolution

m/CSS px

Scale units

Map scale

200 m

<MapScale
  label="Scale at map center"
  metersPerPixel={frame.metersPerPixel}
  maxWidth={120}
  units="metric"
/>

Supply positive finite ground meters per CSS pixel at a documented map location. The adapter owns projection and resolution; MapScale does not infer physical screen DPI or promise uniform scale across the map.

The bar selects a distance from the 1/2/5 sequence within maxWidth (default 120 CSS pixels) and the measured available width. It recalculates the label when the container narrows. Metric uses meters/kilometers; imperial uses feet/miles. The same ground resolution supplies both. A missing, zero, negative or nonfinite resolution, or invalid width, shows Scale unavailable.

Props

PROP	TYPE	DEFAULT	REQUIRED
`label`	`string`	`"Map scale"`	no
`metersPerPixel` Positive finite local ground meters per CSS pixel. Missing/null/nonpositive/nonfinite values show Scale unavailable. Adapter owns projection and scale location.	`number`	—	no
`maxWidth` Positive finite maximum bar width in CSS pixels. Recomputes against narrower measured container width rather than shrinking a mislabeled bar.	`number`	`120`	no
`units` Metric uses m/km; imperial uses ft/mi. Both derive from the same supplied ground resolution.	`enum` metric \| imperial	`"metric"`	no
`className`	`string`	—	no

Accessibility

The exact displayed distance and unit are readable text; the bar is decorative. The distance groups its digits in the application's locale (React Aria's I18nProvider), breaks only after a digit group and keeps its unit with the last one.
No focus stop or live announcement is introduced for this passive readout.
The bar remains visible in forced colors. The root forwards a div ref/native attributes.

Manifest entry

<MapScale metersPerPixel={frame.metersPerPixel} units="metric" />

View agent manifest

{
  "description": "Bounded 1/2/5 ground-distance scale from a supplied local map resolution.",
  "props": {
    "label": {
      "type": "string",
      "default": "Map scale"
    },
    "metersPerPixel": {
      "type": "number",
      "description": "Positive finite local ground meters per CSS pixel. Missing/null/nonpositive/nonfinite values show Scale unavailable. Adapter owns projection and scale location."
    },
    "maxWidth": {
      "type": "number",
      "default": 120,
      "description": "Positive finite maximum bar width in CSS pixels. Recomputes against narrower measured container width rather than shrinking a mislabeled bar."
    },
    "units": {
      "type": "enum",
      "values": [
        "metric",
        "imperial"
      ],
      "default": "metric",
      "description": "Metric uses m/km; imperial uses ft/mi. Both derive from the same supplied ground resolution."
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "MapControls",
    "MapLegend",
    "AppShell"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<MapScale metersPerPixel={frame.metersPerPixel} units=\"metric\" />"
}