Widgets

All twenty-one, with every setting explained and the LVGL 8/9 differences called out.

Twenty-one widgets, matching the SquareLine Studio set by name, parameter and style part. Each one is an LVGL object; each setting below is a setter LVGL offers for that type, emitted by the generator only when you change it from the default. Every widget also has the common things - name, geometry, flags, layout, styles, events and bindings - which are documented on their own pages rather than repeated twenty-one times.

LVGL 8 and 9. The catalogue is the same on both, but a few settings only exist on one. The Image widget's Inner align is LVGL 9 only, the Label's Recolor is LVGL 8 only, and the Colorwheel was removed from LVGL 9 core - the designer warns when you use it on a 9.x project. The generator switches every renamed call (lv_img_* to lv_image_*, lv_obj_clear_flag to lv_obj_remove_flag) for you.

The screen

Screen

The root object. It has no position; it is the panel. A screen is styled like any widget (a background colour is the usual thing) and takes the four screen-only events: Screen loaded, Screen unloaded, Screen load start and Screen unload start.

Group: Screen · Default size: the panel · Style parts: Main

Setting	Default	What it does
Temporary	off	Free the screen from RAM when it is unloaded and rebuild it on the next load. Worth it on a small MCU with many screens.
Don't export screen function	off	Skip the `ui_<Name>_screen_init()` so you can write that screen by hand.

Basic

Panel

A plain lv_obj with the theme's card look - a background, a border and rounded corners. The usual way to group widgets: children move with it and its Layout setting can arrange them.

Group: Basic · Default size: 200 × 120 · Style parts: Main, Scrollbar

Container

The same object as a Panel with the decoration removed - no background, no border, no padding. Use it when you want grouping or a flex row without a visible box.

Group: Basic · Default size: 200 × 120 · Style parts: Main, Scrollbar

Button

An lv_button with a centred label child. The label is generated as ui_<Name>_label so you can restyle it separately.

Group: Basic · Default size: 100 × 50 · Style parts: Main

Setting	Default	What it does
Text	Button	The caption.

Label

Text. Bind its Text to a variable and it becomes a readout; the binding's prefix, printf format and postfix are applied in bindings_apply().

Group: Basic · Default size: 100 × 24 · Style parts: Main

Setting	Default	What it does
Label mode	Wrap	What happens when the text is wider than the widget: Wrap, Dot (ellipsis), Scroll, Scroll circular or Clip.
Text	Label	The text. Multi-line is fine.
Recolor	off	Enables `#RRGGBB text#` inline colouring. LVGL 8 only - use `lv_span` on 9.
To be translated	off	Marks the string for translation tooling; no effect on the generated code.

Image

Shows an asset. The source is either &symbol for a compiled-in image or "S:/file.bin" for one on the board filesystem; the generator picks whichever the asset is set to.

Group: Basic · Default size: 100 × 100 · Style parts: Main

Setting	Default	What it does
Asset	(none)	Which imported image to show.
Pivot X / Pivot Y	0	The point rotation and scaling happen around, in pixels from the top-left.
Rotation	0°	Rotation in degrees. LVGL uses tenths of a degree internally; the generator multiplies.
Scale	256	256 is 100%. 128 is half size, 512 double.
Inner Align	Default	How the image sits inside a widget larger than it: the nine positions, Stretch or Tile. LVGL 9 only.

Textarea

Editable text. Pair it with a Keyboard widget whose Target is this textarea.

Group: Basic · Default size: 200 × 60 · Style parts: Main, Selected, Cursor, Placeholder

Setting	Default	What it does
Text	(empty)	Initial contents.
Placeholder	(empty)	Shown greyed when empty.
One line mode	off	No wrapping; Enter does not insert a newline.
Password mode	off	Shows bullets.
Accepted characters	(any)	A whitelist, e.g. `0123456789.`.
Max text length	0	0 is unlimited.

Tabview

A tab bar plus one page per tab. Each tab page is a container you can drop widgets into; the Hierarchy shows them as children.

Group: Basic · Default size: 240 × 180 · Style parts: Main, Button main, Button items

Setting	Default	What it does
Tab position	Top	Where the bar sits: Top, Bottom, Left or Right.
Tab size	40	The bar's height (or width, for Left and Right).
Tabpages	Tab 1 / Tab 2 / Tab 3	One tab per line.

Controller

Slider

A horizontal or vertical slider - make it taller than wide and LVGL turns it vertical. Fires Value changed as it moves. Bindable both ways.

Group: Controller · Default size: 180 × 12 · Style parts: Main, Indicator, Knob

Setting	Default	What it does
Min / Max	0 / 100	The range.
Mode	Normal	Normal fills from the start to the value. Symmetrical fills from zero, in whichever direction the value lies - give it a range such as -50 to 50. Range has two knobs and fills between them. The canvas and the preview draw all three, and in preview a range slider moves whichever knob you press nearer to.
Value	50	The initial value - the right-hand (or upper) knob in Range mode.
Value left	0	The lower knob in Range mode. It cannot pass the value; LVGL clamps it and so does the designer.

