Icons

Using Mappedin SDK for Android with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

Mappedin SDK for Android provides access to Mappedin's icon library through the Icons class. Icons are Content Delivery Network (CDN) backed Scalable Vector Graphics (SVG) assets served from a global CDN with North America and Europe regions, and can be looked up by name, type, subtype, category, or tags.

tip

A complete example demonstrating Icons can be found in the Mappedin Android GitHub repo: IconsDemoActivity.kt

tip

Note that the MapView class instantiates the Icons class and exposes it as MapView.icons. The Icons API is map-independent: it registers automatically as soon as the bridge is ready and does not require a map to be loaded.

Initialization

The Icons extension is initialized automatically with the North America CDN. To serve icons from a different region, call Icons.initialize() with an IconCdnRegion. The default region is IconCdnRegion.NA and the European CDN is IconCdnRegion.EU.

// Re-initialize with the European CDN
mapView.icons.initialize(IconCdnRegion.EU) {
  // Ready to look up and fetch icons from the EU region.
}

Icon Types

Icons are organized into a hierarchy of types, subtypes, and categories. Each icon has an IconType that classifies it by its primary usage context.

Type	Description
IconType.CATEGORIES	Icons for map locations and amenities. Further classified by IconSubtype.
IconType.SMALL	Compact icons designed for Labels on maps.
IconType.INPUT	Icons for UI input elements.
IconType.METADATA	Fallback and miscellaneous icons.

Subtypes

Icons with IconType.CATEGORIES are further classified by IconSubtype:

Subtype	Description
IconSubtype.LOCATIONS	Location category icons organized by business type (e.g., Food, Fashion, Entertainment).
IconSubtype.AMENITIES	Amenity icons (e.g., Washrooms, Accessibility).
IconSubtype.GENERAL	General purpose category icons.
IconSubtype.SYSTEM	System icons (e.g., Elevator, Escalator, Stairs).

Categories

Location icons within IconSubtype.LOCATIONS can be further filtered by IconCategory, which represents business domains such as FOOD_AND_DRINK, FASHION, ENTERTAINMENT, HOSPITAL, TRANSPORTATION, and many more.

Icon Gallery

The Icons API can be used to build a gallery of all available icons, organized by type. The following code sample fetches all icons of a given type and renders each one's SVG. A complete gallery example is available in IconGalleryFragment.kt.

mapView.icons.getByType(IconType.CATEGORIES) { result ->
  result.onSuccess { icons ->
    for (icon in icons) {
      mapView.icons.fetchSvg(icon.name) { svgResult ->
        svgResult.onSuccess { svg ->
          // Render the SVG, for example in a WebView cell.
        }
      }
    }
  }
}

Looking Up Icons

The Icons class provides several methods for finding icons. Each method delivers one or more MappedinIcon objects through a callback. A MappedinIcon contains the icon's name, url, type, tags, and other metadata.

// Look up a single icon by its unique name
mapView.icons.getByName("information") { result ->
  result.onSuccess { icon ->
    Log.d("Icons", icon.url)  // Full CDN URL to the SVG file
    Log.d("Icons", icon.tags.toString())
  }
}

// Filter by type
mapView.icons.getByType(IconType.CATEGORIES) { result -> /* ... */ }

// Filter by subtype
mapView.icons.getBySubtype(IconSubtype.AMENITIES) { result -> /* ... */ }

// Filter by business category
mapView.icons.getByCategory(IconCategory.FOOD_AND_DRINK) { result -> /* ... */ }

// Search by tags (case-insensitive)
mapView.icons.getByTags(listOf("Washroom", "Restroom")) { result -> /* ... */ }

// Get all icons
mapView.icons.getAll { result -> /* ... */ }

Method	Description
getByName()	Returns a single MappedinIcon by its unique name.
getByType()	Returns all icons matching an IconType.
getBySubtype()	Returns all icons matching an IconSubtype.
getByCategory()	Returns all icons matching an IconCategory.
getByTags()	Returns all icons matching any of the provided tags. Case-insensitive.
getAll()	Returns every icon in the library.
getSmallIcon()	Returns the compact variant of an icon, if one exists.

Fetching and Displaying Icons

