The Lists are built from a background Page and Buttons on it. The Buttons contain an optional icon-like Image (which can be a symbol too) and a Label. When the list become long enough it can be scrolled. The width of the buttons is set to maximum according to the object width.

You can add new list element with lv_list_add(list, "U:/img", "Text", rel_action) or with symbol icon lv_list_add(list, SYMBOL_EDIT, "Edit text"). If you do no want to add image use "" as file name. The function returns with a pointer to the created button to allow further configurations.

You can use lv_list_get_btn_label(list_btn) and lv_list_get_btn_img(list_btn) to get the label and the image of a list button.

In the release action of a button you can get the the button's text with lv_list_get_btn_text(button). It helps to identify the released list element.

To delete a list element just use lv_obj_del() on the return value of lv_list_add().

You can navigate manually in the list with lv_list_up(list) and lv_list_down(list)

You can focus on a button directly using lv_list_focus(btn, anim_en)

The animation time of up/down/focus movements can be set via: lv_list_set_anim_time(list, anim_time). Zero animation time means not animations.

Style usage

The lv_list_set_style(list, LV_LIST_STYLE_..., &style) function sets the style of a list. For details explanation of BG, SCRL and SB see Page

  • LV_LIST_STYLE_BG list background style. Default: lv_style_transp_fit
  • LV_LIST_STYLE_SCRL scrollable parts's style. Default: lv_style_pretty
  • LV_LIST_STYLE_SB scrollbars' style. Default: lv_style_pretty_color
  • LV_LIST_STYLE_BTN_REL button released style. Default: lv_style_btn_rel
  • LV_LIST_STYLE_BTN_PR button pressed style. Default: lv_style_btn_pr
  • LV_LIST_STYLE_BTN_TGL_REL button toggled released style. Default: lv_style_btn_tgl_rel
  • LV_LIST_STYLE_BTN_TGL_PR button toggled pressed style. Default: lv_style_btn_tgl_pr
  • LV_LIST_STYLE_BTN_INA button inactive style. Default: lv_style_btn_ina


  • You can set a transparent background for the list. In this case if you have only a few list buttons the the list will look shorter but become scrollable when more list elements are added.
  • The button labels default long mode is LV_LABEL_LONG_ROLL. You can modify it manually. Use lv_list_get_btn_label() to get buttons's label.
Example of List in Littlev Graphics Library

						/*Will be called on click of a button of a list*/
static lv_res_t list_release_action(lv_obj_t * list_btn)
    printf("List element click:%s\n", lv_list_get_btn_text(list_btn));

    return LV_RES_OK; /*Return OK because the list is not deleted*/


 * Create a default list

/*Crate the list*/
lv_obj_t * list1 = lv_list_create(lv_scr_act(), NULL);
lv_obj_set_size(list1, 130, 170);
lv_obj_align(list1, NULL, LV_ALIGN_IN_TOP_LEFT, 20, 40);

/*Add list elements*/
lv_list_add(list1, SYMBOL_FILE, "New", list_release_action);
lv_list_add(list1, SYMBOL_DIRECTORY, "Open", list_release_action);
lv_list_add(list1, SYMBOL_CLOSE, "Delete", list_release_action);
lv_list_add(list1, SYMBOL_EDIT, "Edit", list_release_action);
lv_list_add(list1, SYMBOL_SAVE, "Save", list_release_action);

/*Create a label above the list*/
lv_obj_t * label;
label = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(label, "Default");
lv_obj_align(label, list1, LV_ALIGN_OUT_TOP_MID, 0, -10);

 * Create new styles
/*Create a scroll bar style*/
static lv_style_t style_sb;
lv_style_copy(&style_sb, &lv_style_plain);
style_sb.body.main_color = LV_COLOR_BLACK;
style_sb.body.grad_color = LV_COLOR_BLACK;
style_sb.body.border.color = LV_COLOR_WHITE;
style_sb.body.border.width = 1;
style_sb.body.border.opa = LV_OPA_70;
style_sb.body.radius = LV_RADIUS_CIRCLE;
style_sb.body.opa = LV_OPA_60;

