API reference#

Exports of @sigx/lynx-maps v0.4.9 — two components, their prop types, the geometry and event types, and the low-level JSX intrinsics.

The public surface is two components plus a set of type-only exports:

import { Map, MapMarker } from '@sigx/lynx-maps';
import type {
  MapProps,
  MapMarkerProps,
  MapRegion,
  MapCoordinate,
  MapType,
  MapRegionChangeEvent,
  MapRegionChangeEventDetail,
  MapPressEvent,
  MapPressEventDetail,
  MapMarkerPressEvent,
  MapMarkerPressEventDetail,
  SigxMapAttributes,
  SigxMapMarkerAttributes,
} from '@sigx/lynx-maps';

Every export below works on both iOS and Android.

Components#

Map#

Native map view component. Renders MKMapView on iOS (Apple Maps, no key) and com.google.android.gms.maps.MapView on Android (Google Maps, API key required). Accepts any number of MapMarker children as pins.

export const Map: (props: MapProps) => /* sigx-lynx component */

• props — MapProps. All props are optional.
• Returns — a sigx-lynx component that maps to the intrinsic <sigx-map> element.

Platform notes: serializes region to a JSON string; passes showsUserLocation → shows-user-location and mapType → map-type; and wires onRegionChange / onPress / onMarkerPress to the native bindregionchange / bindpress / bindmarkerpress bindings. The map snaps to region on every prop change — for initial-region-only semantics, pass it once and hold it in stable local state. The imperative methods animateToRegion and fitToCoordinates are not implemented in v1.

MapMarker#

Marker pin rendered inside a Map.

export const MapMarker: (props: MapMarkerProps) => /* sigx-lynx component */

• props — MapMarkerProps. coordinate is required; the rest are optional.
• Returns — a sigx-lynx component that maps to the intrinsic <sigx-map-marker> element.

