FlexToggle Documentation

FlexToggle turns a native checkbox into a toggle while preserving the checkbox's form, keyboard, validation, and change-event behavior.

Markup

<input type="checkbox"
       id="email-notifications"
       name="emailNotifications"
       class="flextoggle"
       data-label-text="Email notifications"
       data-label-position="right" />

FlexToggle initializes all input[type=checkbox].flextoggle elements when the DOM is ready. Calling FlexToggle.initialize() again is safe; an existing element is not initialized twice.

Data attributes

Attribute	Values	Description
class	flextoggle	Required. The class that turns a native checkbox into a FlexToggle.
data-color-on	CSS color	Default: `#2196F3`. Track color when the checkbox is checked.
data-color-off	CSS color	Default: `#ccc`. Track color when the checkbox is unchecked.
data-label-text	Text	Default: empty. The visible label text. The text is part of the native checkbox label and is clickable.
data-label-position	left \| right	Default: `left`. Position of the visible label relative to the toggle.
data-shape	round \| rect	Default: `round`. Rounded or square track and thumb.
data-width	Positive number \| auto	Effective default: `48` px. If only width is supplied, height is half the width.
data-height	Positive number \| auto	Effective default: `24` px. If only height is supplied, width is twice the height.

Width must be greater than height. Dimension values may be numbers, numeric strings, or pixel values such as 48px. Invalid dimensions, colors, shapes, label positions, and non-checkbox elements throw a descriptive error.

Native checkbox attributes

Native attributes such as id, name, value, checked, disabled, and required remain on the original checkbox and continue to work normally. A native form reset immediately restores both the checkbox and the visual toggle state.

Global configuration

FlexToggle.configure({
    colorOn: "#4CAF50",
    height: 28,
    width: 56,
    label: {
        position: "right"
    }
});

Call configure() before initialization to change defaults for subsequently initialized toggles. Nested label configuration is merged with the existing defaults.

JavaScript API

Initialize an existing checkbox

const element = document.getElementById("email-notifications");
const toggle = FlexToggle.init(element);

init(element) returns the existing instance when the checkbox is already initialized.

Create a checkbox and toggle

const toggle = FlexToggle.create({
    container: document.getElementById("notification-settings"),
    id: "sms-notifications",
    name: "smsNotifications",
    value: "enabled",
    checked: true,
    disabled: false,
    required: false,
    ariaLabel: "SMS notifications",
    width: 56,
    height: 28,
    colorOn: "#4CAF50",
    colorOff: "#ccc",
    shape: "round",
    label: {
        text: "SMS notifications",
        position: "right"
    }
});

container must be a DOM Element and defaults to document.body. create() returns the new FlexToggle instance. If it is called before the body exists, creation is queued and the immediate return value is null.

Instance methods

toggle.check();
toggle.uncheck();
toggle.toggle();

toggle.update({
    checked: true,
    disabled: false,
    colorOn: "rebeccapurple",
    label: {
        text: "Updated label",
        position: "left"
    }
});

const originalCheckbox = toggle.destroy();

check(), uncheck(), and toggle() use the native checkbox click behavior and return the instance.
update(options) updates native state and component configuration without rebuilding the surrounding DOM.
destroy() removes the generated UI, restores the original checkbox position, and returns the checkbox.
FlexToggle.getInstanceById(id) returns the initialized instance with the matching checkbox id.

Accessibility and interaction

The original native checkbox remains focusable and operable with the keyboard.
A visible focus indicator is shown on keyboard focus.
Checked, unchecked, disabled, hover, and reduced-motion states are styled without replacing the checkbox.
The label text and slider both activate the same native checkbox.
Clicks are stopped at the component boundary so the toggle does not activate a clickable parent row or card. Native change events still bubble normally.

Every checkbox must have an accessible name. Use data-label-text, an external <label for="...">, aria-label, or aria-labelledby.