Styles

The LVGL style system: properties, states, inheritance, and transitions.

An lv_style_t holds a set of property values (color, padding, border, font, and so on) that you attach to a widget, a specific part of a widget, and a state such as LV_STATE_PRESSED or LV_STATE_FOCUSED. Styles cascade through the parent/child tree, and transitions let property changes animate between states. This section covers property groups, state handling, and common composition patterns.

Size, position, and padding

Style an object's width, height, coordinates, and padding, then add a child label.

A single lv_style_t sets radius, width to 150, height to LV_SIZE_CONTENT, vertical padding to 20, left padding to 5, and positions the object at x = 50% of the parent with y = 80. The style is applied to a base object on the active screen, and a label with the text Hello is added as a child.

Background gradient fill

Apply a two-stop vertical gradient background to a centered object.

A style is configured with radius = 5 and a lv_grad_dsc_t holding two stops: a light grey at frac = 128 and a blue at frac = 192, with LV_GRAD_DIR_VER. The style is applied to a base object that is centered on the active screen, producing a shifted vertical gradient.

Partial border sides

Draw a border only on the bottom and right edges of an object.

The style sets a grey background with radius = 10, then configures a blue border with width = 5 and opa = 50%, restricted to LV_BORDER_SIDE_BOTTOM | LV_BORDER_SIDE_RIGHT. The style is applied to a centered base object so only two sides receive the border.

Outline with padding gap

Wrap an object in a blue outline offset from its edge.

A grey-filled style with radius = 5 also sets outline_width = 2, outline_color to blue, and outline_pad = 8 so the outline sits 8 pixels outside the object's border box. The styled object is centered on the active screen.

Box shadow glow

Render a soft blue shadow around a centered object.

A grey-filled style with radius = 5 sets shadow_width = 55 and shadow_color to the main blue palette entry. Applying the style to a centered base object produces a wide blue glow on all sides.

Image recolor and rotation

Tint an image blue and rotate it using style properties.

A style sets a grey background, a blue border, image_recolor to blue with image_recolor_opa = 50%, and transform_rotation = 300 (30 degrees). The style is applied to an lv_image whose source is img_cogwheel_argb, then the image is centered on the active screen.

Arc color and width

Style the arc stroke with a red color and thin width.

A style sets arc_color to the main red palette entry and arc_width = 4, then applies it to an lv_arc centered on the active screen so the background arc renders as a thin red ring.

Text color and spacing

Style a label's text color, letter spacing, line spacing, and underline.

A style sets a grey background, a blue border, padding, and the text properties text_color to blue, text_letter_space = 5, text_line_space = 20, and text_decor = LV_TEXT_DECOR_UNDERLINE. The style is applied to a two-line label that is centered on the active screen.

Line stroke style

Style a polyline with a thick grey stroke and rounded end caps.

A style sets line_color to the main grey palette entry, line_width = 6, and line_rounded = true. The style is applied to an lv_line whose point array is set with lv_line_set_points, and the line is centered on the active screen.

Drop shadow on arc indicator

Cast a red drop shadow from an arc's indicator part.

A style sets drop_shadow_color to red, drop_shadow_radius = 16, drop_shadow_opa = 255, drop_shadow_offset_x = 5, and drop_shadow_offset_y = 10. It is added to an lv_arc on LV_PART_INDICATOR so only the foreground arc casts the shadow, and the arc is centered on the active screen.

Style transitions on press

Smoothly animate color and border changes when an object is pressed.

Two lv_style_transition_dsc_t instances animate LV_STYLE_BG_COLOR, LV_STYLE_BORDER_COLOR, and LV_STYLE_BORDER_WIDTH: the default transition runs for 100 ms with a 200 ms delay, while the pressed transition runs for 500 ms with no delay. A red pressed style is attached to LV_STATE_PRESSED on a centered base object, so pressing it eases to red and releasing eases back.

Layered base and warning styles

Override a shared base style with a warning style on one of two objects.

A style_base sets light blue background, border, shadow, white text, and a 100 pixel width. A style_warning overrides only bg_color, border_color, and text_color with yellow tones. Two labeled objects are placed on the active screen: one with only the base style aligned to LV_ALIGN_LEFT_MID, and one with the base plus warning styles aligned to LV_ALIGN_RIGHT_MID.

Local style overrides shared style

