Image

Displays an image from a URL with scaling, tinting, and styling options.

type: "image"atomsleaf

Crop (Default)

Image cropped to fill bounds — default contentScale

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale1/400/300",
    "contentDescription": "Sample image",
    "ui": {
      "layout": {
        "size": {
          "width": 200,
          "height": 150
        }
      }
    }
  }
}

Quick Start

{
  "type": "image",
  "data": {
    "url": "value"
  }
}

Data Fields

Field	Type	Default	Description
urlrequired	string	—	Image URL
content_description	string	—	Accessibility description

Style Fields

Field	Type	Default	Description
content_scale	enum fitfillWidthfillHeightfillBoundscropinsidenone	crop	How image scales within bounds
tint_color	color	—	Color tint applied over the image

Layout Fields

Parent Layout Fields

Examples

contentScale: fit

Image scaled to fit within bounds (may letterbox)

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale2/400/300",
    "ui": {
      "style": {
        "contentScale": "fit",
        "background": {
          "palette": "neutral",
          "shade": 50
        }
      },
      "layout": {
        "size": {
          "width": 200,
          "height": 150
        }
      }
    }
  }
}

contentScale: fillBounds

Image stretched to fill (may distort aspect ratio)

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale3/400/300",
    "ui": {
      "style": {
        "contentScale": "fillBounds"
      },
      "layout": {
        "size": {
          "width": 200,
          "height": 100
        }
      }
    }
  }
}

contentScale: none

Image at original size, no scaling

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale6/100/100",
    "ui": {
      "style": {
        "contentScale": "none",
        "background": {
          "palette": "neutral",
          "shade": 50
        }
      },
      "layout": {
        "size": {
          "width": 200,
          "height": 150
        }
      }
    }
  }
}

cornerRadius: circle

Circular avatar with crop

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale4/200/200",
    "ui": {
      "style": {
        "contentScale": "crop",
        "cornerRadius": 100
      },
      "layout": {
        "size": {
          "width": 64,
          "height": 64
        }
      }
    }
  }
}

cornerRadius: rounded

Rounded corners at 12dp

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4saleR/400/300",
    "ui": {
      "style": {
        "contentScale": "crop",
        "cornerRadius": 12
      },
      "layout": {
        "size": {
          "width": 200,
          "height": 150
        }
      }
    }
  }
}

Border

Image with 2dp primary border and rounded corners

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4saleB/400/300",
    "ui": {
      "style": {
        "contentScale": "fit",
        "border": {
          "width": 2,
          "color": {
            "palette": "primary",
            "shade": 300
          }
        },
        "cornerRadius": 8
      },
      "layout": {
        "size": {
          "width": 200,
          "height": 150
        }
      }
    }
  }
}

tintColor

Color tint overlay at 40% opacity

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4saleT/200/200",
    "ui": {
      "style": {
        "contentScale": "crop",
        "tintColor": {
          "palette": "primary",
          "shade": 200,
          "alpha": 0.4
        },
        "cornerRadius": 12
      },
      "layout": {
        "size": {
          "width": 150,
          "height": 150
        }
      }
    }
  }
}

aspectRatio: 16:9

Fill-width image with 16:9 aspect ratio

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4sale5/800/450",
    "ui": {
      "style": {
        "contentScale": "crop",
        "cornerRadius": 12
      },
      "layout": {
        "size": {
          "width": "fill",
          "aspectRatio": 1.778
        }
      }
    }
  }
}

aspectRatio: 1:1

Square image with aspect ratio constraint

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4saleSq/300/300",
    "ui": {
      "style": {
        "contentScale": "crop"
      },
      "layout": {
        "size": {
          "width": "fill",
          "aspectRatio": 1
        }
      }
    }
  }
}

Alpha (Opacity)

Image at 50% opacity

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/4saleA/200/200",
    "ui": {
      "style": {
        "contentScale": "crop",
        "alpha": 0.5,
        "cornerRadius": 8
      },
      "layout": {
        "size": {
          "width": 120,
          "height": 120
        }
      }
    }
  }
}

Icon (Small SVG)

SVG icon rendered as image with fixed size

{
  "type": "image",
  "data": {
    "url": "https://api.iconify.design/mdi/heart.svg",
    "ui": {
      "style": {
        "contentScale": "fit"
      },
      "layout": {
        "size": {
          "width": 24,
          "height": 24
        }
      }
    }
  }
}

parentLayout: weight in Row

Image takes remaining space via weight=1

{
  "type": "row",
  "data": {
    "children": [
      {
        "type": "image",
        "data": {
          "url": "https://picsum.photos/seed/w1/200/200",
          "ui": {
            "style": {
              "contentScale": "crop",
              "cornerRadius": 8
            },
            "layout": {
              "size": {
                "height": 80
              }
            },
            "parentLayout": {
              "weight": 1
            }
          }
        }
      },
      {
        "type": "image",
        "data": {
          "url": "https://picsum.photos/seed/w2/200/200",
          "ui": {
            "style": {
              "contentScale": "crop",
              "cornerRadius": 8
            },
            "layout": {
              "size": {
                "height": 80
              }
            },
            "parentLayout": {
              "weight": 1
            }
          }
        }
      }
    ],
    "ui": {
      "layout": {
        "spacing": 8,
        "size": {
          "width": "fill"
        }
      }
    }
  }
}

Production Patterns

Real patterns extracted from the 4Sale production API.

Icon (Small)16×16 fitted icon — featured badge, camera count

{
  "type": "image",
  "data": {
    "url": "https://api.iconify.design/mdi/star.svg",
    "ui": {
      "style": {
        "contentScale": "fit"
      },
      "layout": {
        "size": {
          "width": 16,
          "height": 16
        }
      }
    }
  }
}

Avatar (Circular)40×40 cropped circle — brand profile avatar

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/avatar1/100/100",
    "ui": {
      "style": {
        "contentScale": "crop",
        "cornerRadius": 100
      },
      "layout": {
        "size": {
          "width": 40,
          "height": 40
        }
      }
    }
  }
}

Brand Logo80×60 fitted — brand logo in carousel

{
  "type": "image",
  "data": {
    "url": "https://picsum.photos/seed/brand1/200/150",
    "ui": {
      "style": {
        "contentScale": "fit"
      },
      "layout": {
        "size": {
          "width": 80,
          "height": 60
        }
      }
    }
  }
}

Text

Box