Geo Map.

PRO

Show geographic locations and magnitudes on a map.

Live preview44 feature examples

LIVE EXAMPLE

Asian hubs

Match the page theme
Interact with the chart to see selection and range-change results here.
OptionsChanges are reflected in the preview and code.
Appearance and style8
Legend and interaction13
Title and dimensions3

Show cities and their magnitudes using longitude and latitude. All values are sample data.

View code
Current preview
<div id="chart-container" style="width: 100%; min-width: 0;"></div>

<script type="module">
  import { defineCustomElement as define0 } from '@syidax/advanced-pro/components/sy-geo-map.js';
  define0();

  // Pro: complete registerLicense at app startup using your issued certificate.
  // The website preview certificate is not for use in customer apps.
  const specs = [
    {
      "id": "example-chart",
      "tag": "sy-geo-map",
      "props": {
        "data": [
          {
            "id": "seoul",
            "label": "Seoul",
            "longitude": 126.98,
            "latitude": 37.57,
            "value": 80
          },
          {
            "id": "tokyo",
            "label": "Tokyo",
            "longitude": 139.69,
            "latitude": 35.68,
            "value": 65
          },
          {
            "id": "taipei",
            "label": "Taipei",
            "longitude": 121.56,
            "latitude": 25.03,
            "value": 45
          },
          {
            "id": "singapore",
            "label": "Singapore",
            "longitude": 103.82,
            "latitude": 1.35,
            "value": 55
          }
        ],
        "mapRegion": "asia",
        "mapBackground": "natural-earth",
        "projection": "mercator",
        "nodeLabels": "show",
        "width": 640,
        "height": 360,
        "brandPosition": "bottom-right",
        "brandLogo": ""
      }
    }
  ];
  const container = document.querySelector('#chart-container');
  const elements = specs.map(({ tag, id, props }) => {
    const element = document.createElement(tag);
    element.id = id;
    Object.assign(element, props);
    element.setAttribute('aria-label', 'geo-map example chart');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const onEvent = event => {
    console.log('nodeClick', event.detail);
  };
  chart.addEventListener('nodeClick', onEvent);
  const observer = new ResizeObserver(([entry]) => {
    const width = Math.max(160, Math.floor(entry.contentRect.width));
    elements.forEach(element => { element.width = width; });
  });
  observer.observe(container);

  // In an SPA, call this function when the view is disposed.
  function disposeChart() {
    observer.disconnect();
    chart.removeEventListener('nodeClick', onEvent);
    container.replaceChildren();
  }
</script>

Usage and data

#

Explore the distribution of cities, facilities, or observation sites.

Check the longitude and latitude order. Projection affects the representation of distances and areas.

Data contract

PropertyInput format
dataAn array of { longitude, latitude, value?, label? }.
projectionHow geographic coordinates project onto the screen.
mapRegionThe region shown initially.

Updating data

Assign a new array or object to the property instead of mutating values inside an array. Chart events provide selection results through event.detail. When disposing of the view, clean up ResizeObserver and event listeners registered by your app.

Feature examples

#

Try 44 interactive feature examples and inspect their code. Select “Edit in preview” to combine more options in the settings panel above.

Globe projectionPRO

Inspect the same hubs on a globe projection.

Interact with the chart to see results here.
View code

Hub labelsPRO

Adjust marker size and labels together.

Interact with the chart to see results here.
View code

Inspect values with the pointerPRO

Point to data to view the value at that location.

Interact with the chart to see results here.
View code

Crosshair trackingPRO

Move the pointer to read horizontal and vertical coordinates alongside values.

Interact with the chart to see results here.
View code

Drag to zoom and panPRO

Drag to zoom and hold Shift to pan. Use Ctrl + wheel to zoom in or out.

Interact with the chart to see results here.
View code

Replay animationPRO

Redraw the same example to inspect its initial display animation.

Interact with the chart to see results here.
View code

AccessibilityPRO

Compare 4 examples of Accessibility. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

AlbersPRO

Compare 6 examples of Albers. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

AnimationPRO

Compare 11 examples of Animation. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

BubblesPRO

Compare 6 examples of Bubbles. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

ChoroplethPRO

Compare 6 examples of Choropleth. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

ColorPRO

Compare 2 examples of Color. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

ConnectionsPRO

Compare 9 examples of Connections. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

CoordinatesPRO

Compare 2 examples of Coordinates. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

CrosshairPRO

Compare 7 examples of Crosshair. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Data inputPRO

Compare 5 examples of Data input. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Engine ComparePRO

Compare 2 examples of Engine Compare. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

EquirectangularPRO

Compare 5 examples of Equirectangular. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

HeatPRO

Compare 6 examples of Heat. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

LabelPRO

Compare 12 examples of Label. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

LayoutPRO

Compare 4 examples of Layout. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

LegendPRO

Compare 5 examples of Legend. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Map ViewPRO

Compare 3 examples of Map View. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

OrthographicPRO

Compare 7 examples of Orthographic. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Large datasetsPRO

Compare 6 examples of Large datasets. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Highlight statePRO

Compare 6 examples of Highlight state. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

PolygonsPRO

Compare 8 examples of Polygons. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Map projectionPRO

Compare 4 examples of Map projection. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

SizePRO

Compare 1 examples of Size. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

TooltipPRO

Compare 19 examples of Tooltip. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Zoom and panPRO

Compare 7 examples of Zoom and pan. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Context menuPRO

Compare 1 examples of Context menu. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

FeaturesPRO

Compare 4 examples of Features. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

HoverPRO

Compare 2 examples of Hover. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Point ClickPRO

Compare 1 examples of Point Click. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Data context menuPRO

Compare 1 examples of Data context menu. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

ExportPRO

Compare 4 examples of Export. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Read coordinates and dataPRO

Compare 1 examples of Read coordinates and data. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

ImportPRO

Compare 5 examples of Import. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Map ViewPRO

Compare 7 examples of Map View. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Runtime APIPRO

Compare 2 examples of Runtime API. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

OptionalPRO

Compare 2 examples of Optional. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

OverviewPRO

Compare 2 examples of Overview. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

Streaming · Add and update live dataPRO

Compare 9 examples of Add and update live data. Buttons and options update both the live result and source code.

Interact with the chart to see results here.
View code

API reference

#

The full public API for sy-geo-map. Pass objects and arrays as JavaScript properties. Select a name to view usage code and type definitions.

Key properties

Attribute / PropertyType / DefaultDescription
GeoMapDataDefault: undefinedAn array of { longitude, latitude, value?, label? }.
polygonOpacitynumberDefault: 0.7Set as an HTML attribute or JavaScript property. type: number.
mapLegendbooleanDefault: falseNative buttons for point, polygon, connection and heat visibility.
numberDefault: 900Chart width in pixels. Update with ResizeObserver when the container changes.
numberDefault: 400Chart height in pixels.
brandLogostringDefault: undefinedThe default is the Syidax logo. With the Pro chart.branding entitlement, use none or a PNG, JPEG, or WebP data URL.
brandPosition'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'Default: 'bottom-right'The corner where the logo is anchored. Applies equally to Community and Pro, on screen and in image exports.
GeoMapProjectionDefault: 'identity'How geographic coordinates project onto the screen.
mapRegionGeoMapRegionDefault: 'world'The region shown initially.
mapFixedbooleanDefault: falseLock geographic dragging: flat maps wrap longitude inside a fixed frame; Albers/Orthographic rotate. Zoom is separate.
CartesianCrosshairInputDefault: undefinedGeographic crosshair. Bare attribute or {} uses defaults; an object prop or JSON attribute overrides options. Omit/remove the attribute to disable.
nodeRadiusnumberDefault: 5Set as an HTML attribute or JavaScript property. type: number.
nodeLabelsGeoMapLabelModeDefault: 'auto'Allowed values: auto, show, hide. Default: 'auto'.
featureLabelsGeoMapLabelModeDefault: 'hide'Optional region and connection names, sharing point-label collision avoidance.
featureLabelValuebooleanDefault: falseSet as an HTML attribute or JavaScript property. type: boolean.
chartTitlestringDefault: undefinedThe title inside the chart. Explain the data's unit and meaning alongside it.
chartSubtitlestringDefault: undefinedThe subtitle inside the chart.
CartesianTooltipInputDefault: undefinedTooltip settings for pointer-driven values, position, and content.
tooltipEnabledbooleanDefault: trueSet as an HTML attribute or JavaScript property. type: boolean.
animatedbooleanDefault: falseWhether to animate initial display and data changes.
animationDurationnumberDefault: 600Animation duration in milliseconds.
animationEasingGeoMapEasingDefault: 'ease-out'Allowed values: linear, ease-out, ease-in, ease-in-out. Default: 'ease-out'.
animationTypeGeoMapAnimationTypeDefault: undefinedAllowed values: initial, update. Default: undefined.
CartesianZoomInputDefault: undefinedSettings for zooming and the visible range.
Other properties 28
Attribute / PropertyType / DefaultDescription
GeoMapFeatureCollectionDefault: undefinedOwned geographic polygons and great-circle LineStrings, below data points.
polygonColorstringDefault: '#0d9488'Set as an HTML attribute or JavaScript property. type: string.
connectionWidthnumberDefault: 2Set as an HTML attribute or JavaScript property. type: number.
connectionColorstringDefault: '#7c3aed'Set as an HTML attribute or JavaScript property. type: string.
connectionOpacitynumberDefault: 0.85Set as an HTML attribute or JavaScript property. type: number.
connectionPathGeoMapConnectionPathDefault: 'great-circle'Surface great-circle arcs (default), or flat-map straight routes. On globes, straight lifts the equirectangular route onto the surface.
mapColorAxisGeoMapColorAxisInputDefault: undefinedChoropleth: feature property to a shared color ramp and numeric legend.
mapBubbleGeoMapBubbleInputDefault: undefinedGeographic bubbles encode point values by area; object options are property-bound.
mapHeatGeoMapHeatInputDefault: undefinedBounded screen-space Gaussian density below connections and points.
mapLayersGeoMapLayersInputDefault: undefinedLayer presentation masks; assign an object property. Hidden sources retain selection and pinned-card identity.
mapLegendLayersReadonlyArray<GeoMapLayer>Default: undefinedOptional ordered legend subset for geographic specializations; source layers stay intact.
mapLayerNamesPartial<Record<GeoMapLayer,string>>Default: undefinedPass as a JavaScript property. type: Partial<Record<GeoMapLayer,string>>.
numberDefault: 16Padding around the coordinate frame in CSS pixels.
mapBackgroundGeoMapBackgroundDefault: 'natural-earth'Bundled public-domain land/coastline data; no runtime map download or API key.
crosshairSnapDistancenumberDefault: 12Point-center capture distance in CSS pixels when crosshair.snap is enabled; direct marker hits also snap.
stringDefault: 'auto'Set as an HTML attribute or JavaScript property. type: string.
activeColorstringDefault: '#f59e0b'Set as an HTML attribute or JavaScript property. type: string.
inactiveOtherPointsbooleanDefault: falseDim other point/feature glyphs around the focused, hovered or selected source identity. Heat stays unchanged.
inactivePointOpacitynumberDefault: .2Set as an HTML attribute or JavaScript property. type: number.
nodeLabelValuebooleanDefault: falseSet as an HTML attribute or JavaScript property. type: boolean.
enableMouseTrackingbooleanDefault: trueSet as an HTML attribute or JavaScript property. type: boolean.
tooltipFormat(detail: GeoMapHitDetail) => stringDefault: undefinedPass as a JavaScript property. type: (detail: GeoMapHitDetail) => string.
featureTooltipFormat(detail:GeoMapFeatureHitDetail)=>stringDefault: undefinedFormats owned polygon/connection metadata; point tooltipFormat remains independent.
streamSourceGeoMapStreamSourceDefault: undefinedA stream source for live data. Check the contract for the specific type.
streamMaxnumberDefault: undefinedThe maximum number of streaming data points to retain.
streamWindownumberDefault: undefinedThe streaming data range to keep visible.
GeoMapEngineModeDefault: 'auto'Renderer selection: auto, standard, or pro. Engine selection is separate from permission to use a Pro chart type.
GeoMapUnavailableBehaviourDefault: 'fallback'Allowed values: fallback, error. Default: 'fallback'.
Events 20
EventsDetail typeDescription
GeoMapRenderResult & { tier: GeoMapEngineTier }Emits rendering results in detail when chart drawing completes.
GeoMapHitDetailCustomEvent.detail type: GeoMapHitDetail. Event names are case-sensitive.
GeoMapHitDetail | nullCustomEvent.detail type: GeoMapHitDetail | null. Event names are case-sensitive.
GeoMapFeatureHitDetailCustomEvent.detail type: GeoMapFeatureHitDetail. Event names are case-sensitive.
GeoMapFeatureHitDetail | nullCustomEvent.detail type: GeoMapFeatureHitDetail | null. Event names are case-sensitive.
GeoMapFeatureSelectionChangeEventDetailCustomEvent.detail type: GeoMapFeatureSelectionChangeEventDetail. Event names are case-sensitive.
GeoMapSelectionChangeEventDetailCustomEvent.detail type: GeoMapSelectionChangeEventDetail. Event names are case-sensitive.
ChartPointContextMenuEventDetail<GeoMapPickDetail>CustomEvent.detail type: ChartPointContextMenuEventDetail<GeoMapPickDetail>. Event names are case-sensitive.
{ count: number; replaced: number }CustomEvent.detail type: { count: number; replaced: number }. Event names are case-sensitive.
{ dropped: number }CustomEvent.detail type: { dropped: number }. Event names are case-sensitive.
CartesianTooltipEventDetailWhether to display the built-in tooltip.
voidCustomEvent.detail type: void. Event names are case-sensitive.
CartesianTooltipActionEventDetailCustomEvent.detail type: CartesianTooltipActionEventDetail. Event names are case-sensitive.
voidCustomEvent.detail type: void. Event names are case-sensitive.
voidCustomEvent.detail type: void. Event names are case-sensitive.
voidCustomEvent.detail type: void. Event names are case-sensitive.
CartesianZoomChangeEventDetailCustomEvent.detail type: CartesianZoomChangeEventDetail. Event names are case-sensitive.
GeoMapViewChangeEventDetailCustomEvent.detail type: GeoMapViewChangeEventDetail. Event names are case-sensitive.
GeoMapLayerChangeEventDetailCustomEvent.detail type: GeoMapLayerChangeEventDetail. Event names are case-sensitive.
CartesianCrosshairEventDetail | nullCustomEvent.detail type: CartesianCrosshairEventDetail | null. Event names are case-sensitive.
Methods 59

Stencil methods return Promises. Use await within an async function to read the result.

Method / ArgumentsReturn typeDescription
Promise<GeoMapLayerDetail[]>An asynchronous method. Check the argument and return types below.
layer: GeoMapLayer, visible: booleanPromise<GeoMapLayerDetail|null>Immediately mask a layer without restarting active animations, rescaling or reframing. Unknown keys return null.
Promise<GeoMapRenderResult>An asynchronous method. Check the argument and return types below.
Promise<void>Release and reacquire the shared GPU surface without resetting data, pins or geographic view. Without the grant (or while frozen) nothing is recycled: no GPU work starts.
Promise<GeoMapConnectionView[]>An asynchronous method. Check the argument and return types below.
Promise<ChartEngineStatus>Requested engine vs what runs, and why (CHART-ADD-08); a frozen or unlicensed chart reports the license outcome.
Promise<GeoMapEngineTier>An asynchronous method. Check the argument and return types below.
Promise<string | undefined>An asynchronous method. Check the argument and return types below.
Promise<GeoMapAvailabilityDetail>Owned current engine status. A Pro decision can be pending before asynchronous device initialization finishes.
data: GeoMapDataPromise<void>An asynchronous method. Check the argument and return types below.
features?: GeoMapFeatureCollectionPromise<void>Validate atomically; invalid input rejects and leaves the previous layer intact.
Promise<GeoMapFeatureCollection>An asynchronous method. Check the argument and return types below.
Promise<GeoMapColorAxisDetail|null>An asynchronous method. Check the argument and return types below.
Promise<GeoMapFeatureSelection>An asynchronous method. Check the argument and return types below.
index: numberPromise<GeoMapFeatureHitDetail | null>An asynchronous method. Check the argument and return types below.
index: numberPromise<CartesianTooltipEventDetail | null>An asynchronous method. Check the argument and return types below.
input: unknown, objectName?: stringPromise<GeoMapFeatureCollection>Decode a Topology (object or JSON text) into owned GeoJSON; does not change chart data.
input: unknownPromise<GeoMapFeatureCollection>Decode RFC 7946 Geometry, Feature or FeatureCollection into owned features without changing chart data.
Promise<GeoMapPoint[]>An asynchronous method. Check the argument and return types below.
index: numberPromise<GeoMapPoint | null>An asynchronous method. Check the argument and return types below.
id: stringPromise<GeoMapPoint | null>An asynchronous method. Check the argument and return types below.
Promise<number>An asynchronous method. Check the argument and return types below.
Promise<GeoMapExtent>An asynchronous method. Check the argument and return types below.
Promise<GeoMapDiagnostics>Current base input and active normalized stream window; not lifetime ingestion counters. Returns an owned snapshot.
Promise<GeoMapLayoutResult>An asynchronous method. Check the argument and return types below.
node: GeoMapPointInputPromise<void>An asynchronous method. Check the argument and return types below.
nodes: ReadonlyArray<GeoMapPointInput>Promise<void>An asynchronous method. Check the argument and return types below.
count: numberPromise<void>An asynchronous method. Check the argument and return types below.
nodes: ReadonlyArray<GeoMapPointInput>Promise<void>An asynchronous method. Check the argument and return types below.
Promise<GeoMapStreamSource | undefined>An asynchronous method. Check the argument and return types below.
Promise<void>An asynchronous method. Check the argument and return types below.
Promise<void>An asynchronous method. Check the argument and return types below.
Promise<void>An asynchronous method. Check the argument and return types below.
options: { enabled?: boolean; duration?: number; easing?: GeoMapEasing; type?: GeoMapAnimationType }Promise<void>An asynchronous method. Check the argument and return types below.
cssX: number, cssY: numberPromise<GeoMapPickDetail | null>An asynchronous method. Check the argument and return types below.
index: numberPromise<GeoMapHitDetail | null>An asynchronous method. Check the argument and return types below.
Promise<void>An asynchronous method. Check the argument and return types below.
Promise<GeoMapSelection>An asynchronous method. Check the argument and return types below.
index: numberPromise<CartesianTooltipEventDetail | null>An asynchronous method. Check the argument and return types below.
index: numberPromise<CartesianTooltipEventDetail | null>An asynchronous method. Check the argument and return types below.
Promise<void>An asynchronous method. Check the argument and return types below.
request: CartesianZoomRequestPromise<CartesianZoomChangeEventDetail | null>Zoom to explicit windows over the unit extents: `x` / `y` as `{ min, max }` or `[min, max]` (`null` clears that orientation).
factor: number, anchorFraction?: numberPromise<CartesianZoomChangeEventDetail | null>Scale the current windows by `factor` (< 1 zooms in) around `anchorFraction` (0..1, default centre).
delta: { x?: number; y?: number }Promise<CartesianZoomChangeEventDetail | null>Slide the zoomed windows by unit-extent units (`{ x?, y? }`); a no-op at the full extent.
Promise<CartesianZoomChangeEventDetail | null>Back to the full diagram.
Promise<void>Restore the configured projection/region and clear map movement and zoom.
Promise<GeoMapViewDetail>Owned geographic camera, effective region and viewport state.
options?: GeoMapFitOptionsPromise<GeoMapFitDetail|null>Fit current point/feature geometry with a uniform scale. Empty candidates leave the view unchanged.
Promise<CartesianZoomState | null>The current zoom state (`null` = the full diagram).
request?: CartesianZoomExtentRequestPromise<CartesianZoomExtentDetail | null>The full extent (0 … 1) and key of the diagram's orientations (`null` before the first layout).
Promise<ChartDataTable>An asynchronous method. Check the argument and return types below.
Promise<GeoMapLabel[]>An asynchronous method. Check the argument and return types below.
Promise<GeoMapLabelView>Full source text and current screen placement for both point and feature names.
Promise<GeoMapHeatDetail|null>An asynchronous method. Check the argument and return types below.
cssX: number, cssY: numberPromise<GeoMapHeatPointDetail|null>Read aggregate density at a host-relative point; original point/feature selection remains separate.
longitude: number, latitude: numberPromise<GeoMapHeatPointDetail|null>Read the current visible density at geography without requiring a source point or marker. Returns null for invalid, projection-clipped, offscreen or rear-hemisphere coordinates and hidden heat.
Promise<GeoMapBubbleScaleDetail|null>An asynchronous method. Check the argument and return types below.
request: {dataX:number;dataY:number}Promise<boolean>Quiet geographic synchronization; invalid, hidden or clipped coordinates leave no guide.
Promise<void>An asynchronous method. Check the argument and return types below.