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

4.1 Box Model

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

4.1 Box Model

LVGL box model = a 4-layer structure, which from the inside out is in the order of:

Hierarchy

Function

Code Mapping

Effect / Description

Content Area (Content)

The actual contents placed inside the box.

Label and other content controls such as tags

Located at the innermost layer, where text and icons are displayed; it is wrapped by padding and will not directly stick to the border.

Padding

The blank space between the content and the border.

set_pad_all(15)

Leave a 15-pixel margin on the top, bottom, left and right sides to keep content away from the edges and create a more polished interface.

Border

The outer contour line of the box.

set_border_width(),set_border_color()

The padding encloses the content area and forms the boundary of the box.

Shadow

The projection on the exterior of the box.

Attributes such as shadow width and offset

It is only responsible for visual beautification, does not occupy layout space, and will not affect the size or position of the box.

Summary

The LVGL box model consists of a 4-layer structure.

Content + Padding + Border + Shadow

Total size of the control = content + padding + border; shadows are not included in the actual layout size.

The sample code is as follows:

import display_driver
import lvgl as lv

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

# 1. Create container (box model carrier)
obj = lv.obj(scr)
obj.set_pos(80, 80)    # Position of the box on the screen
obj.set_size(120, 120) # Total size of the box

# 2. Core: box model styles (simplified, keeping only key attributes)
style = lv.style_t()
# --------- Padding: blank space inside the box ---------
style.set_pad_all(15)       # Uniform padding on all sides
# --------- Background (base color of the content area) ---------
style.set_bg_color(lv.color_hex(0xFF0000)) # Red background
style.set_bg_opa(255)
# --------- Border: the box's border ---------
style.set_border_width(3)   # Border width
style.set_border_color(lv.color_hex(0x00FF00)) # Green border
# --------- Shadow: drop shadow outside the box ---------
style.set_shadow_width(8)
style.set_shadow_color(lv.color_hex(0x00FFFF))
style.set_shadow_offset_x(5)
style.set_shadow_offset_y(5)

# Apply style
obj.add_style(style, lv.STATE.DEFAULT)

# 3. Content area: label (placed inside the box, squeezed by the padding)
label = lv.label(obj)
label.set_text("BOX")
label.center() # Centered inside the box
label.set_style_text_color(lv.color_hex(0xFFFFFF), 0)

# Show interface
lv.screen_load(scr)
4.1 Box Model

This code transforms the abstract "box model" into an intuitively visible interface by combining a red container, internal labels, and visual layering, which perfectly corresponds to the four-layer structure of LVGL widgets:

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/24

Initialize the document.