Labs / LVGL / 04 Quick Start Case - Layout and Space Management (Based on Web Simulator and LVGL v9.0

4.6 Scrolling

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

4.6 Scrolling

Scrolling is the core interaction mechanism in LVGL that enables users to swipe and browse when content exceeds the container bounds, which is widely applied in scenarios such as lists, long text, and carousels, with a design that aligns with the operation intuition of embedded devices.

The essence of scrolling lies in the 'size difference' between the container and the content:

It should be noted that LVGL does not support diagonal scrolling, and you can only choose one of the following two directions:

The scrollbar is a standalone component (LV_PART_SCROLLBAR) of the container, used to visually indicate:

Scrollbars can be styled individually (including color, thickness and spacing), and their show/hide logic can also be controlled.

A complete scrolling operation goes through three key stages, which can be monitored via event listeners:

Here is the quick reference sheet for LVGL MicroPython scrolling function API:

Category

Method

Function

Description / Scenario

Scroll Basic Configuration

set_scroll_dir(dir)

Set the allowed scrolling directions

It supports controlling horizontal scrolling, vertical scrolling, or disabling scrolling.

Scroll Basic Configuration

set_scrollbar_mode(mode)

Set the scrollbar display mode

The scrollbar can be configured to automatically show, always show, or be hidden.

Scroll Basic Configuration

set_scroll_snap_x(align) / set_scroll_snap_y(align)

Set scroll snapping effect

Automatically aligns to the specified position after release, which is suitable for scenarios such as carousel carousels.

Scroll Control Method

scroll_by (dx, dy, anim_en)

relative scrolling

Scroll based on the offset from the current position dx / dy in pixels.

Scroll Control Method

scroll_to(x, y, anim_en)

Absolute Scrolling

Scroll directly to the specified x / y coordinate position.

Scroll Control Method

scroll_to_x(x, anim_en) / scroll_to_y(y, anim_en)

Control horizontal/vertical scrolling independently

respectively control the scrolling position in the X-axis or Y-axis direction.

Scroll Control Method

scroll_to_view(anim_en)

Automatically scroll to display the current control

Make the current control fully displayed on the screen, which is often used for automatically locating elements.

Scroll State Acquisition

get_scroll_x() / get_scroll_y()

Get the current scroll coordinates

Returns the current X/Y scroll position of the container.

Scroll State Acquisition

get_scroll_top() / get_scroll_bottom()

Obtain the vertical boundaries

Returns the maximum scrolling boundaries at the top / bottom in the vertical direction.

Scroll State Acquisition

get_scroll_left() / get_scroll_right()

Obtain the horizontal boundary

Returns the maximum scroll boundary on the left / right side in the horizontal direction.

4.6 Scrolling

Scroll Direction Setting:

FunctionRelated code
Vertical scrollingcontainer.set_scroll_dir(lv.DIR.VER)
Horizontal scrollingcontainer.set_scroll_dir(lv.DIR.HOR)
Scrolling disabledcontainer.set_scroll_dir(lv.DIR.NONE)
Scrollbar shown automaticallycontainer.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO)

The scrollbar modes of LVGL are as follows:

Enum constantMeaningCore function (beginner-friendly)
lv.SCROLLBAR_MODE.OFFOffNever shows the scrollbar, completely hidden
lv.SCROLLBAR_MODE.ONAlways shownAlways shows the scrollbar, whether or not the content overflows
lv.SCROLLBAR_MODE.ACTIVEShown while scrollingShown only while the finger is swiping / scrolling, and hidden once it stops
lv.SCROLLBAR_MODE.AUTOAutomatic displayRecommended by default; shows the scrollbar only when the content overflows the container

LVGL provides three types of core events for capturing the entire lifecycle of scrolling:

4.6 Scrolling

Core Event

Meaning of Core Events

SCROLL_BEGIN

Triggered when scrolling starts, the scrolling animation parameters (such as animation duration, easing curve) can be modified;

SCROLL_END

Triggered when scrolling ends, suitable for executing post-scrolling cleanup logic (such as loading more content and updating status);

SCROLL