Platform notes: JSON-stringifies coordinate, passes title / description through, and forwards id → marker-id (surfaced as event.detail.id on the parent map's onMarkerPress). v1 markers are minimal — platform default pin only: no custom icons, no draggable pins, no custom callout views. Set id to disambiguate when multiple markers share a coordinate.

Prop types#

MapProps#

Props for Map. All props are optional (each Define.Prop's third type argument is false).

export type MapProps =
    & Define.Prop<'region', MapRegion, false>
    & Define.Prop<'showsUserLocation', boolean, false>
    & Define.Prop<'mapType', MapType, false>
    & Define.Prop<'class', string, false>
    & Define.Prop<'style', string | Record<string, string | number>, false>
    & Define.Prop<'onRegionChange', (e: MapRegionChangeEvent) => void, false>
    & Define.Prop<'onPress', (e: MapPressEvent) => void, false>
    & Define.Prop<'onMarkerPress', (e: MapMarkerPressEvent) => void, false>
    & Define.Prop<'children', unknown, false>;

• region — a MapRegion object (not the JSON string; the component stringifies it). Re-applied on every change.
• showsUserLocation — show the user-location dot. Requires location permission at runtime.
• mapType — base map style, a MapType. Defaults to 'standard'.
• class — CSS class string.
• style — a CSS string or a style object (Record<string, string | number>).
• onRegionChange — handler receiving a MapRegionChangeEvent.
• onPress — handler receiving a MapPressEvent.
• onMarkerPress — handler receiving a MapMarkerPressEvent.
• children — the MapMarker pins.

Platform note: event handlers receive typed event objects whose payload is on .detail.

MapMarkerProps#

Props for MapMarker. Only coordinate is required (its Define.Prop third argument is true).

export type MapMarkerProps =
    & Define.Prop<'coordinate', MapCoordinate, true>
    & Define.Prop<'title', string, false>
    & Define.Prop<'description', string, false>
    & Define.Prop<'id', string, false>;

• coordinate — required MapCoordinate, the pin's location.
• title — optional. Populates the callout shown when the marker is tapped.
• description — optional. Secondary callout text.
• id — optional. Surfaced as event.detail.id on the parent map's onMarkerPress; empty string when not set.

Geometry types#

MapRegion#

Rectangular visible region. Matches the react-native-maps Region shape.

export interface MapRegion {
    latitude: number;
    longitude: number;
    latitudeDelta: number;
    longitudeDelta: number;
}

• latitude / longitude — the center point of the viewport.
• latitudeDelta / longitudeDelta — the span in degrees visible above/below and left/right of the center.

MapCoordinate#

A single geographic point. Used by MapMarker's coordinate and inside press / marker-press event details.

export interface MapCoordinate {
    latitude: number;
    longitude: number;
}

• latitude / longitude — the point's coordinates.

MapType#

Base map style.

export type MapType = 'standard' | 'satellite' | 'hybrid';

• The default is 'standard'.

Event types#

MapRegionChangeEvent#

Event passed to onRegionChange. Fires after the user pans/zooms, or after a programmatic region change.

export interface MapRegionChangeEvent {
    type: 'regionchange';
    detail: MapRegionChangeEventDetail;
}

• type — always 'regionchange'.
• detail — a MapRegionChangeEventDetail.

MapRegionChangeEventDetail#

Detail payload for region-change events: the new visible region.

export interface MapRegionChangeEventDetail {
    region: MapRegion;
    [k: string]: unknown;
}

• region — the new visible MapRegion.
• [k: string] — open index signature for forward-compat extra fields.

MapPressEvent#

Event passed to onPress. Fires when the user taps the map (not on a marker).

export interface MapPressEvent {
    type: 'press';
    detail: MapPressEventDetail;
}

• type — always 'press'.
• detail — a MapPressEventDetail.

MapPressEventDetail#

Detail payload for map-press events: the tapped coordinate.

export interface MapPressEventDetail {
    coordinate: MapCoordinate;
    [k: string]: unknown;
}

• coordinate — the tapped MapCoordinate.
• [k: string] — open index signature for extra fields.

MapMarkerPressEvent#

Event passed to onMarkerPress. Fires when the user taps a marker.

export interface MapMarkerPressEvent {
    type: 'markerpress';
    detail: MapMarkerPressEventDetail;
}

• type — always 'markerpress'.
• detail — a MapMarkerPressEventDetail.

MapMarkerPressEventDetail#

Detail payload for marker-press events: the pressed marker's id and its coordinate.

export interface MapMarkerPressEventDetail {
    /** Marker's `marker-id` prop, or empty string if none was set. */
    id: string;
    coordinate: MapCoordinate;
    [k: string]: unknown;
}

• id — the marker's id prop, or the empty string if none was set.
• coordinate — the pressed marker's MapCoordinate.
• [k: string] — open index signature for extra fields.

Low-level JSX intrinsics#

Importing @sigx/lynx-maps (which side-effect-imports its jsx-augment module) registers two intrinsic tags globally, so you do not need to import the augmentation yourself:

declare global {
    namespace JSX {
        interface IntrinsicElements {
            'sigx-map': SigxMapAttributes;
            'sigx-map-marker': SigxMapMarkerAttributes;
        }
    }
}

These are the native-facing tags the Map and MapMarker components render to. Most code should use the components; the intrinsics and their attribute types are documented for completeness. Element availability at runtime requires sigx prebuild to have run after adding the dependency (the autolinker emits the iOS LynxConfig registration and Android Behavior attachment that bind the tags to native UI classes).

SigxMapAttributes#

JSX intrinsic attributes for the <sigx-map> element. Extends LynxCommonAttributes (shared Lynx element attrs like class, style).

export interface SigxMapAttributes extends LynxCommonAttributes {
    region?: string;
    'shows-user-location'?: boolean;
    'map-type'?: MapType;
    bindregionchange?: LynxEventHandler<MapRegionChangeEvent>;
    bindpress?: LynxEventHandler<MapPressEvent>;
    bindmarkerpress?: LynxEventHandler<MapMarkerPressEvent>;
    children?: unknown;
}

• region — the JSON-stringified MapRegion. Object props are not supported on the Lynx wire, so JSON-on-the-wire is the sigx-lynx idiom.
• shows-user-location — requires location permission.
• map-type — a MapType.
• bindregionchange / bindpress / bindmarkerpress — native event bindings, typed as LynxEventHandler<TEvent>.
• children — the marker children.

SigxMapMarkerAttributes#

JSX intrinsic attributes for the <sigx-map-marker> element. Extends LynxCommonAttributes.

export interface SigxMapMarkerAttributes extends LynxCommonAttributes {
    coordinate: string;
    title?: string;
    description?: string;
    'marker-id'?: string;
}

• coordinate — required JSON-stringified {latitude, longitude}.
• title / description — callout text.
• marker-id — surfaced as event.detail.id in bindmarkerpress.

Supporting types#

These types come from other packages and shape the surface above; they are not exported by @sigx/lynx-maps.

• Define.Prop (from @sigx/lynx) — component props are declared via an intersection of Define.Prop<'name', Type, Required> entries. The third type argument is a boolean: true = required, false = optional. Used by MapProps and MapMarkerProps.
• LynxCommonAttributes (from @sigx/lynx-runtime) — shared Lynx element attributes (such as class / style) extended by SigxMapAttributes and SigxMapMarkerAttributes.
• LynxEventHandler<TEvent> (from @sigx/lynx-runtime) — the type of the native bind* event bindings.