Custom Buttons
Custom buttons run a sequence of actions: setting values, evaluating expressions, and calling scripts.
What Buttons Are For
A custom button (customButtons) speeds up steps a user would otherwise perform manually: "Approve" sets Status to Approved, fills in the approver, and immediately saves the form. A button is defined once in the designer (Bar & Buttons tab) and appears in the top form bar, the bottom footer, or as a widget placed anywhere in the layout.
Button Placement
Since 1.19.0, placement is configured with toggle chips in the button detail (the placements property; multiple locations can be selected at once): Form bar (top command bar of the form), Footer (bottom bar of the form), and In form (widget inside a section). Turning on the "In form" chip lets you choose a section and inserts the widget; turning it off removes the widget from all layouts in a single Undo step after confirmation. Next to the option, you can see which sections contain the button. The footer shows the button even if it is also placed as a widget. With no location enabled, the button is not shown anywhere (the designer warns about this). How to return a button to the footer: enable "Footer" (and optionally disable "In form"). The Bar & Buttons tab shows a preview of both the bar and the footer. Buttons on the list command bar and item context menu are not part of the form: they are configured on the List Actions tab.
The older placement property (legacy) continues to be read on saved forms with the same behavior; it applies only when placements is absent. Meaning: placement specifies where the button appears: section (default, in the bottom bar or as a widget), header (only in the top command bar), or both (in the bar and at the bottom). The button card shows a badge indicating where it is displayed. Legacy buttons without placement behave as section. When the command bar is disabled, header buttons are not displayed.
Custom Buttons and the Button Widget
Each button can appear in the top form bar, in the bottom footer, and as a widget directly inside a layout section:
- In the bottom bar / footer (default). The button appears next to Save and Cancel.
- As a widget in the layout. Enabling the In form chip in the button detail (or inserting the Custom Button widget in Layout,
fieldType: "customButton") adds a reference to the button in the selected section viacustomButtonConfig.buttonId. The button then appears in its position among fields (and remains in the footer only if the Footer chip is also enabled).
The definition (label, actions, conditions) is the same in all placements. The widget additionally controls alignment (alignment: left, center, right, stretch). The bottom bar is displayed when the form uses default actions or contains custom buttons.
Bar & Buttons Tab: List and Detail (since 1.28.0)
The Bar & Buttons tab is split into two parts. On the left is the Form Buttons list: the Show top command bar toggle, the System group (Back to list, Edit, Save, Cancel, Print, and Form Settings; each row shows its modes and has a visibility toggle, see bar settings), and the Custom · process group with the + Add button link. Custom buttons can be reordered by dragging the handle or using the arrows on the selected row; the list order is the bar order. The ϟ condition badge indicates a button with a display condition. On the right is the detail of the selected row. The Preview bar button opens a side panel with the actual bar and footer (sample data, actions do not execute); clicking a custom button selects it in the list.
Add a new button using + Add button. The custom button detail includes Duplicate (inserts a copy after the original with a new ID), Delete, and sections Label, Icon, Appearance (four preview tiles), Where and when to show (placements, modes, and condition), and On click (steps in order: confirmation dialog, actions, validation, and saving the form; disabled steps are dimmed and unnumbered). A system button detail offers only the label (empty = default text) and the modes determined by the form. Button properties:
| Option | Property | Meaning | Default |
|---|---|---|---|
| Button label | label | text on the button, may include symbols (for example, "✓ Approve"). Required. | – |
| Button appearance | appearance | primary (accented), secondary, outline, subtle | secondary |
| Icon | icon | optional icon from presets (same as tabs and sections), displayed on the button in both the bar and section. Without it, a bar button uses a lightning icon. | lightning |
| Show in modes | showInModes | when the button is visible: new, edit, display. At least one must remain checked. | new, edit |
| Show button only when condition is met | condition | single condition in the same format as rules (field, operator, value; supports $formMode, $userGroups, and @Me). Legacy form; conditions is written now. | no condition |
| Multiple display conditions | conditions, conditionMatch | a list of conditions of the same shape and how they combine: all (all must hold, default) or any (at least one). Takes precedence over condition; an empty list means the button is always visible. In the designer, add conditions with + Add condition; with two or more, toggle all match / at least one matches. | no conditions |
| Validate and save form after actions | submitForm | enabled: triggers save after actions. Disabled: the button only runs the actions. | enabled |
| Confirmation prompt before execution | confirmMessage | prompt text shown in a confirmation dialog. If filled, the button asks before running actions and does nothing if canceled. | no prompt |
| Confirmation title | confirmTitle | title of the confirmation dialog; translatable. Without it, the default title "Confirm" is used. The dialog has Confirm and Cancel buttons. | – |
- Order is changed by dragging the card by its left handle or using the arrows on the card. The same order applies in both the top bar and the bottom bar.
- Actions are added with + Add action and run from top to bottom. A button with no actions simply submits the form (if
submitFormis enabled). - Label, prompt, and title can be translated into other languages. If you switch the designer language to a non-default language, texts edited on this tab (label, confirmation title and prompt, system button labels) are saved directly to that language's translations.
Runtime Behavior
- The button is shown when the current form mode is in
showInModesand the display conditions are met (conditionscombined byconditionMatch, or the legacycondition). The condition is re-evaluated whenever a referenced field changes. - On click, the confirmation prompt is shown if
confirmMessageis set. Canceling does nothing. - Actions execute in order. Written values mark the form as dirty, as if entered by the user.
- If
submitFormis enabled, the form is validated and submitted just like clicking Save, includingonSaverules and theonBeforeSavescript (see Blocking Save). If validation fails, it is not saved.
For an approval button, set appearance: "primary", add a confirmMessage, and set a condition so it appears only in the "Pending Approval" status and only to the approvers group ($userGroups). Use two conditions combined as all match: Stav equals "Ke schválení" and $userGroups contains "Schvalovatelé".
In Display Mode
A button with display in "Show in modes" is active in Display mode (even when placed as a widget and fields are read-only). Because Display mode does not save anything, only the callFunction action executes (e.g., showing a notification or opening a link in your function). Write actions (setValue, setFieldValue, setExpression) and submitForm are skipped and a warning is logged to the browser console. Skipping rather than hiding keeps a button that combines a function with a write action usable.
When Scripts Are Disabled
The callFunction action is a script, so it will not run on a tenant that has not allowed scripts. Such an action is silently skipped, other actions (setValue, setExpression) run, and saving proceeds if enabled. Calls to a function that no longer exists are similarly skipped.
Button Actions
Each action has a type property. Three actions are available in the editor: setting a value, evaluating an expression, and calling a function.
Set field value (legacy name) setFieldValue
Legacy name for the setValue action. It behaves identically and takes the same parameters (fieldInternalName, value). Configurations with this type continue to work. The editor displays it as "Set field value" and saves it as setValue when edited. Use setValue for new configurations.
{ "type": "setFieldValue", "fieldInternalName": "Stav", "value": "Schváleno" }Set fixed value setValue
Writes a fixed value into a field. Parameters: fieldInternalName (target field) and value (string, number, or true/false). The editor provides a text input; enter values of other types in Raw JSON. Unlike rules, it does not support @Me and @Today tokens as values: use setExpression for those. The value is written once, and the user can change it afterward.
{ "type": "setValue", "fieldInternalName": "Stav", "value": "Schváleno" }Set expression setExpression
Evaluates an expression and writes the result into a field. Parameters: fieldInternalName and expression. The expression reads current form values at the moment of click and works even when scripts are disabled. An empty result leaves the field unchanged; an invalid numeric result (division by zero) clears the field. To fill in the current user or today's date, use @Me, @Today, or TODAY().
{ "type": "setExpression", "fieldInternalName": "DatumSchvaleni", "expression": "@Today" }Call script function callFunction
Runs a named function from form scripts and waits for it to finish before continuing to the next action. Parameter: functionName (name from scripts.functions). The function runs in the user phase, so values set via ctx.setValue mark the form as dirty. If the function is unknown or scripts are disabled, the action is skipped. See When Scripts Are Disabled.
{ "type": "callFunction", "functionName": "prepocitejDph" }Example: Approval Button
{
"id": "btn-schvalit",
"label": "✓ Schválit",
"appearance": "primary",
"showInModes": ["edit"],
"condition": { "fieldInternalName": "Stav", "operator": "equals", "value": "Ke schválení" },
"actions": [
{ "type": "setValue", "fieldInternalName": "Stav", "value": "Schváleno" },
{ "type": "setExpression", "fieldInternalName": "DatumSchvaleni", "expression": "@Today" }
],
"submitForm": true,
"confirmMessage": "Opravdu chcete žádost schválit?"
}Status and approval date are set, the user confirms the prompt, and the form is saved. The button is visible only when opening an item in Edit mode with the status "Pending Approval".