Switch

Switch enables users to toggle between two states: on and off.

Switch Values

The initialValue and value properties of the switch are transformed to a Boolean value to display the on (true) or off (false) state with this logic:

• null and undefined go to false.
• If the property is Boolean, the property value is used as is.
• If it is a number, NaN and 0 result in false; other values represent true.
• If the property is a string, the empty string and the literal "false" string result in false; others result in true.
• The empty array value goes to false; other array values result in true.
• Object values with no properties result in false; other values represent true.

Behaviors

This component supports the following behaviors:

Properties

autoFocus

default: false

If this property is set to true, the component gets the focus automatically when displayed.

enabled

default: true

This boolean property value indicates whether the component responds to user events (true) or not (false).

This boolean property indicates whether the checkbox responds to user events (i.e. clicks); it is true by default.

<App>
  Enabled switches:
  <HStack>
    <Switch initialValue="true" enabled="true" />
    <Switch initialValue="false" enabled="true" />
  </HStack>
  Disabled switches:
  <HStack>
    <Switch initialValue="true" enabled="false" />
    <Switch initilaValue="false" enabled="false" />
  </HStack>
</App>

<App>
  Enabled switches:
  <HStack>
    <Switch initialValue="true" enabled="true" />
    <Switch initialValue="false" enabled="true" />
  </HStack>
  Disabled switches:
  <HStack>
    <Switch initialValue="true" enabled="false" />
    <Switch initilaValue="false" enabled="false" />
  </HStack>
</App>

initialValue

default: false

This property sets the component's initial value.

readOnly

default: false

Set this property to true to disallow changing the component value.

If true, the value of the component cannot be modified.

<App>
  <Switch readOnly="true" label="Checked" initialValue="true" />
  <Switch readOnly="true" label="Unchecked" intialValue="false" />
</App>

<App>
  <Switch readOnly="true" label="Checked" initialValue="true" />
  <Switch readOnly="true" label="Unchecked" intialValue="false" />
</App>

required

default: false

Set this property to true to indicate it must have a value before submitting the containing form.

validationStatus

default: "none"

This property allows you to set the validation status of the input component.

Available values:

Events

click

This event is triggered when the Switch is clicked.

Signature: click(event: MouseEvent): void

• event: The mouse event object.

didChange

This event is triggered when value of Switch has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

This event is triggered when the Switch is toggled due to user interaction. A read-only switch never fires this event, and it won't fire if the switch's value is set programmatically.

<App verticalAlignment="center" var.changes="">
  <Switch label="Changeable" onDidChange="changes += '+'" />
  <Switch label="Readonly" readOnly="true" onDidChange="changes += '-'" />
  <Text value="Changes: {changes}" />
</App>

<App verticalAlignment="center" var.changes="">
  <Switch label="Changeable" onDidChange="changes += '+'" />
  <Switch label="Readonly" readOnly="true" onDidChange="changes += '-'" />
  <Text value="Changes: {changes}" />
</App>

gotFocus

This event is triggered when the Switch has received the focus.

Signature: gotFocus(): void

This event is triggered when the Switch receives focus.

Click the Switch in the example demo to change the label text. Note how clicking elsewhere resets the text to the original.

<App var.focused="{false}" verticalAlignment="center">
  <Switch
    value="true"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
  />
  <Text value="{focused === true ? 'I am focused!' : 'I have lost the focus!'}" />
</App>

<App var.focused="{false}" verticalAlignment="center">
  <Switch
    value="true"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
  />
  <Text value="{focused === true ? 'I am focused!' : 'I have lost the focus!'}" />
</App>

lostFocus

This event is triggered when the Switch has lost the focus.

Signature: lostFocus(): void

Exposed Methods

setValue

This API sets the value of the Switch. You can use it to programmatically change the value.

Signature: setValue(value: boolean): void

• value: The new value to set. Can be either true (on) or false (off).

<App var.changes="">
  <Switch
    id="mySwitch"
    readOnly="true"
    label="This switch can be set only programmatically"
    onDidChange="changes += '+'" />
  <HStack>
    <Button
      label="Check"
      onClick="mySwitch.setValue(true)" />
    <Button
      label="Uncheck"
      onClick="mySwitch.setValue(false)" />
  </HStack>
  <Text>The switch is {checkbox.value ? "checked" : "unchecked"}</Text>
  <Text value="Changes: {changes}" />
</App>

<App var.changes="">
  <Switch
    id="mySwitch"
    readOnly="true"
    label="This switch can be set only programmatically"
    onDidChange="changes += '+'" />
  <HStack>
    <Button
      label="Check"
      onClick="mySwitch.setValue(true)" />
    <Button
      label="Uncheck"
      onClick="mySwitch.setValue(false)" />
  </HStack>
  <Text>The switch is {checkbox.value ? "checked" : "unchecked"}</Text>
  <Text value="Changes: {changes}" />
</App>

value

This property holds the current value of the Switch, which can be either "true" (on) or "false" (off).

Signature: get value():boolean

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• input: The switch input area.
• label: The label displayed for the switch.

Styling

Theme Variables