Skip to content

Image Widget

The image widget displays an image from a URL. It can be used to provide backgrounds or foreground images.

Image Widget

The image URL can take one of three formats:

  • A string URL with ${var} references
  • Map of URLs candidates
  • List of URL candidates

String URL

If the URL is a string, the string will expand ${var} references and then be used as the image to display.

Map of URLs

If a map of URLs is provided, the image is selected based on the current widget data value. In this manner, an appropriate image can be selected based on run-time data. For example: a weather image could display a sunny image when the temperature is above 70 degrees or a cloudy image when the temperature is between 50 and 70 degrees.

js
url: {
    sunny: 'https://example.com/sunny.jpg',
    cloudy: 'https://example.com/cloudy.jpg',
    '*': 'https://example.com/default.jpg',
}

List of URLs

If the URL value is a list, the list contains candidate URLs with expressions that are evaluated at run-time to select the best match. For example:

js
[
    { 
        expression: 'temp > 40', 
        value: 'https://example.com/audio/hot.mp3',
    },
    {
        expression: true,
        value: 'https://example.com/audio/temperate.mp3'
    }
]

Auto Scale

The image scales to the size of the widget. How the image fills the widget area is controlled by the object-fit and object-position properties.

Configurable components

Class NameDescription
cardBackground image card component
primaryPrimary image component

Widget Properties

NameDescription
urlURL string, map or list of URLs
valueWidget data value to select the image from the URL map

Common CSS Properties

CategoryCSS Property / TechniquePurposeExample
BordersborderAdd borders around imagesborder: 2px solid #ccc
Effectsclip-pathClip imageclip-path: circle(50% at 50% 50%);
EffectsfilterApply visual effects like blur or grayscalefilter: grayscale(100%) blur(2px)
EffectsopacityAdjust image transparencyopacity: 0.7
Fitobject-fitControls how an image fills its container (e.g., stretch, crop, scale)object-fit: cover, or fill, contain, none, or scale-down
Positionobject-positionControls where the image is anchoredobject-position: top right
Shapesborder-radiusRound image corners or create circular imagesborder-radius: 8px or border-radius: 50%

Custom CSS Properties

NameDescriptionExample
--w-gradientApply a gradient over the imageto top right, rgba(100,115,201,.33), rgba(25,32,72,.7)