Replace a style's background color with a per-object local setting.

A reusable style sets a green background and a lighter green border with width = 3. After applying it to a centered base object, lv_obj_set_style_bg_color is called with the orange palette on LV_PART_MAIN, so the object keeps the green border but shows an orange fill.

Slider indicator part and pressed state

Style a slider's indicator differently when it is pressed.

One style gives the slider's LV_PART_INDICATOR a horizontal red gradient, and a second style adds a red shadow with shadow_width = 10 and shadow_spread = 3 on LV_PART_INDICATOR | LV_STATE_PRESSED. The slider is created with value 70 and centered on the active screen, so pressing the indicator reveals the shadow.

Extending the current theme

Create a child theme that adds a green style to every button.

A first button labeled Original theme is added to the active screen under the system theme. The helper new_theme_init_and_set clones the current theme via lv_theme_copy, reparents it with lv_theme_set_parent, and registers an apply callback that attaches style_btn to any lv_button_class object. The new theme is assigned with lv_display_set_theme, and a second button labeled New theme renders with the green background and darker border. A LV_EVENT_DELETE handler on the display frees the theme.

Opacity and transform

Compare a normal button with a half-opaque one and a rotated, scaled one.

Three 100 by 40 buttons are stacked vertically on the active screen. The first uses defaults. The second sets opa to LV_OPA_50 so the button and its label are rendered to a layer before blending. The third also sets opa to LV_OPA_50 and applies transform_rotation = 150 (15 degrees), transform_scale = 256 + 64 (1.25x), and pivots the transform at (50, 20).

Conical gradient metallic knob

Fill a circular object with a reflected conical gradient to mimic brushed metal.

A fully rounded radius = 500 style sets a black drop shadow and a background lv_grad_dsc_t built with lv_grad_conical_init centered on the object with LV_GRAD_EXTEND_REFLECT. The gradient uses up to eight grey stops depending on LV_GRADIENT_MAX_STOPS. The styled 200 by 200 object is centered on the active screen; when LV_USE_DRAW_SW_COMPLEX_GRADIENTS is disabled, a scrolling label announces the missing feature instead.

Radial gradient background

Fill the screen with a purple-to-black radial gradient.

A style's background lv_grad_dsc_t is built with lv_grad_radial_init, centered on the object and extending to the bottom-right corner with LV_GRAD_EXTEND_PAD. The stops run from 0x9B1842 to black. An object sized to the display resolution is created on the active screen and centered. When LV_USE_DRAW_SW_COMPLEX_GRADIENTS is disabled, a scrolling label reports the missing feature instead.

Four gradient button backgrounds

Stack four buttons using horizontal, vertical, linear, and radial gradients.

Two styles prepare complex gradients: a linear gradient from (0%, 0%) to (20%, 100%) with LV_GRAD_EXTEND_REFLECT, and a radial gradient centered at (30%, 30%) extending to (100%, 100%) with the same reflect mode. Four 150 by 50 buttons are aligned on LV_ALIGN_CENTER: the first two use local bg_grad_dir set to LV_GRAD_DIR_HOR and LV_GRAD_DIR_VER, and the last two apply the linear and radial gradient styles. A fallback label reports when LV_USE_DRAW_SW_COMPLEX_GRADIENTS is disabled.

Modal overlay timing

Compare a full-screen dim layer against a recolor overlay for modal dialogs.

The scene from lv_example_style_12 is reused as the background, then a modal overlay is drawn over it. By default a semi-transparent black background is set on lv_layer_top(); toggling the #if 0 branch switches to lv_obj_set_style_recolor on the active screen instead. A slider is added to lv_layer_top() and centered, then lv_refr_now and lv_tick_elaps print the render cost of the chosen approach through LV_LOG_USER.

Transform a card with arc and slider

Rotate and scale a styled profile card using an arc and a slider.

Separate styles configure a grid-based card with shadow and rounded corners, a circular avatar with shadow, and a gradient like-button. The helper card_create assembles the card from an avatar image, a name label, and a like-button. Two cards are centered on the active screen; the back one is faded with LV_OPA_50. A large arc and a bottom-aligned slider drive the front card through LV_EVENT_VALUE_CHANGED: the arc writes transform_rotation from lv_arc_get_angle_end * 10, while the slider (range 128 to 300, initial 256) sets transform_scale_x and transform_scale_y.