Switch


The Alexa switch responsive component (AlexaSwitch) displays a switch the user can slide between on and off. You can control the switch size, colors, and commands to run when the user interacts with the switch.

Compatibility

AlexaSwitch 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 AlexaSwitch on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.

Import the alexa-layouts package

To use AlexaSwitch, import the alexa-layouts package.

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

AlexaSwitch Parameters

All parameters except type are optional.

Name Type Default Description Widget support Version added

accessibilityLabel

String

A string describing the switch. Voice over reads this string when the user selects the switch.

Not supported

1.2.0

activeColor

Color

A blue color. The specific shade depends on the specified theme.

Color to use for the switch when the switch is in the "on" position (checked is true).

Not supported

1.2.0

entities

Array

Array of entity data to bind to this component.

Not supported

1.2.0

layoutDirection

String

${environment.layoutDirection}

Specifies the layout direction for the content. Set this property to either LTR (left-to-right) or RTL (right-to-left). This property doesn't inherit the layoutDirection from the component's parent container. Therefore, explicitly set this property when needed.

For more details about support for right-to-left languages in the responsive components, see Support for Right-to-left Languages.

Not supported

1.4.0

primaryAction

Command

The action to trigger when the user selects the switch.

Not supported

1.2.0

switchHeight

Dimension

Height based on the viewport

Height of the switch

Not supported

1.2.0

switchWidth

Dimension

Width based on the viewport

Width of the switch.

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 AlexaSwitch

Not supported

1.2.0

checked state

AlexaSwitch uses the standard checked component state to determine whether to show the component in the on or off position. When you place the component in your document, initialize checked to true or false:

  • Set checked to true to show the switch in the on position with the thumb indicator on the right.
  • Set to false to display the switch in the off position with the thumb indicator on the left. The component sets checked to false by default.

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

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

Examples of the default switch with the checked state on and off
Examples of the default switch with the checked state on and off

disabled state

AlexaSwitch uses the standard disabled component state to determine whether to show the component enabled or disabled. When disabled is true, the switch 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 switch in the on or off position.

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

Combining the checked and disabled states
Combining the checked and disabled states

Accessibility

The AlexaSwitch component is a touchable component configured as a switch. 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 turn the switch on or off.

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

AlexaSwitch examples

Switches in different colors and sizes

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


Send the switch checked state to your skill

The following example shows a full document with two AlexaSwitch components. When the user selects a switch, the switch runs the SendEvent command to send a UserEvent request to the skill. Because the SendEvent includes the components property, the UserEvent request includes the ID and current checked state of the two switches.

To test the SendEvent command shown in the example, copy the code into a skill and test with a device or the simulator in the developer console.


The following example shows the UserEvent the skill receives when the user toggles the second switch (exampleSwitch2) from off to on. The components property in the request includes the current checked state for both of the AlexaSwitch components.

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2020-10-12T20:25:57Z",
  "locale": "en-US",
  "arguments": [
    "AlexaSwitch changed",
    "exampleSwitch2"
  ],
  "components": {
    "exampleSwitch2": true,
    "exampleSwitch1": true
  },
  "source": {
    "type": "VectorGraphic",
    "handler": "Press",
    "id": "exampleSwitch2",
    "value": false
  },
  "token": "switchSendEventCheckedStateExampleToken"
}
Two AlexaSwitch components that send a request to the skill
Two AlexaSwitch components that send a request to the skill

Was this page helpful?

Last updated: Nov 28, 2023