Switch

Use a Switch when you want a user to easily toggle between two mutually exclusive options, like 'on' and 'off' typically for settings or preferences within an application.

Usage

import { registerSwitch } from '@vonage/vivid-api';

registerSwitch('your-prefix');

Name and Value

Use the name and value attribute when including the Switch as part of a form.

<script setup lang="ts">
import { VSwitch, VLayout, VButton } from '@vonage/vivid-api-vue';
import { ref } from 'vue';

const results = ref('');

const handleSubmit = (event: Event) => {
  event.preventDefault();
  const form = event.target as HTMLFormElement;
  const formData = new FormData(form);
  results.value = `
      email: ${formData.get('email')}<br />
      text: ${formData.get('text')}<br />
      phone: ${formData.get('phone')}
    `;
};
</script>

<template>
  <VLayout column-basis="small">
    <form @submit="handleSubmit">
      <VLayout row-spacing="small" column-basis="block">
        <div>Marketing settings</div>
        <VSwitch value="yes" name="email" label="Email notifications" />
        <VSwitch value="yes" name="text" label="Text messages" />
        <VSwitch value="yes" name="phone" label="Phone calls" />
        <div>
          <VButton type="submit" label="Submit" appearance="filled" connotation="cta" />
        </div>
      </VLayout>
    </form>
    <div>Form Results:<br /><code v-html="results"></code></div>
  </VLayout>
</template>

<vwc-layout column-basis="small">
  <form id="settings">
    <vwc-layout row-spacing="small" column-basis="block">
      <div>Marketing settings</div>
      <vwc-switch value="yes" name="email" label="Email notifications"></vwc-switch>
      <vwc-switch value="yes" name="text" label="Text messages"></vwc-switch>
      <vwc-switch value="yes" name="phone" label="Phone calls"></vwc-switch>
      <div>
        <vwc-button type="submit" label="Submit" appearance="filled" connotation="cta"></vwc-button>
      </div>
    </vwc-layout>
  </form>
  <div>Form Results:<br /><code id="results"></code></div>
</vwc-layout>

<script>
  const results = document.getElementById('results');
  document.getElementById('settings').addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(document.forms.settings);
    results.innerHTML = `
      email: ${formData.get('email')}<br />
      text: ${formData.get('text')}<br />
      phone: ${formData.get('phone')}
    `;
  });
</script>

API Reference

Properties

Property	Type	Description
checked (modelValue)	`boolean`	The current checkedness of the element.
connotation	`'accent' \| 'cta' \| 'success' \| 'alert' \| 'announcement'`	Controls the color of the Switch
defaultChecked	`boolean`	The default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set.
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
initialValue	`string`	The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
label	`string`	Provides the label for the Switch
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
readOnly	`boolean`	When true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly \| readonly HTML attribute for more information.
required	`boolean`	Require the field to be completed prior to form submission.
value	`string`	The current value of the element.

Property	Type	Description
current-checked	`boolean`	The current checkedness of the element.
connotation	`'accent' \| 'cta' \| 'success' \| 'alert' \| 'announcement'`	Controls the color of the Switch
checked	`boolean`	The default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set.
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
value	`string`	The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
label	`string`	Provides the label for the Switch
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
readonly	`boolean`	When true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly \| readonly HTML attribute for more information.
required	`boolean`	Require the field to be completed prior to form submission.
current-value	`string`	The current value of the element.

Events

Name	Type	Description
change	`CustomEvent<undefined>`	Emits a custom change event when the checked state changes

Name	Type	Description
change	`CustomEvent<undefined>`	Emits a custom change event when the checked state changes

Methods

Name	Params	Returns	Description
checkValidity		`boolean`	Return the current validity of the element.
reportValidity		`boolean`	Return the current validity of the element. If false, fires an invalid event at the element.