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

    Type Alias CustomImage<I>

    Basic structure to define custom map icons, which end up in the map sprite.

    Allows you to provide custom images for various map icons such as POIs, route waypoints, charging stations, and any other TomTom map icons, replacing the default icons with your own branding or design.

    Icon images can be URLs, raw SVG texts, data URIs or loaded img elements. They will be loaded/transformed if necessary and added 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 or charging stops 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> = {
        availabilityLevel?: AvailabilityLevel;
        id: I;
        image?: string | HTMLImageElement;
        offsetX?: number;
        offsetY?: number;
        pixelRatio?: number;
    }

    Type Parameters

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

    Availability level for POI icons with availability indicators.

    Used when displaying custom icons for POIs with real-time availability data. The SDK will select the appropriate icon based on the availability ratio and configured threshold.

    • 'available': Used when ratio >= threshold (sufficient capacity available)
    • 'occupied': Used when ratio < threshold (low or no availability)
    // Define custom icons for both availability states
    categoryIcons: [
      {
        id: 'CHARGING_LOCATION',
        image: greenChargingSVG,
        availabilityLevel: 'available'
      },
      {
        id: 'CHARGING_LOCATION',
        image: redChargingSVG,
        availabilityLevel: 'occupied'
      }
    ]
    id: I

    Unique identifier for the icon in the map sprite.

    This ID is used to reference the icon when styling map features. The specific values depend on the context:

    • For POI categories: Use MapStylePOICategory values (e.g., 'RESTAURANT', 'HOTEL_OR_MOTEL')
    • For icons an icon.mapping picks by id (route waypoints, charging stops): any unique string, the one the mapping returns
    image?: string | HTMLImageElement

    URL or data URI of the icon image.

    This property is optional. If omitted, the icon with the corresponding id must already exist in the map's sprite. Use this property when you need to add a new icon to the sprite, or provide undefined when referencing an existing sprite icon.

    // 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, negative values shift it left. The offset is applied before icon-size scaling, matching the MapLibre icon-offset convention.

    Only takes effect when image is also provided — an icon referencing 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, negative values shift it up. The offset is applied before icon-size scaling, matching the MapLibre icon-offset convention.

    Only takes effect when image is also provided — an icon referencing 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.

    This property is optional and only relevant when image is provided. If omitted while providing an image, it defaults to 2. When the icon already exists in the sprite (no image), this property is ignored.

    Use 2 for high-DPI (Retina) displays, 1 for standard displays. Higher values result in 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