Toggle Component

On This Page

Function

a!toggleField( choiceLabel, helpTooltip, value, saveInto, showWhen, required, requiredMessage, validations, validationGroup, disabled, accessibilityText, marginAbove, marginBelow, choicePosition )

Displays a toggle that saves a true or false value. This works well for controls that take effect immediately, like showing or hiding content.

basic toggle for enabling integration

Parameters

Name	Keyword	Types	Description
Choice Label	choiceLabel	Text	Text to display as the label next to the toggle.
Help Tooltip	helpTooltip	Text	Displays a help icon next to the choice label with the specified text as a tooltip. The tooltip displays a maximum of 500 characters.
Value	value	Boolean	Determines if the toggle is on or off. The toggle appears on when true, and off when false or null.
Save Into	saveInto	List of Save	One or more variables that are updated with the value when a user turns the toggle on or off. Use a!save() to save a modified or alternative value to a variable.
Show When	showWhen	Boolean	Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: `true`.
Required	required	Boolean	Determines if the toggle value must be true to submit the form. If required is true, a validation message displays when the value is false or null. Default: `false`.
Required Message	requiredMessage	Text	Custom message to display when required is true but the value is false or null.
Validations	validations	List of Text String	Validation errors to display below the field when the value is not null.
Validation Group	validationGroup	List of Text	The keyword used to identify the validation group for the validations parameter. When this parameter is specified, the validations parameter is only evaluated when a button that uses the same validation group is selected. This value cannot contain spaces. See the following recipes for more information: Configure Buttons with Conditional Requiredness Validation Groups for Buttons with Multiple Validation Rules'
Disabled	disabled	Boolean	Determines if the field should display as potentially editable but grayed out. Default: `false`.
Accessibility Text	accessibilityText	Text	Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.
Margin Above	marginAbove	Text	Determines how much space is added above the component. Valid values: `"NONE"` (default), `"EVEN_LESS"`, `"LESS"`, `"STANDARD"`, `"MORE"`, `"EVEN_MORE"`.
Margin Below	marginBelow	Text	Determines how much space is added below the component. Valid values: `"NONE"`, `"EVEN_LESS"`, `"LESS"`, `"STANDARD"` (default), `"MORE"`, `"EVEN_MORE"`.
Toggle Position	choicePosition	Text	Determines whether the toggle appears on the left or right of the choice label. Valid values: `"START"` (default), `"END"`.

Usage considerations

Using the value parameter

When the toggle is on, the value parameter is true.
When the toggle is off or the value parameter is null, it is treated as false.

Using the required parameter

If the required parameter is set to true, the toggle must be on (value must be true) to submit the form.

The default required message is "Enable the toggle to continue". This can be changed using the requiredMessage parameter.

Using in editable grids

Only the toggle displays in editable grids, not the choice label. Use the column heading to describe what the toggle is for.

Using the choicePosition parameter

See the SAIL Design System for choice position best practices.

Toggle vs boolean checkbox

Both toggles and boolean checkboxes capture true or false values. You can use a boolean checkbox whenever you need to capture a boolean value. Toggles can be used in some of these cases, but work best for specific use cases:

Use toggles for activation and state changes, such as:
- Enabling/disabling settings. For example, "Enable dark mode".
- Filtering data. For example, "Show inactive users".
Don't use toggles in forms. Use boolean checkboxes instead.

Examples

Use the interactive editor below to test out the example code.

Simple toggle

a!localVariables(
  local!updateNotifications,
  a!toggleField(
    choiceLabel: "Notify me when updates are made to this case",
    value: local!updateNotifications,
    saveInto: local!updateNotifications
  )
)

Feature compatibility

The table below lists this component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Compatible
Offline Interfaces	Compatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Incompatible	Cannot be used to configure a process event node, such as a start event or timer event.
Process Autoscaling	Incompatible	Cannot be used in autoscaled processes.
Event Consumer Filter Conditions	Compatible	Can be used in filter conditions.
Event Consumer Event Handlers	Compatible	Can be used in event handler expressions.

Feedback

Was this page helpful?