Image Widget

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

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.

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:

[
    { 
        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 Name	Description
card	Background image card component
primary	Primary image component

Widget Properties

Name	Description
url	URL string, map or list of URLs
value	Widget data value to select the image from the URL map

CSS Properties

Property	Description	Example
border	Add borders around images	border: 2px solid #ccc
clip-path	Clip image	clip-path: circle(50% at 50% 50%);
filter	Apply visual effects like blur or grayscale	filter: grayscale(100%) blur(2px)
opacity	Adjust image transparency	opacity: 0.7
object-fit	Controls how an image fills its container (e.g., stretch, crop, scale)	object-fit: cover, or fill, contain, none, or scale-down
object-position	Controls where the image is anchored	object-position: top right
border-radius	Round image corners or create circular images	border-radius: 8px or border-radius: 50%
--w-gradient	Apply a gradient over the image	to top right, rgba(100,115,201,.33), rgba(25,32,72,.7)