/*Create styles for the buttons*/
static lv_style_t style_btn_rel;
static lv_style_t style_btn_pr;
lv_style_copy(&style_btn_rel, &lv_style_btn_rel);
style_btn_rel.body.main_color = LV_COLOR_MAKE(0x30, 0x30, 0x30);
style_btn_rel.body.grad_color = LV_COLOR_BLACK;
style_btn_rel.body.border.color = LV_COLOR_SILVER;
style_btn_rel.body.border.width = 1;
style_btn_rel.body.border.opa = LV_OPA_50;
style_btn_rel.body.radius = 0;

lv_style_copy(&style_btn_pr, &style_btn_rel);
style_btn_pr.body.main_color = LV_COLOR_MAKE(0x55, 0x96, 0xd8);
style_btn_pr.body.grad_color = LV_COLOR_MAKE(0x37, 0x62, 0x90);
style_btn_pr.text.color = LV_COLOR_MAKE(0xbb, 0xd5, 0xf1);

 * Create a list with modified styles

/*Copy the previous list*/
lv_obj_t * list2 = lv_list_create(lv_scr_act(),list1);
lv_obj_align(list2, NULL, LV_ALIGN_IN_TOP_RIGHT, -20, 40);
lv_list_set_sb_mode(list2, LV_SB_MODE_AUTO);
lv_list_set_style(list2, LV_LIST_STYLE_BG, &lv_style_transp_tight);
lv_list_set_style(list2, LV_LIST_STYLE_SCRL, &lv_style_transp_tight);
lv_list_set_style(list2, LV_LIST_STYLE_BTN_REL, &style_btn_rel); /*Set the new button styles*/
lv_list_set_style(list2, LV_LIST_STYLE_BTN_PR, &style_btn_pr);

/*Create a label above the list*/
label = lv_label_create(lv_scr_act(), label);       /*Copy the previous label*/
lv_label_set_text(label, "Modified");
lv_obj_align(label, list2, LV_ALIGN_OUT_TOP_MID, 0, -10);

lv_obj_t *


(lv_obj_t * par, lv_obj_t * copy);

Create a list objects

par pointer to an object, it will be the parent of the new list

copy pointer to a list object, if not NULL then the new object will be copied from it

return pointer to the created list

lv_obj_t *


(lv_obj_t * list, const void * img_src, const char * txt, lv_action_t rel_action);

Add a list element to the list

list pointer to list object

img_fn file name of an image before the text (NULL if unused)

txt text of the list element (NULL if unused)

rel_action pointer to release action function (like with lv_btn)

return pointer to the new list element which can be customized (a button)



(lv_obj_t *list, uint16_t anim_time);

Set scroll animation duration on 'list_up()' 'list_down()' 'list_focus()'

list pointer to a list object

anim_time duration of animation [ms]



(lv_obj_t * list, lv_sb_mode_t mode);

Set the scroll bar mode of a list

list pointer to a list object

sb_mode the new mode from 'lv_page_sb_mode_t' enum



(lv_obj_t *list, lv_list_style_t type, lv_style_t *style);

Set a style of a list

list pointer to a list object

type which style should be set

style pointer to a style



* lv_list_get_btn_text(lv_obj_t * btn);

Get the text of a list element

btn pointer to list element

return pointer to the text

lv_obj_t *


(lv_obj_t * btn);

Get the label object from a list element

btn pointer to a list element (button)

return pointer to the label from the list element or NULL if not found

lv_obj_t *


(lv_obj_t * btn);

Get the image object from a list element

btn pointer to a list element (button)

return pointer to the image from the list element or NULL if not found



(lv_obj_t *list);

Get scroll animation duration

list pointer to a list object

return duration of animation [ms]



(lv_obj_t * list);

Get the scroll bar mode of a list

list pointer to a list object

return scrollbar mode from 'lv_page_sb_mode_t' enum

lv_style_t *


(lv_obj_t *list, lv_list_style_t type);

Get a style of a list

list pointer to a list object

type which style should be get

return style pointer to a style



(lv_obj_t * list);

Move the list elements up by one

list pointer a to list object



(lv_obj_t * list);

Move the list elements down by one

list pointer to a list object



(lv_obj_t *btn, bool anim_en);

Focus on a list button. It ensures that the button will be visible on the list.

btn pointer to a list button to focus

anim_en true: scroll with animation, false: without animation

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!

The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary