Icons

Point layers can be drawn as icons instead of plain circles. Set iconImage in the paint block to a built-in icon slug (or an emoji), and the icon takes on the layer's color and size.

Icons work in simple, categorical, and numeric point visualizations. In categorical and numeric styles, iconImage (and the other paint properties) may be an array so each category or class gets its own marker.

Icon paint properties

Property	Type	Description
iconImage	string | string[]	An icon slug from the catalog below, or an emoji in the form "emoji::name:".
iconFrame	string	"none", "frame-circle", or "frame-square". Built-in icons only (not emojis).
iconRotation	number | string	Rotation in degrees, or the name of a column to rotate by.
iconHideOnZoom	number	Zoom level below which icons are drawn as plain points instead. Optional.

When iconImage is set, color fills the icon and size scales it (the same size you would use for a circle radius).

Examples

A single icon marker, framed in a circle:

{
  "version": "2.3.1",
  "type": "simple",
  "paint": {
    "iconImage": "hospital",
    "iconFrame": "frame-circle",
    "color": "#E74C3C",
    "size": 4,
    "opacity": 0.9,
    "isClickable": true
  },
  "legend": {}
}

To give each category its own icon, make iconImage an array — see the icon-per-category example in Categorical visualizations.

Available icons

Use only the icon slugs listed here. Invented names will not render.

• Shapes: dot, square, diamond, triangle, x, plus, circle-line, circle-slash, circle-triangle, circle-x, circle-plus, star, heart, hexagon, octagon

• Arrows & directions: arrow-up, chevron-up, double-chevron-up, direction-up (combine with iconRotation to point them anywhere)

• Transportation: pedestrian, bicycle, wheelchair, airport, car, bus, train, truck, ferry, sailboat, electric-service, gas-service, blood-clinic, badge, traffic-light, traffic-cone, road-sign-caution

• Activities & places: person, restroom, house, work, letter, hotel, factory, hospital, religious-facility, school, government, university, bank, landmark, museum, clothing, shopping, store, bar, pub, cafe, food, park, amusement-park, camping-tent, cabin, picnic, water-refill, trailhead, guidepost, viewpoint, camera, us-football, football, tennis, binoculars, swimming

• Infrastructure: zap, battery-full, battery-half, battery-low, boom, radar, wind-turbine, solar-panel, antenna, telephone-pole, oil-well, oil-barrel, railroad-track, bridge, lighthouse, lock-closed, lock-open, wifi, trash, recycle

• Nature: tree, flower, leaf, fire, mountain, snowy-mountain, volcano, island, wave, hot-springs, water, lake, ocean, animal, bird, duck, dog, fish, beach, wetland

• Weather: sun, moon, cloud, partial-sun, rain, lightning, snowflake, wind, snow, fog, sleet, hurricane

• Signs: warning, parking, info, circle-exclamation

Emojis

To use an emoji as a marker, write it as "emoji::name:" — note the double colon after emoji and the trailing colon. For example: "emoji::fire:", "emoji::tree:". iconFrame does not apply to emojis. Prefer built-in icons unless an emoji is specifically requested.

{
  "version": "2.3.1",
  "type": "simple",
  "paint": {
    "iconImage": "emoji::fire:",
    "size": 6
  },
  "legend": {}
}