Custom Button

A button in the form that executes configured actions when clicked.

Widget description: `customButton`

The Process Button widget places a custom button directly into the form layout at a location you choose, instead of in the bottom bar. The button itself (label, appearance, display condition, actions, and save after click) is defined on the Buttons tab in the designer. The widget only controls where the button appears and how it is aligned. Button actions are described on the Custom Buttons page, such as Set value or Call function. It is a virtual widget and is not saved to the item.

Process Button widget settings: Linked button and Button alignment

Adding to the form

There are two ways:

From the button editor: on the Buttons tab, click Insert as widget into active tab in Layout next to the button. The designer adds the widget to the first section of the active tab, links it to that button, and shows a confirmation. Then move it wherever you need on the Layout tab.
From the palette: on the Widgets tab, drag Process Button into a section and select Linked button in the inspector.

Once placed, the button editor replaces “Shown in bottom bar” with “Placed as widget in layout: tab → section”. A button linked to a widget is not shown in the bottom bar so it does not appear twice. This also applies when it is hidden by a condition.

A widget from the palette without a selected button will not render in the form at all. Create the button on the Buttons tab first, then select Linked button. The dropdown is only offered when at least one button exists in the configuration.

Inspector settings

Option	Property	Description	Default
Linked button	`customButtonConfig.buttonId`	Which button from the Buttons tab is displayed here. Selecting one also overwrites the widget's label (`customLabel`) with the button label.	widget's own `internalName`
Button alignment	`customButtonConfig.alignment`	`left` (Left), `center` (Center), `right` (Right), `stretch` (100%, full cell width).	`left`
Width in section	`colSpan`	Cell width in the 12-column grid. The button is always aligned within its cell according to the option above.	4
Visible, Read-only	`defaultVisible`, `defaultReadOnly`	Default visibility and disabled state. A read-only button is grayed out and does not respond.	yes, no

Appearance (appearance: primary, secondary, outline, subtle), label, modes, condition, actions, confirmation prompt, and “save after actions” belong to the button, not the widget, and are edited on the Buttons tab.

Runtime behavior

Visibility: the widget is shown only when the linked button is visible—that is, when the current mode is included in its Show in modes (default New and Edit) and its condition holds (for example, field Stav equals “Draft”). The widget itself must also be visible (setVisible). A section with nothing else visible is hidden completely.
Label: the widget takes its label from the button, or falls back to customLabel or the default “Button”.
Click: executes the same sequence as a button in the bottom bar: optional confirmation prompt, then actions top-to-bottom (setValue, setExpression, callFunction), and finally, if “save after actions” is enabled, form validation and save. See Custom Buttons for details.
Disabled button: if the widget is read-only (default read-only or setReadOnly action), the button is disabled.
Display mode: in Display mode all fields are locked, so even if the button is enabled for this mode, the widget renders disabled. Therefore, do not use a button widget for Display mode; use a button in the bottom bar instead.

Buttons tab showing a button marked “Placed as widget in layout” and below it (on the second button) the Insert as widget into active tab option

Form with the “Submit for approval” button centered in the section, next to a button stretched to 100% width

Text translations

The label of the displayed button is translated via button translations (keyed by the button's id), not via the widget. See Translations and Multilingual Forms and Custom Buttons.

Rules and scripts

setVisible: hides the widget regardless of the button's condition.
setReadOnly: disables the button.
For visibility based on a field value or user group, prefer the button condition on the Buttons tab. The condition can also check user groups and form mode.
Functions called by the button are written in Scripts.

Configuration example (JSON)

A button defined in customButtons and a widget that places it in the layout:

{
  "id": "btn_ke_schvaleni",
  "label": "Submit for approval",
  "appearance": "primary",
  "showInModes": ["new", "edit"],
  "condition": { "fieldInternalName": "Stav", "operator": "equals", "value": "Draft" },
  "actions": [
    { "type": "setValue", "fieldInternalName": "Stav", "value": "Pending approval" }
  ],
  "submitForm": true,
  "confirmMessage": "Are you sure you want to submit for approval?"
}

{
  "internalName": "widget_button_ke_schvaleni",
  "customLabel": "Submit for approval",
  "fieldType": "customButton",
  "colSpan": 4,
  "defaultVisible": true,
  "customButtonConfig": {
    "buttonId": "btn_ke_schvaleni",
    "alignment": "left"
  }
}

Limitations and tips

A single button can be placed multiple times; it will appear in all placed locations and nowhere in the bottom bar.
If you do not want to place the button in the layout, do not use the widget: the button will automatically appear in the bottom bar.
If you delete a button from the Buttons tab, the widget remains in the layout without rendering. Remove it from the layout as well.
Cell width (colSpan) and alignment apply only within that section. On narrow screens, cells stack vertically like other fields.