Button

The primary way an operator does something. On its own a button does nothing — attach event actions to its click event.

Reach for it when you need:

• Start/stop commands
• Navigating to a detail view
• Running a Gateway script

Component name: Button · Category: Input

In the palette: Clickable button

Properties

Any property can be bound to a tag, another component's property, or a query.

Property	Type	Default	Description
label	string	Click Me	—
variant	enum	primary	primary · secondary · outline · ghost · soft (tinted, low emphasis) · link (text only) · success · warning · destructive. Keep success/warning/destructive for real start/caution/stop actions — saturated colour on an HMI should mean something. Options: primary · secondary · outline · ghost · soft · link · success · warning · destructive. 1.0.8
size	enum	inherit	Padding, font, icon and corner radius. Project default = the project's Control size (Project settings → Theme). The px figure is the natural height (fit = content, or inside a Flex container); with fit = fill the widget box sets the height. Use md or larger on touch panels — sm/xs are below the 44 px touch-target minimum. Options: inherit · xs · sm · md · lg · xl. 1.0.8
shape	enum	rounded	rounded (radius scales with size) · square · pill. Options: rounded · square · pill. 1.0.8
fit	enum	fill	Fill box = the button stretches to the widget box (resize it on the canvas). Fit content = the natural size for size, centered in the box. Options: fill · content. 1.0.8
iconOnly	boolean	false	Hide the label and shrink the button to the icon (keeps the chosen variant color)
color	color	""	Button background color (overrides the variant; still overridable via the inline Style editor)
hover	object	{"background":"","color":"","fontSize":0}	Hover overrides (each value is validated): background color, text color, and font size (px).
↳ hover.background	color	""	Background color on hover (overrides the variant). Validated as a CSS color.
↳ hover.color	color	""	Text/font color on hover. Validated as a CSS color.
↳ hover.fontSize	number	0	Font size (px) on hover; 0 = inherit the base size.
iconOptions	object	{"icon":"","size":0,"position":"left","color":"","gap":8}	Icon: name, size, position, color, and gap to the label
↳ iconOptions.icon	icon	""	Pick from the icon library
↳ iconOptions.size	number	0	Icon size (px). 0 = auto: follows the button size (12/14/16/18/22 px for xs…xl). 1.0.8
↳ iconOptions.position	enum	left	Options: left · right.
↳ iconOptions.color	color	""	—
↳ iconOptions.gap	number	8	Space (px) between icon and label
disabled	boolean	false	—
style	style	{}	Custom CSS properties

Events

Attach event actions to these in the Event Manager.

Event	Label	Group	Payload
click	Click	Mouse	The DOM event.
dblclick	Double click	Mouse	The DOM event.
contextmenu	Right click	Mouse	The DOM event.
mouseenter	Mouse enter	Mouse	The DOM event.
mouseleave	Mouse leave	Mouse	The DOM event.

Right-click behaves differently in the Designer

contextmenu fires your configured actions at runtime only — in LiveView and in preview. On the Designer canvas the right-click is captured to open the Event Manager, so testing it there will not run your actions. Test right-click in preview.

Notes

Confirm consequential actions. A button that starts equipment should ask first, and the tag it writes should carry a write level — hiding the button is usability, not a control.

Size, shape and fit New in 1.0.8

Until 1.0.8 the button had one look: fixed padding, a 44 px minimum height and a 16 px icon. Three settings now shape it:

• size — xs to xl, the same scale as the field widgets (28, 36, 44, 52 and 64 px natural height), so a button beside an Input of the same size lines up with it exactly. Project default follows the project's Control size.
• shape — rounded (the corner radius grows with the size), square or pill.
• fit — fill (the default, and the old behaviour) stretches the button to the widget box, so resizing the box on the canvas resizes the button. content draws it at its natural size for size, centred in the box.

The icon follows the size too: iconOptions.size 0 (the new default) means 12, 14, 16, 18 or 22 px for xs to xl. A number you set still wins, and a button saved before 1.0.8 keeps the 16 it was saved with.

Variants

primary, secondary, outline and ghost are joined by New in 1.0.8 soft (a tinted, low-emphasis button), link (text only), and success, warning and destructive. Keep the last three for actions that really are start, caution and stop: saturated colour on an HMI should mean something, and a screen where every button is green teaches operators to ignore it.

The button also draws a visible focus ring for keyboard users. New in 1.0.8

Fields, buttons and menus draw smaller after upgrading to 1.0.8

Before 1.0.8 these widgets had one size, what is now md (a 44 px field). The project's Control size defaults to sm (36 px), sized for desktop dashboards, and every widget whose size is Project default follows it — which is every widget in an upgraded project. On a touch panel, set Project settings → Theme → Control size to md or larger: 44 px is the touch-target minimum.

See also

• Event actions