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

Common CSS Properties

Category	CSS Property / Technique	Purpose	Example
Borders	border	Add borders around images	border: 2px solid #ccc
Effects	clip-path	Clip image	clip-path: circle(50% at 50% 50%);
Effects	filter	Apply visual effects like blur or grayscale	filter: grayscale(100%) blur(2px)
Effects	opacity	Adjust image transparency	opacity: 0.7
Fit	object-fit	Controls how an image fills its container (e.g., stretch, crop, scale)	object-fit: cover, or fill, contain, none, or scale-down
Position	object-position	Controls where the image is anchored	object-position: top right
Shapes	border-radius	Round image corners or create circular images	border-radius: 8px or border-radius: 50%

Custom CSS Properties

Name	Description	Example
--w-gradient	Apply a gradient over the image	to top right, rgba(100,115,201,.33), rgba(25,32,72,.7)