Switch

The Switch component is a user interface element that allows users to toggle between two states: on and off. It consists of a small rectangular or circular button that can be moved left or right to change its state.

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>

indeterminate (default: false)

The true value of this property signals that the component is in an intedeterminate state.

initialValue (default: false)

This property sets the component's initial value.

label

This property sets the label of the component.

This property sets the label of the component.

<App>
  <Switch label="Example label" initialValue="true" />
  <Switch label="Another label" intialValue="false" />
</App>

labelBreak (default: false)

This boolean value indicates if the Switch labels can be split into multiple lines if it would overflow the available label width.

labelPosition (default: "end")

Places the label at the given position of the component.

Available values:

<App>
  <Switch label="Top label" labelPosition="top" initialValue="true" />
  <Switch label="End label" labelPosition="end" initialValue="true" />
  <Switch label="Bottom label" labelPosition="bottom" initialValue="true" />
  <Switch label="Start label" labelPosition="start" initialValue="true" />
</App>

labelWidth

This property sets the width of the Switch.

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>

required

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

didChange

This event is triggered when value of Switch has changed.

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>

gotFocus

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

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>

lostFocus

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

Exposed Methods

setValue

You can use this method to set the component's current value programmatically (true: checked, false: unchecked).

<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

You can query this read-only API property to query the component's current value (true: checked, false: unchecked).

Styling

The Switch component uses these theme variables to customize its appearance:

• backgroundColor-Switch
• borderColor-Switch
• backgroundColor-Switch--disabled
• backgroundColor-indicator-Switch
• backgroundColor-checked-Switch
• backgroundColor-checked-Switch-warning
• backgroundColor-checked-Switch-success
• backgroundColor-checked-Switch-error
• borderColor-checked-Switch
• borderColor-checked-Switch-warning
• borderColor-checked-Switch-success
• borderColor-checked-Switch-error

<Switch padding="1rem" />

Theme Variables