TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.0. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Type Alias CustomImage<I>

    A custom map icon, added to the map sprite.

    Use it to replace any default TomTom map icon, such as POIs, route waypoints or charging stations, with your own branding or design.

    An icon image can be a URL, raw SVG text, a data URI or a loaded img element. The SDK loads or transforms it if needed and adds it to the map style sprite for rendering.

    // POI category icon
    const poiIcon: CustomImage = {
      id: 'RESTAURANT',
      image: '/icons/restaurant-marker.png',
    };

    // An icon a route's waypoints pick by id through their `icon.mapping`
    const chargingIcon: CustomImage = {
      id: 'my-charging-station',
      image: '/icons/ev-charger-low-res.png',
      pixelRatio: 1
    };

    https://maplibre.org/maplibre-style-spec/sprite/

    type CustomImage<I extends string = string> = {
        id: I;
        image?: string | HTMLImageElement;
        offsetX?: number;
        offsetY?: number;
        pixelRatio?: number;
    }

    Type Parameters

    • I extends string = string
    Index
    id image? offsetX? offsetY? pixelRatio?
    id: I

    The icon's unique id in the map sprite.

    Map feature styling references the icon by this id. Its values depend on the context:

    • For POI categories, a MapStylePOICategory value, such as 'RESTAURANT' or 'HOTEL_OR_MOTEL'.
    • For icons an icon.mapping picks by id (route waypoints), any unique string the mapping returns.
    image?: string | HTMLImageElement

    The URL or data URI of the icon image.

    To add a new icon to the sprite, set it. To reference an existing sprite icon, leave it out or set it to undefined. The icon with the same id must then already exist in the sprite.

    // Adding a new icon to the sprite
    image: 'https://example.com/marker.png'

    // Using a data URI
    image: 'data:image/png;base64,iVBORw0KG...'

    // Using a relative path
    image: '/assets/icons/marker.png'

    // Referencing an existing sprite icon (no URL needed)
    // image is omitted when the icon already exists in the sprite
    offsetX?: number

    Horizontal offset of the icon from its anchor point, in pixels.

    Positive values shift the icon right and negative values shift it left. The offset applies before icon-size scaling, following the MapLibre icon-offset convention.

    It takes effect only when you also provide image. An icon that references an existing sprite icon by id alone ignores offsetX/offsetY.

    0

    // Shift the icon 10px to the right of its coordinate
    offsetX: 10
    offsetY?: number

    Vertical offset of the icon from its anchor point, in pixels.

    Positive values shift the icon down and negative values shift it up. The offset applies before icon-size scaling, following the MapLibre icon-offset convention.

    It takes effect only when you also provide image. An icon that references an existing sprite icon by id alone ignores offsetX/offsetY.

    0

    // Shift the icon 10px above its coordinate
    offsetY: -10
    pixelRatio?: number

    The pixel ratio of the icon image.

    It applies only when you provide image. If you leave it out with an image, it defaults to 2. For an icon that already exists in the sprite (no image), it is ignored.

    Use 2 for high-DPI (Retina) displays and 1 for standard displays. Higher values give sharper icons on high-resolution screens.

    2 (recommended for modern screens)

    // For @2x resolution images
    pixelRatio: 2

    // For standard resolution images
    pixelRatio: 1

    Settings
    Member Visibility

    On This Page
    Properties