ToggleSwitch

A beautiful switch element

Import

import { ToggleSwitch } from "@schukai/monster/source/components/form/toggle-switch.mjs";

Source

View source code

Package

@schukai/monster

Since

3.57.0

click me!

Introduction

This is a versatile web component. More than just a simple UI element, this component serves as a key element for enhancing interactivity and engagement within various web applications. Whether you are developing a basic website or a complex enterprise-level application, this component is designed to improve user interaction and satisfaction.

Key Features

Dynamic interaction: Users can interact with content dynamically, making the web experience more intuitive and user-centric.
Customizable appearance: Customize the appearance of the component to match the design of your brand or application, ensuring visual consistency.
Accessibility: Designed with accessibility in mind to ensure that all users have a seamless experience, regardless of their browsing environment.
Visual feedback effect: Provides subtle touch feedback to enhance user interaction, making actions more responsive and engaging.
Programmatic Control: Offers methods such as trigger, focus, and deactivate, allowing developers to control the component's behavior programmatically and offering greater flexibility.

Improving the user experience

This component goes beyond its traditional functionality to offer an enhanced and interactive user experience. The combination of visual feedback effects and dynamic interaction with content is not only visually appealing, but also provides clear and responsive feedback to user actions, making the web environment more intuitive and user-friendly.

These improvements are supported by user studies that demonstrate a positive impact on user engagement and satisfaction.

Efficiency in the development process

Integrating this component into your development process is straightforward. Its compatibility with standard web technologies and ease of customization ensure seamless integration with your existing tools and libraries. Whether you're working on a small project or a large-scale application, the modular design of this component guarantees easy integration, streamlining your development process and enhancing productivity.

Simple Example

The Toggle Switch component is a simple way to toggle between two states. It is a stylized version of the native checkbox input.

Javascript

import '@schukai/monster/source/components/form/toggle-switch.mjs';

HTML

<monster-toggle-switch></monster-toggle-switch>

Stylesheet

/** no additional stylesheet is defined **/

Component Design

The ToggleSwitch component is implemented using the Shadow DOM to encapsulate its internal structure and styling. By leveraging the shadow root, the component ensures isolation, protecting its layout and behavior from external styles and scripts while maintaining a clean and modular design.

Shadow DOM and Accessibility

Encapsulation through the Shadow DOM ensures that external interference does not alter the component's internal structure. The component is designed to be accessible, supporting semantic structure, keyboard interaction (e.g., space key to toggle), and assistive technologies. This makes the ToggleSwitch user-friendly for all users.

Customizing Through Exported Parts

The ToggleSwitch exposes specific internal elements using exported parts that developers can style using CSS. This allows targeted customization of the switch without compromising its encapsulation.

Available Part Attributes

control: Represents the container wrapping the entire toggle switch.
switch: Represents the main switch area, which toggles between states.
handle: Represents the sliding handle of the switch.

Below is an example of how to use CSS part attributes to customize the ToggleSwitch component:


monster-toggle-switch::part(control) {
    display: inline-block;
    padding: 5px;
    background-color: #f8f8f8;
    border-radius: 6px;
}

monster-toggle-switch::part(switch) {
    width: 50px;
    height: 24px;
    background-color: #d6d6d6;
    border-radius: 12px;
    position: relative;
    cursor: pointer;
    transition: background-color 0.3s ease;
}

monster-toggle-switch::part(handle) {
    position: absolute;
    top: 2px;
    left: 2px;
    width: 20px;
    height: 20px;
    background-color: #ffffff;
    border-radius: 50%;
    transition: transform 0.3s ease;
}

monster-toggle-switch::part(switch)[data-monster-state="on"] monster-toggle-switch::part(handle) {
    transform: translateX(26px);
}

Explanation of the Example

monster-toggle-switch::part(control): Styles the main container with padding and a background.
monster-toggle-switch::part(switch): Customizes the toggle switch background and dimensions.
monster-toggle-switch::part(switch)[data-monster-state="on"]: Changes the background color when the switch is toggled on.
monster-toggle-switch::part(handle): Styles the sliding handle and animates its position when toggled.

Accessibility

The ToggleSwitch component is accessible via keyboard navigation, allowing users to toggle the switch using the Space key. Screen readers can detect the switch's state, providing appropriate feedback. The aria-disabled attribute is automatically managed when the switch is disabled, ensuring compliance with accessibility standards.

HTML Structure

<monster-toggle-switch></monster-toggle-switch>

JavaScript Initialization

const element = document.createElement('monster-toggle-switch');
document.body.appendChild(element);

Exported

ToggleSwitch

Derived from

CustomControl

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomControl.

Option

Type

Default

Description

value

string

current

lement

disabled

boolean

false

Disabled state

object

classes

classes.on

string

monster-theme-on

specifies the class for the on state.

classes.off

string

monster-theme-off

specifies the class for the off state.

object

values

values.off

string

off

specifies the value of the element if it is not selected

object

labels

labels.on

string

undefined

specifies the label for the on state.

labels.off

string

undefined

specifies the label for the off state.

string

actions

actions.on

string

undefined

specifies the action for the on state.

actions.off

string

undefined

specifies the action for the off state.

object

templates

templates.main

string

undefined

the main template used by the control.

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomControl.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomControl.

Behavioral methods

toggle()

Returns

{ToggleSwitch}

toggle switch on/off ``e = document.querySelector('monster-toggle-switch'); e.toggle()``

toggleOff()

Returns

{ToggleSwitch}

toggle switch off ``e = document.querySelector('monster-toggle-switch'); e.toggleOff()``

toggleOn()

Returns

{ToggleSwitch}

toggle switch on ``e = document.querySelector('monster-toggle-switch'); e.toggleOn()``

State query methods

value()

Returns

{string}

The current value of the Switch ``e = document.querySelector('monster-toggle-switch'); console.log(e.value) // ↦ on``

value(value)

Parameters

value

Set value ``e = document.querySelector('monster-toggle-switch'); e.value="on"``

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

[CSSStyleSheet]

getTag()

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{void}

Other methods

[updaterTransformerMethodsSymbol]()

Returns

{function}

updater transformer methods for pipe

click()

toggle switch ``e = document.querySelector('monster-toggle-switch'); e.click()``

state()

Returns

{string}

returns the status of the element ``e = document.querySelector('monster-toggle-switch'); console.log(e.state) // ↦ off``

Events

The component emits the following events:

monster-options-set
monster-selected
monster-change
monster-changed

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.