Switch

An on/off toggle. Bind Checked to a Boolean variable and it drives or follows it.

Group: Controller · Default size: 50 × 25 · Style parts: Main, Indicator, Knob

Setting	Default	What it does
Checked	off	Initial state.
Anim time	0 ms	How long the knob takes to slide.

Checkbox

A tick box with a caption.

Group: Controller · Default size: 120 × 24 · Style parts: Main, Indicator

Setting	Default	What it does
Title	Checkbox	The caption.
Checked	off	Initial state.

A closed list that opens on tap. The list is a separate object in LVGL, which is why it has its own three style parts.

Group: Controller · Default size: 150 × 40 · Style parts: Main, Indicator, List main, List scrollbar, List selected

Setting	Default	What it does
Options	Option 1 / 2 / 3	One per line.
List align	Bottom	Which way the list opens.
Selected	0	Initial index, from zero.
Show selected	on	Whether the closed control shows the current option.
Base text	(empty)	Fixed text to show instead of the selected option - a prompt such as "Choose".
Maximum Height	0	Caps the open list; 0 is unlimited.

Roller

A drum of options; drag to spin. Good for numbers and short lists on a touch panel.

Group: Controller · Default size: 120 × 100 · Style parts: Main, Selected

Setting	Default	What it does
Options	Option 1 … 4	One per line.
Mode	Normal	Normal stops at the ends; Infinite wraps around.
Selected	0	Initial index.
Visible rows	3	How many rows show at once - an odd number keeps the selection centred.

Arc

A circular slider - the classic dial. The background angles set where the track is drawn; the start and end angles are the current indicator, which the value normally controls. Bindable both ways.

Group: Controller · Default size: 150 × 150 · Style parts: Main, Indicator, Knob

Setting	Default	What it does
Range min / max	0 / 100	The range.
Value	40	The initial value.
Bg start / end angle	135° / 45°	Where the track begins and ends, clockwise from 3 o'clock. 135 to 45 is the usual three-quarter dial with the gap at the bottom.
Start / end angle	135° / 45°	The indicator arc. Emitted after the value so a hand-set arc is not overwritten.
Mode	Normal	Normal grows clockwise from the background start. Symmetrical grows from the middle of the background arc towards whichever side the value is on. Reverse grows anticlockwise from the background end, and the knob sits at the moving end - the canvas, the preview and the gallery previews all draw it that way.
Rotation	0°	Rotates the whole thing.

Spinbox

A number with a cursor on one digit; the Step spinbox action moves it. Values are integers with an implied decimal point.

Group: Controller · Default size: 120 × 40 · Style parts: Main, Cursor

Setting	Default	What it does
Digit count	5	Total digits shown.
Separator position	2	How many digits sit left of the decimal point.
Min / Max	-99999 / 99999	The range, in raw integer units.
Increment position	100	The step - 100 with separator 2 steps by 1.00.
Value	0	Initial value.

Image Button

A button drawn from images rather than a box. The Released image is required; the Pressed one falls back to it.

Group: Controller · Default size: 100 × 50 · Style parts: Main

Setting	Default	What it does
Button state	Released	Which state to show on the canvas and at start: Released, Pressed, Disabled and their Checked variants.
Image released / pressed	(none)	The two assets.

Keyboard

An on-screen keyboard. Give it a Target textarea and typing goes there.

Group: Controller · Default size: 300 × 140 · Style parts: Main, Scrollbar, Items

Setting	Default	What it does
Target text area	(none)	The textarea it edits.
Mode	Text lower	Text lower, Text upper, Special, Number, or User 1 for a map you define in code.

Calendar

A month view. The date it opens on is set here; wiring it to a real clock is done in your own code from ui_events.c.

Group: Controller · Default size: 240 × 220 · Style parts: Main, Scrollbar

Setting	Default	What it does
Year / Month / Day	today	The date shown at start.

Colorwheel

An HSV picker. Its Hue and Saturation can be bound to variables.

Group: Controller · Default size: 150 × 150 · Style parts: Main, Knob

Setting	Default	What it does
Mode	Hue	Which component the ring edits: Hue, Saturation or Value.
Hue	0°	Initial hue.
Saturation / Brightness	100%	Initial saturation and value.

LVGL 9. lv_colorwheel was removed from LVGL 9 core. Enable it from the extras in lv_conf.h, or target LVGL 8.

Visualiser

Bar

A progress bar. Bind its Value to a variable for a level readout.

Group: Visualiser · Default size: 180 × 16 · Style parts: Main, Indicator

Setting	Default	What it does
Min / Max	0 / 100	The range.
Mode	Normal	The same three as the slider: Normal from the start, Symmetrical from zero, Range between a start value and the value.
Value	60	The initial value.
Start value	0	The lower end of the fill in Range mode.
Animate	off	Whether value changes slide rather than jump.
Anim time	0 ms	How long the slide takes.

Chart

Line, bar or scatter series against one or two Y axes, with a rolling window. The chart is involved enough to have its own page; the settings are summarised here.

