GIF (lv_gif)

Display animated GIFs through the AnimatedGIF decoder library.

Overview

The GIF widget displays animated GIFs using the AnimatedGIF library. Enable it by setting LV_USE_GIF to 1 in lv_conf.h.

Image source

lv_example_gif_src.c

The example above shows the same bulb GIF loaded two ways: from an embedded lv_image_dsc_t array (left) and from a file path (right).

lv_gif_set_src(widget, src) works like lv_image_set_src, accepting image descriptors (lv_image_dsc_t) or file paths:

lv_gif_set_src(widget, "S:path/to/example.gif");

A file system driver must be registered to open images from files — see File System (lv_fs_drv).

lv_gif_set_color_format(widget, color_format) sets the GIF framebuffer color format. The default is LV_COLOR_FORMAT_ARGB8888 (required for transparency). Matching the display's color format avoids a conversion step during rendering. Call this before lv_gif_set_src to avoid allocating the default ARGB8888 framebuffer first.

Supported formats:

Converting GIF files to C arrays

bash

python ./scripts/LVGLImage.py --cf RAW --ofmt C -o . --name my_gif_image_array input.gif

LV_IMAGE_DECLARE(my_gif_image_array);
lv_obj_t * img = lv_gif_create(lv_screen_active());
lv_gif_set_color_format(img, LV_COLOR_FORMAT_ARGB8888);
lv_gif_set_src(img, &my_gif_image_array);

Memory requirements

Displaying a GIF animation requires ~25 kB of RAM plus (pixel_size + 1) × width × height bytes for the framebuffer. RGB565 = 2 bytes/pixel, RGB888 = 3, ARGB8888 = 4.

Styling

LV_PART_MAIN A background rectangle that uses the typical background style properties.

Maximum GIF Size

By default, LVGL accepts GIF images up to 480 × 32768 pixels. If a GIF exceeds either limit, it will be rejected with a GIF_TOO_LARGE error.

The limits can be changed in lv_conf.h. LV_GIF_MAX_WIDTH also controls the size of an internal line buffer embedded in every GIF widget instance, so raising it increases RAM usage by (new_width - 480) bytes per widget. LV_GIF_MAX_HEIGHT is a validation-only check and has no memory cost.

To support wider GIFs (e.g. on a 800px-wide display):

#define LV_GIF_MAX_WIDTH  800
#define LV_GIF_MAX_HEIGHT 480

To tighten the limits on a very constrained device:

#define LV_GIF_MAX_WIDTH  320
#define LV_GIF_MAX_HEIGHT 240

Events

LV_EVENT_READY is emitted when the animation completes its last frame.

Learn more about Events emitted by all Widgets.