The fetchSvg() method retrieves the raw SVG markup for an icon from the CDN (or from the in-memory cache if it has been pre-fetched). The returned string can be rendered in any view that displays SVG content, such as a WebView.

mapView.icons.fetchSvg("information") { result ->
  result.onSuccess { svg ->
    // svg is the raw SVG markup. Render it, for example inside a WebView.
  }
}

Styling Icons with currentColor

Mappedin icon SVGs use fill="currentColor". When rendering an icon in a WebView, the icon inherits the CSS color of its container, so the fill color can be set without modifying the SVG. Alternatively, the currentColor token can be replaced directly in the SVG string before rendering.

mapView.icons.fetchSvg("information") { result ->
  result.onSuccess { svg ->
    val coloredSvg = svg.replace("currentColor", "#ff5733")
    // Render coloredSvg.
  }
}

tip

A complete example demonstrating recoloring icons in real time with a color picker can be found in the Mappedin Android GitHub repo: ColorPickerFragment.kt

Pre-fetching Icons

For applications that need icons available instantly without waiting for network requests, the Icons class provides several pre-fetching methods. Pre-fetched SVGs are stored in an in-memory cache and returned immediately by subsequent fetchSvg() calls.

// Pre-fetch specific icons by name
mapView.icons.prefetch(listOf("information", "elevator-up", "book")) {
  // Check whether an icon is already cached
  mapView.icons.isCached("information") { result ->
    val cached = result.getOrNull() ?: false
    Log.d("Icons", "isCached = $cached")
  }
}

// Pre-fetch all icons of a given type
mapView.icons.prefetchByType(IconType.SMALL) { /* ... */ }

// Pre-fetch all icons of a given subtype
mapView.icons.prefetchBySubtype(IconSubtype.AMENITIES) { /* ... */ }

// Pre-fetch all icons in a business category
mapView.icons.prefetchByCategory(IconCategory.FOOD_AND_DRINK) { /* ... */ }

Method	Description
prefetch()	Pre-fetches a list of icons by name.
prefetchByType()	Pre-fetches all icons of a given IconType.
prefetchBySubtype()	Pre-fetches all icons of a given IconSubtype.
prefetchByCategory()	Pre-fetches all icons in a given IconCategory.
isCached()	Returns true if the icon's SVG is already in the cache.
clearCache()	Clears all cached SVG content.

tip

A complete example demonstrating pre-fetching by name, type, subtype, and category, along with a comparison of cached versus uncached fetch performance, can be found in the Mappedin Android GitHub repo: PrefetchDemoFragment.kt

Using Icons of Mappedin CMS Categories

The category icons configured in the Mappedin Content Management System (CMS) are included in the icon library. The EnterpriseCategory.iconFromDefaultList property provides the icon name that maps directly to an icon in the library.

When displaying icons on Labels, the compact Small icon variant works best. The getSmallIcon() method or the MappedinIcon.smallIcon property returns the name of the small variant for a given icon. Because the SVGs use fill="currentColor", the fill color can be replaced in the SVG string before passing it to the Label's icon appearance.

The following code sample looks up the small icon for an enterprise location's first category, recolors it, and adds a label for each space of that location.

val category = location.categories.firstOrNull()?.let { categoriesById[it] }
val iconName = category?.iconFromDefaultList ?: "information"
val color = category?.color ?: "black"

mapView.icons.getByName(iconName) { iconResult ->
  val smallIconName = iconResult.getOrNull()?.smallIcon ?: "small-information-desk"
  mapView.icons.fetchSvg(smallIconName) { svgResult ->
    val svg = svgResult.getOrNull() ?: return@fetchSvg
    val coloredSvg = svg.replace("currentColor", "#fafafa")
    val appearance = LabelAppearance(color = color, icon = coloredSvg, iconPadding = 10)
    val labelOptions = AddLabelOptions(labelAppearance = appearance)

    for (spaceId in location.spaces) {
      val space = spacesById[spaceId] ?: continue
      mapView.labels.add(target = space, text = location.name, options = labelOptions)
    }
  }
}

tip

A complete example that loads the Mappedin Demo Enterprise map and labels each enterprise location with its category icon can be found in the Mappedin Android GitHub repo: EnterpriseCategoryIconsFragment.kt