Boolean Checkbox Component

On This Page

Function

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

Displays a single checkbox that saves a true or false value. This works well for confirmations, such as agreeing to terms and conditions. To select multiple items from a list, use the checkbox component.

basic boolean checkbox for terms and conditions

Parameters

Name	Keyword	Types	Description
Choice Label	choiceLabel	Text	Text to display as the label next to the checkbox.
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 checkbox is selected. The checkbox appears as selected when true, and unselected when false or null.
Save Into	saveInto	List of Save	One or more variables that are updated with the value when a user selects or deselects the checkbox. 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 checkbox must be selected 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 the checkbox is required and not selected.
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"`.
Choice Position	choicePosition	Text	Determines whether the checkbox appears on the left or right of the choice label. Valid values: `"START"` (default), `"END"`.

Usage considerations

Using the value parameter

When the checkbox is selected, the value parameter is true.
When the checkbox is unselected or the value parameter is null, it is treated as false.

Using the required parameter

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

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

Using in editable grids

For a more straightforward development experience, if you need to select rows in an editable grid, use the built-in row selection parameters instead of adding a boolean checkbox column.
Only the checkbox displays in editable grids, not the choice label. Use the column heading to describe what the checkbox 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 boolean checkbox

a!localVariables(
  local!termsAgreed,
  a!booleanCheckboxField(
    choiceLabel: "I agree to the terms and conditions",
    value: local!termsAgreed,
    saveInto: local!termsAgreed
  )
)

Required boolean checkbox

a!localVariables(
  local!termsAgreed,
  {
    a!booleanCheckboxField(
      choiceLabel: "I agree to the terms and conditions",
      value: local!termsAgreed,
      saveInto: local!termsAgreed,
      required: true,
      requiredMessage: "Accept the terms and conditions to continue"
    ),
    a!buttonArrayLayout(
      buttons: {
        a!buttonWidget(
          label: "Submit",
          submit: true,
          style: "SOLID"
        )
      }
    )
  }
)

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?