Check Box

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

The Alexa check box responsive component (AlexaCheckbox) displays a check box the user can toggle on and off. You can control the check box size, colors, and commands to run when the user interacts with the check box.

Compatibility

AlexaCheckbox is designed to work with all standard viewport profiles in the alexa-viewport-profiles package:

All hub round profiles
All hub landscape profiles
All hub portrait profiles
All mobile profiles
All TV profiles

If you use AlexaCheckbox on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaCheckbox, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaCheckbox was introduced in version 1.2.0.

AlexaCheckbox Parameters

All parameters except type are optional.

Name	Type	Default	Description	Widget support	Version added
`accessibilityLabel`	String	—	A string describing the check box. Voice over reads this string when the user selects the button.	Not supported	1.2.0
`checkboxHeight`	Dimension	Height based on the viewport	Height of the check box	Not supported	1.2.0
`checkboxWidth`	Dimension	Width based on the viewport	Width of the check box	Not supported	1.2.0
`entities`	Array	—	Array of entity data to bind to this component.	Not supported	1.2.0
`primaryAction`	Command	—	The action to trigger when the user selects the check box.	Not supported	1.2.0
`selectedColor`	Color	A blue color. The specific shade depends on the specified `theme`.	Fill color to use for the check box when it's selected (when `checked` is `true`).	Not supported	1.2.0
`theme`	String	`dark`	Set the dark or light color theme. The selected theme controls the colors used for the component.	Not supported	1.2.0
`type`	String	—	Always set to `AlexaCheckbox`	Not supported	1.2.0

checked state

AlexaCheckbox uses the standard checked component state to determine whether to show the component checked or cleared. When you place the component in your document, initialize checked to true or false:

Set checked to true to display the check box with a solid fill color and a check mark.
Set to false to display the check box as an outlined, empty box. The component sets checked to false by default.

The AlexaCheckbox has a third indeterminate state. Use this state for scenarios in which the check box is "partially" selected. For example, the check box represents a group of sub-options, and some of the sub-options are selected and some are not. For details about this state, see the isIndeterminate property.

When the user interacts with the check box, the component automatically toggles checked state. You don't need to track or update the checked state yourself.

The following example displays check boxes in two rows. In the first row, the check boxes initialize checked to true. In the second row, they leave checked set to the default false.

Examples of the default check box with the checked state on and off

disabled state

AlexaCheckbox uses the standard disabled component state to determine whether to show the component enabled or disabled. When disabled is true, the check box doesn't respond to any user interactions such as touch or a remote.

The disabled state is independent of checked, so you can display the disabled check box as selected or cleared.

The following example displays disabled check boxes in two rows. In the first row, the check boxes set checked to true. In the second row, they leave checked set to the default false.

Combining the checked and disabled states

isIndeterminate

AlexaCheckbox uses the isIndeterminate property to represent a third check box state. When isIndeterminate is true, the check box displays filled in with color, but with a horizontal line instead of a check mark.

Use this state to present a check box that is "partially" selected. For example, assume you are displaying a list of items and each item has a check box. In the header, you have a single overall check box that indicates the state of the full list. When some, but not all, of the items are selected, you would display the check box in the header with the indeterminate state.

When the user selects or clears the check box, AlexaCheckbox toggles the checked state and sets isIndeterminate back to the default false. The end result for the check box depends on the result of toggling checked. For example:

checked is true and isIndeterminate is true –
- The check box displays in the indeterminate state.
- When the user selects the check box, the component updates both checked and isIndeterminate to false. The check box now displays in the cleared state.
checked is false and isIndeterminate is true –
- The check box displays in the indeterminate state.
- When the user selects the check box, the component updates checked to true and isIndeterminate to false. The check box now displays in the checked state.

In both of these scenarios, when the user selects the check box again, the component updates checked but doesn't change isIndeterminate. The check box never goes back to isIndeterminate automatically. To set isIndeterminate to true during the user interaction, use the SetValue command.

Accessibility

The AlexaCheckbox component is a touchable component configured as a check box. On a device with the VoiceView screen reader enabled, the user can tap the component to select it, then double-tap on the screen to select or clear the check box.

For details about accessibility and APL, see APL Accessibility Guide.

AlexaCheckbox example

The following example shows a complete document that displays multiple check boxes with different colors and sizes. The check boxes are provided in a data source. Each row shows the same check box in the dark and light themes. When you select a check box, the check box runs a user-defined command that updates the header subtitle with information about the selected check box. The command gets the current checked state for the AlexaCheckbox from the event.source.checked property.

Last updated: Mar 02, 2023