Triggered during scrolling (on every position change), it is suitable for real-time monitoring of scroll position (e. g., dynamically updating UI elements, recording scroll offset).

4.6.1 Scroll Basic Demo

In the following case, we will create a small container, place a large number of buttons inside (the content will exceed the container's size), which automatically supports scrolling, so you can intuitively understand the trigger conditions for scrolling.

import display_driver
import lvgl as lv

lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0) # Black background

# ==================== 1. Create scroll container (parent object) ====================
container = lv.obj(scr)
container.set_size(200, 150)  # Container size is very small (limits the display area)
container.set_pos(50, 50)     # Container position
container.set_scroll_dir(lv.DIR.VER) # Enable [vertical scrolling] (core)
container.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO) # Scrollbar shows automatically

# ==================== 2. Create many child buttons (content exceeds the container, triggering scrolling) ====================
for i in range(10):
    btn = lv.button(container)
    btn.set_size(180, 30)
    btn.set_pos(10, 10 + i*40) # Arrange buttons vertically
    
    label = lv.label(btn)
    label.set_text(f"Button {i+1}")
    label.center()

lv.screen_load(scr)
3 4 5 6
6 7 8 9

Here, we can see that:

We can also set different scrolling directions to view the content:

FunctionRelated code
Vertical scrollingcontainer.set_scroll_dir(lv.DIR.VER)
Horizontal scrollingcontainer.set_scroll_dir(lv.DIR.HOR)
Scrolling disabledcontainer.set_scroll_dir(lv.DIR.NONE)

Here is the horizontal scroll:

1 2 3

The following disables scrolling:

1 2 3 4

If we do not specify the scrolling direction, it will be automatically set based on the sizes of the container and the internal controls (both vertical and horizontal directions are supported):

# The comment on the line below
# container.set_scroll_dir(lv.DIR.VER)
1 4

We can also set the scrolling mode; the following is the case where the scrollbar is not displayed:

container.set_scrollbar_mode(lv.SCROLLBAR_MODE.OFF)
2 3 4 5 6

The following is to display the scrollbar when scrolling:

container.set_scrollbar_mode(lv.SCROLLBAR_MODE.ACTIVE)
4 5 6 7

The following is the case where the scrollbar is always displayed:

container.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO)
4 5 6 7

4.6.2 Scroll Event Listening

Based on Case 1, monitor the scroll start and scroll end events, and print logs in the terminal so that beginners can intuitively observe the changes in scroll status.

import display_driver
import lvgl as lv

lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

# ==================== Scroll event callback function ====================
def scroll_event_callback(e):
    target = e.get_target()  # Get the object that triggered the event (the scroll container)
    event_code = e.get_code() # Get the event type
    
    # Check for the scroll event
    if event_code == lv.EVENT.SCROLL_BEGIN:
        print("📜 滚动开始了!")
    elif event_code == lv.EVENT.SCROLL_END:
        print("📜 滚动完全结束!")

# ==================== 1. Create the scroll container ====================
container = lv.obj(scr)
container.set_size(200, 150)
container.set_pos(50, 50)
container.set_scroll_dir(lv.DIR.VER)
container.set_scrollbar_mode(lv.SCROLLBAR_MODE.ACTIVE) # Show scrollbar only while scrolling

# ==================== 2. Bind the scroll listener event (core) ====================
container.add_event_cb(scroll_event_callback, lv.EVENT.SCROLL_BEGIN, None)
container.add_event_cb(scroll_event_callback, lv.EVENT.SCROLL_END, None)

# ==================== 3. Create child buttons ====================
for i in range(10):
    btn = lv.button(container)
    btn.set_size(180, 30)
    btn.set_pos(10, 10 + i*40)
    label = lv.label(btn)
    label.set_text(f"Button:{i+1}")
    label.center()

lv.screen_load(scr)
Button4 Button5 Button6 Button7

Here, we bind an event callback to the scroll container, so that the system will automatically notify us when the screen is swiped.

The two core events are as follows:

Common use cases include loading more content when scrolling to the bottom, hiding controls while scrolling, etc.

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/24

Initialize the document.