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.

Add to your interface

#

The code tabs below the preview contain the full data, options, event bindings, and responsive sizing for the current example. Copy them into an app project, such as Vite, that can resolve the installed packages.

Shared sy-chart API versus direct tags

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.