Images

Guide to using and optimizing images in LVGL Pro Editor.

Before referencing images in your XML files, they must be registered as named external resources. Learn how to map images from files or compiled data arrays.

Overview

In XML, images are considered external resources that need to be named in order to be referenced in XML files. Below is how to map images with names.

Registering Images

In order to use images in the Editor add your images in the images folder of your project, and list them in an <images> block in globals.xml.

<data> and <file> entries reference PNG files. To convert JPEG or SVG images to PNG, or scale images use <convert>.

Path Resolution

All src_path values are relative to the project root: the folder that contains project.xml and globals.xml. So src_path="images/logo.png" refers to <project_root>/images/logo.png on disk.

When you export C code and load images as files (<file> entries), the runtime needs to know where those files actually live on the target. This is handled by the path you pass to the project's init function:

my_ui_init("A:my_ui/v2.3/assets");

The init function concatenates this base with each src_path, so src_path="images/logo.png" resolves at runtime to "A:my_ui/v2.3/assets/images/logo.png". Images registered as data (<data> entries) are compiled into the firmware and ignore this path entirely.

See Using Exported C Code for the full init flow.

As Data

The Editor converts PNG image files to a C array that can be compiled into the project:

<images>
    <data name="logo" color_format="rgb565" src_path="images/logo.png"/>
    <data name="icon_sun" color_format="argb8888" src_path="images/sun.png"/>
</images>

All typical color formats are supported, like i1-i8, a1-a8, rgb565, rgb888, argb8888, etc. and even rgb565a8.

As these kind of images are basically C code, you need to recompile the project in the editor to see them with the final color format. To show something on the screen before recompiling the Editor uses the PNG files as fallback which always has ARGB888 color format.

As File

If the images are used as files (e.g., PNG images loaded from a file system), they can be simply added to globals.xml:

<images>
  <file name="avatar" src_path="images/avatar1.png"/>
  <file name="logo" src_path="images/path/to/my_logo.png"/>
</images>

Converting and Resizing

<convert> creates a PNG image from a source image when code is generated. Use it to bring in a source that isn't already a PNG, or to resize an asset to the size it's actually drawn at.

The source can be .svg, .jpg, .jpeg or .png. The output is always a PNG, because that's the format the Editor renders with. dest is the file a <data> or <file> entry then points at:

<images>
  <convert src="images/icons/home.svg" dest="images/icons/home.png" width="24"/>
  <data name="icon_home" src_path="images/icons/home.png" color_format="argb8888"/>
</images>

<convert> entries are processed before <data> and <file>, so dest doesn't have to exist yet. Treat converted PNGs as build output rather than sources.

Sizing

• width only or height only: the other axis follows, keeping the aspect ratio. A 960×641 photo with width="64" becomes 64×43.
• both: exactly that size; the aspect ratio is not preserved.
• scale: a percent of the source's natural size. It must be written as a percent (25%), not a factor (0.25). A 24×24 SVG with scale="25%" becomes 6×6.
• none of them: the source's natural size.

Sizes can be picked from <consts> too to allow easily changing the size of many images at once:

<consts>
  <int name="icon_size" value="16"/>
  <int name="icon_size_lg" value="28"/>
</consts>

<images>
  <convert src="images/icons/home.svg" dest="images/icons/home.png" width="#icon_size"/>
  <data name="icon_home" src_path="images/icons/home.png" color_format="argb8888"/>

  <convert src="images/icons/home.svg" dest="images/icons/lg/home.png" width="#icon_size_lg"/>
  <data name="icon_home_lg" src_path="images/icons/lg/home.png" color_format="argb8888"/>
</images>

It also works well with if_target:

<consts>
  <int name="icon_size_small" value="16"/>
  <int name="icon_size_large" value="24"/>
</consts>

<images>
  <convert src="images/icons/home.svg" dest="images/icons/home_small.png" width="#icon_size_small"/>
  <convert src="images/icons/home.svg" dest="images/icons/home_large.png" width="#icon_size_large"/>
</images>

<images if_target="small">
  <data name="icon_home" src_path="images/icons/home_small.png" color_format="argb8888"/>
</images>

<images if_target="large">
  <data name="icon_home" src_path="images/icons/home_large.png" color_format="argb8888"/>
</images>

Note that if_target belongs on the <images> block, not on <convert>. So convert every size once in a plain <images> block, then choose between the results in target-scoped blocks, as above. Both <data> entries can use the same name, because only one target is ever active.

SVG Sources

Most icon sets (Lucide, Feather, Heroicons) stroke their shapes with currentColor, which only resolves in a browser. Converted as-is, such an SVG renders as nothing at all. Replace it with a real color once, up front:

sed -i 's/currentColor/#000000/' images/icons/*.svg

Black is the practical choice: the alpha channel carries the shape, so a single asset can be tinted anywhere it's used and one icon set serves every theme.

<lv_image src="icon_home" style_image_recolor="#color_accent" style_image_recolor_opa="100%"/>

Using the Images

When the images are added to globals.xml they can be used in all places where a property has image type.

In an image widget:

<lv_image src="avatar" align="center"/>

In a style property:

<styles>
  <style name="style_bg" bg_image_src="wallpaper"/>
</styles>  

In custom properties:

<component>
  <api>
    <prop name="icon_src" type="image" default="arrow_left"/>
  </api> 

  <view>
    <lv_image src="$icon_src"/>
  </view>
</component>