Group: Visualiser · Default size: 240 × 160 · Style parts: Main, Scrollbar, Items, Indicator, Ticks

Setting	Default	What it does
Chart type	Line	Line, Bar, Scatter or None.
Number of points	10	Points per series. On the device this is the window length in points.
Division line count X / Y	3 / 5	Grid lines.
Zoom X / Y	256	256 is 100%.
Primary Y range min / max	0 / 100	The left axis.
Secondary Y axis	off	Adds a right-hand axis with its own range; each series chooses which it is measured against.
X range min / max, X from	scatter only	The X axis range, and the variable every point takes its X from.
When full	Shift	Shift scrolls left; Circular overwrites from the start.
Rolling window	The last N points	Or a span of time in seconds, in which case the firmware paces readings to fit the point count.
Ticks and labels	various	Major and minor tick length and count, whether to label the X and Y axes, and the axis font size.
Chart data	one series	The series: each has a name, a colour, design-time values and - once a second axis exists - which axis it uses.

Scale

A ruler or gauge face: a line or an arc with tick marks and numbers along it. It shows a range rather than a value - there is no needle and nothing to drag. Put one behind an Arc to turn it into a dial, or beside a Bar to label what the fill means.

LVGL 9 only. lv_scale does not exist in LVGL 8 and the nearest equivalent has a different API, so a project set to LVGL 8 reports an error rather than generating code that will not compile. Switch the version in Project settings, or use the widget's own tick settings on a Chart instead.

Group: Visualiser · Default size: 220 × 70 · Style parts: Main, Items, Indicator

The three parts map onto what is drawn: Main is the line or arc itself, Items the minor ticks, and Indicator the major ticks and their labels. Tick colour and thickness come from each part's Line settings; the label font and colour from Indicator's Text settings.

Setting	Default	What it does
Mode	Horizontal, ticks below	Which way the scale runs and which side the ticks sit on: horizontal with ticks above or below, vertical with ticks left or right, or round with ticks pointing inward or outward.
Range min / max	0 / 100	The numbers at the two ends. Labels are interpolated between them.
Total ticks	11	Every tick, major and minor, counting both ends - so 11 ticks give 10 gaps.
Major tick every	5	Every nth tick is drawn longer and, if labels are on, numbered.
Show labels	on	Numbers beside the major ticks.
Angle range	270°	Round modes only. How much of the circle the scale covers.
Rotation	135°	Round modes only. Where it starts, measured clockwise from three o'clock - 135° with a 270° range gives the usual gauge with its gap at the bottom.
Custom labels	empty	One line per major tick, used instead of the numbers - `cold`, `warm`, `hot`, or the points of a compass. Ticks past the last line keep their number.
Ticks over children	off	Draws the ticks on top of anything inside the scale, so a needle passes under them rather than over.
Draw after children	off	Draws the whole scale after its children instead of before.

Tick length

Tick length is a style property rather than a setting, because LVGL treats it as one: set Line › Tick length on the Items part for the minor ticks and on Indicator for the major ones. Colour and thickness come from the same Line group.

The needle

A needle turns the scale into a dial. It is not a property in LVGL but a child object the scale points - either a line it draws for you, or an image it rotates - so the designer generates that child and wires it up.

Round modes only, and only on a square widget. lv_scale_set_line_needle_value and its image twin both return without doing anything if the scale is horizontal or vertical, or if its width and height differ. The settings are therefore hidden outside the round modes, and the Check tab warns when the widget is not square - LVGL would simply draw no needle and say nothing.

Setting	Default	What it does
Needle	None	None, a Line the scale draws, or an Image it rotates.
Needle value	50	Where it points at start-up. Bind the widget's Value to a variable to move it at runtime.
Needle length	60	Pixels from the centre. A negative value measures inward from the rim instead, and LVGL caps it at half the width either way.
Needle width / colour / rounded ends	4, red, on	Line needles only - applied to the generated line object.
Needle image	none	Image needles only. It is rotated about its own pivot, so draw it pointing right at 0°.

Binding the scale's Value drives the needle, which is what makes it a live gauge: point it at a temperature variable and the firmware moves it every refresh. In preview the needle follows the simulated reading the same way.

Sections

A section recolours a band of the range - the red zone on a rev counter, a green "normal" band. Each has a range, a colour and a tick width, and the colour applies to that band's line, its ticks and its labels together. Add as many as you like; a value in two overlapping sections takes the first.

The Check tab warns about a section that falls outside the scale's own range, since none of it would be drawn.

Spinner

A rotating arc for "working". It runs on an LVGL animation and needs no code.

Group: Visualiser · Default size: 80 × 80 · Style parts: Main, Arc

Setting	Default	What it does
Spin time	1000 ms	One revolution.
Arc length	60°	How much of the circle is drawn.

Widgets

The screen

Screen

Basic

Panel

Container

Button

Label

Image

Textarea

Tabview

Controller

Slider

Switch

Checkbox

Dropdown

Roller

Arc

Spinbox

Image Button

Keyboard

Calendar

Colorwheel

Visualiser

Bar

Chart

Scale

Tick length

The needle

Sections

Spinner