Item Toggle

Example

<vega-item-toggle id="web-item-toggle"></vega-item-toggle>

document.getElementById('web-item-toggle').itemToggleStatusMap = {
    unToggledIcon: 'plus-sign',
    toggledIcon: 'delete-bin',
    unToggledLabel: 'Add',
    togglingLabel: 'Added',
    toggledLabel: 'Remove',
    unTogglingLabel: 'Removed',
};

Note: The above example uses Vanilla JS. If you would like to use React, Angular, or Vue, please consult Storybook.

Usage

The vega-item-toggle is an element which allows adding or removing items from a list. It is generally used in place of a checkbox, when it’s clear that an item should or should not be part of a selection.

In many cases, toggle switches resemble physical switches, such as a light switch, which enables turning an item on and off. However, the vega-item-toggle more explicitly shows text which identifies whether an item is to be added or removed, interspersed with an animation showing a checkmark identifying whether the action has been completed.

Toggle States

The item toggle has the following states:

• Add Item
• Remove Item

Each is interspersed with an animation showing a check mark indicating the action has been completed.

Properties

Sample Javascript

document.getElementById('web-item-toggle').itemToggleStatusMap = {
    unToggledIcon: 'plus-sign',
    toggledIcon: 'delete-bin',
    unToggledLabel: 'Add',
    togglingLabel: 'Added',
    toggledLabel: 'Remove',
    unTogglingLabel: 'Removed',
};

Parameters

<vega-item-toggle
    id="web-item-toggle"
    is-toggled=true|false
>
</vega-item-toggle>

Event

The vegaToggleStatus event is created on vega-item-toggle when it is either turned on or off.

Example:

<vega-item-toggle id="toggle"></vega-item-toggle>


<script>
    const toggle = document.getElementById("toggle");
    toggle.addEventListener("vegaToggleStatus", (e) => { ... })
</script>

For more details, view in Storybook.

Accessibility

• Ensures buttons have discernible text.
• Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds.
• Ensures every id attribute value is unique.
• Ensure that links with the same accessible name serve a similar purpose.
• Ensures links have discernible text.
• Nested interactive controls are not announced by screen readers.

Best Practices

Good places to use a Vega item toggle include the following:

• Adding and/or removing a single item from a shopping cart
• A quick response is required to confirm a set of internal settings without the need to take any specific action.
• If there are quick actions that need to be triggered by the user.
• Toggling of any independent features.
• A single selection is required, with no other actions.

It is not recommended to use toggles in places where checkboxes make more sense, such as:

• Settings need to be confirmed prior to submission.
• Any action which requires submission for it to take place.
• If there are any additional steps the user needs to take for the changes to become effective.
• Multiple choice selections.
• If there’s any chance where the user can confuse the on/off state (however, this is less likely to be a problem with the Vega item-toggle).