Image (lv_image)

Display an image from flash (as a C array), from a file, or as a symbol glyph.

Overview

The Image widget displays images from flash (as arrays) or from files. It can also display symbols (LV_SYMBOL_...).

Using the Image decoder interface, custom image formats can be supported as well.

Styling

• LV_PART_MAIN A background rectangle that uses the typical background style properties, and the image itself uses the image style properties.

Image source

Set the source with lv_image_set_src(img, src). src can be:

• A compiled-in C array. Generate it with the LVGL Online Image Converter, declare it with LV_IMAGE_DECLARE(my_img), and pass &my_img to lv_image_set_src.
• A file path. Convert the image to binary with the same converter and route it through the File system module — e.g. lv_image_set_src(img, "S:folder/my_img.bin").
• A symbol. Pass an LV_SYMBOL_* macro to render it as text using the symbol font — useful for monochrome glyphs without a full bitmap.

SVG sources are supported when LV_USE_SVG is enabled. The example below loads an SVG and applies both widget-level (lv_image_set_scale/_rotation) and style-based transforms — handy for icons that need to stay sharp at any size:

Label as an image

Images and labels are sometimes used to convey the same thing, such as describing what a button does. In this context, images and labels are somewhat interchangeable: images can display text by using the macro LV_SYMBOL_DUMMY (which equates to a 3-byte C string containing a special code) as the prefix of the text. For example, lv_image_set_src(img, LV_SYMBOL_DUMMY "Some text").

Transparency

The internal (pixel array) and external images support 2 transparency handling methods:

• Alpha byte: An alpha channel is added to every pixel that contains its opacity, typically a byte. It is the 'A' in the various color formats that contain an alpha channel, such as ARGB8888, ARGB8565, ARGB1555, etc.
• Indexed transparent color: a specific index in a color palette serves to signal transparency for each pixel that uses it.

The format is fixed when the image is converted; from the widget's side just call lv_image_set_src(img, &my_image) like with any other source.

Palette and Alpha index

Besides RGB888 and ARGB8888 color formats, the following formats are supported:

• Indexed: Image has a color palette, and each pixel is an index into that palette.
• Alpha indexed: The values stored at pixel positions are alpha (opacity) values.

These options can be selected in the LVGL Online Image Converter. Learn more about color formats in the Color Formats section. Indexed images cannot be transformed (rotation/scale_*) because the decoder doesn't expose the full pixel buffer; use a non-indexed format for any image you plan to rotate or scale.

Recolor

A color can be mixed with every pixel of an image with a given intensity. This can be useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image. This feature can be enabled in the style by setting img_recolor_opa between LV_OPA_TRANSP (no recolor, value: 0) and LV_OPA_COVER (full recolor, value: 255). The default value is LV_OPA_TRANSP causing this feature to be disabled.

The color to mix is set by img_recolor.

This example binds image_recolor_opa to a subject via <bind_style_prop> and drives that subject from a slider — moving the slider retints the image live without any event callback:

Offset

lv_image_set_offset_x(img, x) and _offset_y(img, y) shift the source inside the widget. When the widget is smaller than the source the offset chooses which slice is visible — animate it for a texture atlas or a marquee effect.

Transformations

Transformations need the full pixel buffer, so they don't work on indexed (LV_COLOR_FORMAT_I1/2/4/8) or alpha-only formats — use ARGB, RGB or A8 for anything you plan to rotate or scale. The widget's own get_width/height/x/y still return the untransformed values.

Image-widget transforms differ from style transforms: they don't affect child widgets and don't create an intermediate snapshot layer.

Inner align

When the widget is larger than its image source, inner_align (lv_image_set_inner_align) controls placement:

• TOP_LEFT / TOP_MID / TOP_RIGHT / LEFT_MID / CENTER / RIGHT_MID / BOTTOM_LEFT / BOTTOM_MID / BOTTOM_RIGHT — pin the source to the named anchor inside the widget.
• STRETCH — independent scale on X and Y to fill the widget.
• TILE — repeat the source to fill the widget (offset shifts the tiling).
• CONTAIN — keep aspect ratio, fit inside the widget.
• COVER — keep aspect ratio, fill the widget (may crop).

offset_x/offset_y are applied after alignment — e.g. CENTER with offset_y=-10 shifts the image 10 px up from centre.

Data binding

Data bindings connect a widget property to a piece of global data — a Subject. When the subject's value changes, every widget bound to it updates automatically; and an interactive widget can write back into the subject so other subscribers see the new value.

An Image binds its src to a pointer Subject. The link is one-way (Subject → Widget): application-side writes into the subject point the widget at a new image descriptor. Only pointer subjects are supported.

• lv_image_bind_src(img, subject)

Events

By default, Image Widgets are created without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make the Widget detect and send events LV_EVENT_CLICKED.

Learn more about Events emitted by all Widgets.