Symbol

A symbol is a reusable component: you design it once in the symbol library, then place as many linked copies as you need. Editing the symbol updates every copy, while each copy can keep small tweaks of its own.

Overview

Term	Definition
Symbol	A component definition that lives in the symbol library and is edited on its own canvas.
Instance	A linked copy of a symbol, placed on a screen. Instances follow the definition.

Symbols are useful for repeated interface elements such as headers, cards, toolbars, and buttons that appear on many screens. One design to maintain, one function in the generated code, and identical appearance everywhere.

Creating a symbol

Open the Symbols tab in the navigator, next to Hierarchy.
Click New in the symbol library header. An empty symbol opens on the canvas and the editor switches to symbol editing mode.
Add widgets to the symbol exactly as you would on a screen.
Click the check button in the symbol toolbar to save the definition.

Symbol library actions take effect immediately:

Rename - click the pencil icon on the row.
Reorder - drag a row up or down. The order is also the order symbols appear in the widget palette.
Delete - see Deleting a symbol.

Only the artwork inside the symbol needs to be saved; renaming, reordering, and deleting apply as you do them.

Editing a symbol

Selecting a symbol in the library opens its definition on the canvas and the symbol toolbar above the canvas shows Editing symbol with its name. An amber dot marks unsaved changes.

Control	Behavior
Undo / Redo	Step through changes made in this editing session.
Discard (✕)	Discard unsaved changes and close the editor; asks for confirmation.
Save (✓)	Save the definition and update its instances.

Discard and Save are enabled only while the symbol has unsaved changes.

Note

Symbol edits are not saved automatically. Switching to another symbol, or back to the Hierarchy tab, prompts Discard unsaved changes? when the current definition has unsaved edits. Confirm to return to the last saved version. Library operations (renaming, reordering, deleting) are saved to the project immediately; discarding only affects the current symbol's unsaved edits and does not undo those operations.

An unsaved symbol draft also blocks export: finish with Save or discard with ✕ before building or exporting the project.

Creating instances

Expand the widget bar, and the Symbols group in the widget bar lists every symbol you can place:

Click a tile to add an instance to the active screen or a container on it.
Drag a tile onto the canvas to decide the position yourself.

Every placed copy is linked. To place the same symbol many times, repeat either action.

Note

The palette is read-only in preview mode, and hides symbols that would create a circular reference while you are editing a symbol.

Working with an instance

An instance behaves as a single object on the canvas: its internal widgets are locked, clicking any part of it selects the instance, and the hierarchy shows it as a leaf. To change its content, edit the symbol.

What you can change per instance:

Setting	Behavior
Position	Always set by the instance; where you place it is never taken from the definition.
Display name	Local to the instance and free to edit.
Identifier	Local to the instance; used as the generated C variable name.
Other rows	Shown by Edit Instance in the inspector, see below.

The inspector starts collapsed for an instance and shows only the rows that are clearly local. Above them sit:

Edit Symbol - opens the definition's editor.
More actions (…) - contains Edit Instance, which reveals the rest of the widget rows.

Editing a row to a different value makes that value local to the instance. Local values are sticky: they keep their value the next time the symbol is saved.

Once an instance has local values, the menu offers Reset, which restates the symbol's design over everything this instance changed. Its position, name, identifier, children, and link stay as they are.

Saving a symbol with existing instances

Saving a definition updates every instance:

Values you never touched on an instance follow the new design.
Values you changed on an instance keep your value.
A property you removed on an instance stays removed; a later definition edit does not bring it back.

Use Reset on an instance when you want it to follow the symbol again.

Deleting a symbol

Deleting a symbol removes its library entry only. While the symbol is still used by instances, the editor refuses with Symbol is still in use, which names the number of widgets involved. Delete those instances first, then delete the symbol.

Generated code

Each symbol becomes one reusable function in the generated output, and instances reuse it rather than duplicating the design:

A definition is emitted as create_symbol_<identifier>(lv_obj_t * parent) in generated/symbols.c and generated/symbols.h.
An untouched instance emits one call plus its position.
An instance with local values emits the call, its position, and only the differences it states.
The children inside an instance are not emitted separately.

Prefixing one symbol with create_symbol_ makes it easy to find the code behind each instance; see the codegen guide for the generated file layout.

Layout - arrange the widgets inside a symbol.
Image - assign image resources to widgets inside a symbol.
Font library - typography for symbol content.
Codegen - how symbols become generated functions.
Overview - design screens on the canvas.
Navigator - screens, hierarchy, and the Symbols tab.
Preview - verify a symbol's appearance and behavior.