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.
A blue color. The specific shade depends on the specified theme.
Fill color to use for the check box when it is selected (when checked is true).
1.2.0
theme
String
dark
Set the dark or light color theme. The selected theme controls the colors used for the component.
1.2.0
type
String
None
Always set to AlexaCheckbox
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.
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.
{"type":"APL","version":"1.6","theme":"dark","import":[{"name":"alexa-layouts","version":"1.3.0"}],"layouts":{"CheckboxRow":{"description":"Display a row with text on the left, and then 4 checkboxes on the right. All 4 have the same checked state, but differing themes and disabled states.","parameters":["textToDisplay","checked","disabled","isIndeterminate","arrayOfCheckboxes"],"item":{"type":"Container","description":"Main container for the check box row.","direction":"row","width":"100vw","paddingLeft":"@marginHorizontal","paddingRight":"@marginHorizontal","items":[{"type":"Text","description":"Display the passed in text describing the row.","text":"${textToDisplay}","width":"75%","textAlignVertical":"center","shrink":1,"style":"textStyleBody"},{"type":"Container","description":"Display the check boxes based on the disabled and theme data provided in the array.","direction":"row","data":"${arrayOfCheckboxes}","items":[{"type":"AlexaCheckbox","checked":"${checked}","isIndeterminate":"${isIndeterminate}","disabled":"${data.disabled}","theme":"${data.theme}"}]}]}}},"mainTemplate":{"parameters":["checkBoxStateData"],"items":[{"type":"Container","items":[{"type":"AlexaHeader","headerTitle":"${checkBoxStateData.headerTitle}","headerSubtitle":"${checkBoxStateData.headerSubtitle}"},{"type":"Sequence","height":"100vh","width":"100vw","data":"${checkBoxStateData.arrayOfCheckboxRows}","items":[{"type":"CheckboxRow","textToDisplay":"${data.textToDisplay}","checked":"${data.checked}","isIndeterminate":"${data.isIndeterminate}","arrayOfCheckboxes":"${checkBoxStateData.arrayOfCheckboxes}"}]}]}]}}
{"checkBoxStateData":{"headerTitle":"Check box states","headerSubtitle":"Default / Disabled / Light theme / Light theme and disabled","arrayOfCheckboxRows":[{"checked":true,"textToDisplay":"Checked"},{"checked":false,"textToDisplay":"Not checked"},{"checked":true,"isIndeterminate":true,"textToDisplay":"Checked and indeterminate"},{"checked":false,"isIndeterminate":true,"textToDisplay":"Not checked and indeterminate"}],"arrayOfCheckboxes":[{"theme":"dark"},{"theme":"dark","disabled":true},{"theme":"light"},{"theme":"light","disabled":true}]}}
Examples of the indeterminate state combined with other states
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.
{"type":"APL","version":"1.6","import":[{"name":"alexa-layouts","version":"1.3.0"}],"layouts":{"CheckboxRow":{"parameters":["checkboxText","checkboxId","checked","disabled","isIndeterminate","checkboxHeight","checkboxWidth","selectedColor","theme"],"item":{"type":"Container","direction":"row","width":"100vw","paddingLeft":"@marginHorizontal","items":[{"type":"Text","text":"${checkboxText}","textAlignVertical":"center","width":"75%"},{"type":"AlexaCheckbox","id":"${checkboxId}","checkboxHeight":"${checkboxHeight}","checkboxWidth":"${checkboxWidth}","selectedColor":"${selectedColor}","checked":"${checked}","disabled":"${disabled}","isIndeterminate":"${isIndeterminate}","primaryAction":[{"type":"ShowCheckBoxResult"}]},{"type":"AlexaCheckbox","id":"${checkboxId}_light","checkboxHeight":"${checkboxHeight}","checkboxWidth":"${checkboxWidth}","selectedColor":"${selectedColor}","checked":"${checked}","disabled":"${disabled}","isIndeterminate":"${isIndeterminate}","theme":"light","primaryAction":[{"type":"ShowCheckBoxResult"}]}]}}},"mainTemplate":{"parameters":["checkboxExampleData"],"item":{"type":"Container","width":"100vw","height":"100vh","items":[{"type":"AlexaHeader","id":"headerId","headerTitle":"Check box examples","headerSubtitle":"Select the check box and see <code>checked</code> state here"},{"type":"Sequence","height":"80%","data":"${checkboxExampleData.arrayOfCheckboxes}","paddingBottom":"@spacing3XLarge","items":[{"type":"CheckboxRow","checkboxId":"${data.checkboxId}","checkboxText":"${data.checkboxText}","checkboxHeight":"${data.checkboxHeight}","checkboxWidth":"${data.checkboxWidth}","selectedColor":"${data.selectedColor}","checked":"${data.checked}","disabled":"${data.disabled}","isIndeterminate":"${data.isIndeterminate}","theme":"${data.theme}"}]}]}},"commands":{"ShowCheckBoxResult":{"commands":[{"type":"SetValue","componentId":"headerId","property":"headerSubtitle","value":"You changed ${event.source.id} to ${event.source.checked}"}]}}}