Geo Map.
PROShow geographic locations and magnitudes on a map.
LIVE EXAMPLE
Asian hubs
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
<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
| Property | Input format |
|---|---|
data | An array of { longitude, latitude, value?, label? }. |
projection | How geographic coordinates project onto the screen. |
mapRegion | The 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.
View code
Hub labelsPRO
Adjust marker size and labels together.
View code
Inspect values with the pointerPRO
Point to data to view the value at that location.
View code
Crosshair trackingPRO
Move the pointer to read horizontal and vertical coordinates alongside values.
View code
Drag to zoom and panPRO
Drag to zoom and hold Shift to pan. Use Ctrl + wheel to zoom in or out.
View code
Replay animationPRO
Redraw the same example to inspect its initial display animation.
View code
AccessibilityPRO
Compare 4 examples of Accessibility. Buttons and options update both the live result and source code.
View code
AlbersPRO
Compare 6 examples of Albers. Buttons and options update both the live result and source code.
View code
AnimationPRO
Compare 11 examples of Animation. Buttons and options update both the live result and source code.
View code
BubblesPRO
Compare 6 examples of Bubbles. Buttons and options update both the live result and source code.
View code
ChoroplethPRO
Compare 6 examples of Choropleth. Buttons and options update both the live result and source code.
View code
ColorPRO
Compare 2 examples of Color. Buttons and options update both the live result and source code.
View code
ConnectionsPRO
Compare 9 examples of Connections. Buttons and options update both the live result and source code.
View code
CoordinatesPRO
Compare 2 examples of Coordinates. Buttons and options update both the live result and source code.
View code
CrosshairPRO
Compare 7 examples of Crosshair. Buttons and options update both the live result and source code.
View code
Data inputPRO
Compare 5 examples of Data input. Buttons and options update both the live result and source code.
View code
Engine ComparePRO
Compare 2 examples of Engine Compare. Buttons and options update both the live result and source code.
View code
EquirectangularPRO
Compare 5 examples of Equirectangular. Buttons and options update both the live result and source code.
View code
HeatPRO
Compare 6 examples of Heat. Buttons and options update both the live result and source code.
View code
LabelPRO
Compare 12 examples of Label. Buttons and options update both the live result and source code.
View code
LayoutPRO
Compare 4 examples of Layout. Buttons and options update both the live result and source code.
View code
LegendPRO
Compare 5 examples of Legend. Buttons and options update both the live result and source code.
View code
Map ViewPRO
Compare 3 examples of Map View. Buttons and options update both the live result and source code.
View code
OrthographicPRO
Compare 7 examples of Orthographic. Buttons and options update both the live result and source code.
View code
Large datasetsPRO
Compare 6 examples of Large datasets. Buttons and options update both the live result and source code.
View code
Highlight statePRO
Compare 6 examples of Highlight state. Buttons and options update both the live result and source code.
View code
PolygonsPRO
Compare 8 examples of Polygons. Buttons and options update both the live result and source code.
View code
Map projectionPRO
Compare 4 examples of Map projection. Buttons and options update both the live result and source code.
View code
SizePRO
Compare 1 examples of Size. Buttons and options update both the live result and source code.
View code
TooltipPRO
Compare 19 examples of Tooltip. Buttons and options update both the live result and source code.
View code
Zoom and panPRO
Compare 7 examples of Zoom and pan. Buttons and options update both the live result and source code.
View code
Context menuPRO
Compare 1 examples of Context menu. Buttons and options update both the live result and source code.
View code
FeaturesPRO
Compare 4 examples of Features. Buttons and options update both the live result and source code.
View code
HoverPRO
Compare 2 examples of Hover. Buttons and options update both the live result and source code.
View code
Point ClickPRO
Compare 1 examples of Point Click. Buttons and options update both the live result and source code.
View code
Data context menuPRO
Compare 1 examples of Data context menu. Buttons and options update both the live result and source code.
View code
ExportPRO
Compare 4 examples of Export. Buttons and options update both the live result and source code.
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.
View code
ImportPRO
Compare 5 examples of Import. Buttons and options update both the live result and source code.
View code
Map ViewPRO
Compare 7 examples of Map View. Buttons and options update both the live result and source code.
View code
Runtime APIPRO
Compare 2 examples of Runtime API. Buttons and options update both the live result and source code.
View code
OptionalPRO
Compare 2 examples of Optional. Buttons and options update both the live result and source code.
View code
OverviewPRO
Compare 2 examples of Overview. Buttons and options update both the live result and source code.
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.
View code
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.
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 / Property | Type / Default | Description |
|---|---|---|
GeoMapDataDefault: undefined | An array of { longitude, latitude, value?, label? }. | |
| polygonOpacity | numberDefault: 0.7 | Set as an HTML attribute or JavaScript property. type: number. |
| mapLegend | booleanDefault: false | Native buttons for point, polygon, connection and heat visibility. |
numberDefault: 900 | Chart width in pixels. Update with ResizeObserver when the container changes. | |
numberDefault: 400 | Chart height in pixels. | |
| brandLogo | stringDefault: undefined | The 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. | |
| mapRegion | GeoMapRegionDefault: 'world' | The region shown initially. |
| mapFixed | booleanDefault: false | Lock geographic dragging: flat maps wrap longitude inside a fixed frame; Albers/Orthographic rotate. Zoom is separate. |
CartesianCrosshairInputDefault: undefined | Geographic crosshair. Bare attribute or {} uses defaults; an object prop or JSON attribute overrides options. Omit/remove the attribute to disable. | |
| nodeRadius | numberDefault: 5 | Set as an HTML attribute or JavaScript property. type: number. |
| nodeLabels | GeoMapLabelModeDefault: 'auto' | Allowed values: auto, show, hide. Default: 'auto'. |
| featureLabels | GeoMapLabelModeDefault: 'hide' | Optional region and connection names, sharing point-label collision avoidance. |
| featureLabelValue | booleanDefault: false | Set as an HTML attribute or JavaScript property. type: boolean. |
| chartTitle | stringDefault: undefined | The title inside the chart. Explain the data's unit and meaning alongside it. |
| chartSubtitle | stringDefault: undefined | The subtitle inside the chart. |
CartesianTooltipInputDefault: undefined | Tooltip settings for pointer-driven values, position, and content. | |
| tooltipEnabled | booleanDefault: true | Set as an HTML attribute or JavaScript property. type: boolean. |
| animated | booleanDefault: false | Whether to animate initial display and data changes. |
| animationDuration | numberDefault: 600 | Animation duration in milliseconds. |
| animationEasing | GeoMapEasingDefault: 'ease-out' | Allowed values: linear, ease-out, ease-in, ease-in-out. Default: 'ease-out'. |
| animationType | GeoMapAnimationTypeDefault: undefined | Allowed values: initial, update. Default: undefined. |
CartesianZoomInputDefault: undefined | Settings for zooming and the visible range. |
Other properties 28
| Attribute / Property | Type / Default | Description |
|---|---|---|
GeoMapFeatureCollectionDefault: undefined | Owned geographic polygons and great-circle LineStrings, below data points. | |
| polygonColor | stringDefault: '#0d9488' | Set as an HTML attribute or JavaScript property. type: string. |
| connectionWidth | numberDefault: 2 | Set as an HTML attribute or JavaScript property. type: number. |
| connectionColor | stringDefault: '#7c3aed' | Set as an HTML attribute or JavaScript property. type: string. |
| connectionOpacity | numberDefault: 0.85 | Set as an HTML attribute or JavaScript property. type: number. |
| connectionPath | GeoMapConnectionPathDefault: 'great-circle' | Surface great-circle arcs (default), or flat-map straight routes. On globes, straight lifts the equirectangular route onto the surface. |
| mapColorAxis | GeoMapColorAxisInputDefault: undefined | Choropleth: feature property to a shared color ramp and numeric legend. |
| mapBubble | GeoMapBubbleInputDefault: undefined | Geographic bubbles encode point values by area; object options are property-bound. |
| mapHeat | GeoMapHeatInputDefault: undefined | Bounded screen-space Gaussian density below connections and points. |
| mapLayers | GeoMapLayersInputDefault: undefined | Layer presentation masks; assign an object property. Hidden sources retain selection and pinned-card identity. |
| mapLegendLayers | ReadonlyArray<GeoMapLayer>Default: undefined | Optional ordered legend subset for geographic specializations; source layers stay intact. |
| mapLayerNames | Partial<Record<GeoMapLayer,string>>Default: undefined | Pass as a JavaScript property. type: Partial<Record<GeoMapLayer,string>>. |
numberDefault: 16 | Padding around the coordinate frame in CSS pixels. | |
| mapBackground | GeoMapBackgroundDefault: 'natural-earth' | Bundled public-domain land/coastline data; no runtime map download or API key. |
| crosshairSnapDistance | numberDefault: 12 | Point-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. | |
| activeColor | stringDefault: '#f59e0b' | Set as an HTML attribute or JavaScript property. type: string. |
| inactiveOtherPoints | booleanDefault: false | Dim other point/feature glyphs around the focused, hovered or selected source identity. Heat stays unchanged. |
| inactivePointOpacity | numberDefault: .2 | Set as an HTML attribute or JavaScript property. type: number. |
| nodeLabelValue | booleanDefault: false | Set as an HTML attribute or JavaScript property. type: boolean. |
| enableMouseTracking | booleanDefault: true | Set as an HTML attribute or JavaScript property. type: boolean. |
| tooltipFormat | (detail: GeoMapHitDetail) => stringDefault: undefined | Pass as a JavaScript property. type: (detail: GeoMapHitDetail) => string. |
| featureTooltipFormat | (detail:GeoMapFeatureHitDetail)=>stringDefault: undefined | Formats owned polygon/connection metadata; point tooltipFormat remains independent. |
| streamSource | GeoMapStreamSourceDefault: undefined | A stream source for live data. Check the contract for the specific type. |
| streamMax | numberDefault: undefined | The maximum number of streaming data points to retain. |
| streamWindow | numberDefault: undefined | The 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
| Events | Detail type | Description |
|---|---|---|
GeoMapRenderResult & { tier: GeoMapEngineTier } | Emits rendering results in detail when chart drawing completes. | |
GeoMapHitDetail | CustomEvent.detail type: GeoMapHitDetail. Event names are case-sensitive. | |
GeoMapHitDetail | null | CustomEvent.detail type: GeoMapHitDetail | null. Event names are case-sensitive. | |
GeoMapFeatureHitDetail | CustomEvent.detail type: GeoMapFeatureHitDetail. Event names are case-sensitive. | |
GeoMapFeatureHitDetail | null | CustomEvent.detail type: GeoMapFeatureHitDetail | null. Event names are case-sensitive. | |
GeoMapFeatureSelectionChangeEventDetail | CustomEvent.detail type: GeoMapFeatureSelectionChangeEventDetail. Event names are case-sensitive. | |
GeoMapSelectionChangeEventDetail | CustomEvent.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. | |
CartesianTooltipEventDetail | Whether to display the built-in tooltip. | |
void | CustomEvent.detail type: void. Event names are case-sensitive. | |
CartesianTooltipActionEventDetail | CustomEvent.detail type: CartesianTooltipActionEventDetail. Event names are case-sensitive. | |
void | CustomEvent.detail type: void. Event names are case-sensitive. | |
void | CustomEvent.detail type: void. Event names are case-sensitive. | |
void | CustomEvent.detail type: void. Event names are case-sensitive. | |
CartesianZoomChangeEventDetail | CustomEvent.detail type: CartesianZoomChangeEventDetail. Event names are case-sensitive. | |
GeoMapViewChangeEventDetail | CustomEvent.detail type: GeoMapViewChangeEventDetail. Event names are case-sensitive. | |
GeoMapLayerChangeEventDetail | CustomEvent.detail type: GeoMapLayerChangeEventDetail. Event names are case-sensitive. | |
CartesianCrosshairEventDetail | null | CustomEvent.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 / Arguments | Return type | Description |
|---|---|---|
Promise<GeoMapLayerDetail[]> | An asynchronous method. Check the argument and return types below. | |
| layer: GeoMapLayer, visible: boolean | Promise<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: GeoMapData | Promise<void> | An asynchronous method. Check the argument and return types below. |
| features?: GeoMapFeatureCollection | Promise<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: number | Promise<GeoMapFeatureHitDetail | null> | An asynchronous method. Check the argument and return types below. |
| index: number | Promise<CartesianTooltipEventDetail | null> | An asynchronous method. Check the argument and return types below. |
| input: unknown, objectName?: string | Promise<GeoMapFeatureCollection> | Decode a Topology (object or JSON text) into owned GeoJSON; does not change chart data. |
| input: unknown | Promise<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: number | Promise<GeoMapPoint | null> | An asynchronous method. Check the argument and return types below. |
| id: string | Promise<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: GeoMapPointInput | Promise<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: number | Promise<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: number | Promise<GeoMapPickDetail | null> | An asynchronous method. Check the argument and return types below. |
| index: number | Promise<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: number | Promise<CartesianTooltipEventDetail | null> | An asynchronous method. Check the argument and return types below. |
| index: number | Promise<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: CartesianZoomRequest | Promise<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?: number | Promise<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?: GeoMapFitOptions | Promise<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?: CartesianZoomExtentRequest | Promise<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: number | Promise<GeoMapHeatPointDetail|null> | Read aggregate density at a host-relative point; original point/feature selection remains separate. |
| longitude: number, latitude: number | Promise<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. |
No matching APIs.