npm CircleCI npm bundle size (scoped version) Discord npm

Vue 3 Toggle






## Sponsors

## About Vueform Vueform

Vueform is comprehensive **form development framework** for Vue.js. It supercharges and standardizes the entire form building process and takes care of everything from rendering to validation and processing. With our latest tool, the **Drag and Drop Form Builder**, you can allow your developers & non-tech workforce to build the most complex forms without coding. Feature highlights: - integrate Vueform **Drag and Drop Form Builder** into **any application** - save forms in **database** as a JSON - use your **own form elements** with **custom configuration** options - a complete theming and templating system with **Tailwind support** - 25+ form elements with **multi-file uploads**, date pickers and rich text editor - element **nesting** and **repeating** - **50+ validators** with async, dependent and custom rules - **conditional logic** on element & form level - breaking forms into **steps** with **form wizard** - **translating** form content and global i18n support. Vueform Builder

**Learn more:** - Builder: [https://builder.vueform.com](https://builder.vueform.com?cid=toggle) - Framework: [https://vueform.com](https://vueform.com?cid=toggle) ## Other libraries * [@vueform/multiselect](https://github.com/vueform/multiselect) - Vue 3 multiselect component with single select, multiselect and tagging options. * [@vueform/slider](https://github.com/vueform/slider) - Vue 3 slider component with multihandles, tooltips merging and formatting. ## Toggle features * Vue 2 & 3 support * No dependencies * Lightweight (<2 kB gzipped) * 100% coverage * TypeScript support * Accessibility support * ESM support * CSS vars support * Tailwind & utility class support * On / Off labels ## Demo Check out our [demo](https://jsfiddle.net/m2hvw7o8/). ## Installation ``` npm install @vueform/toggle ``` ## Usage with Vue 3 ``` vue ``` ## Using with Vue 2 ``` vue ``` #### Using with < Vue 2.7 Switch to [`<= 2.0.2`](https://github.com/vueform/toggle/tree/2.0.2) to use the Toggle with Vue.js `< 2.7`. ## Support Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](https://github.com/vueform/toggle/issues). ## Basic props | Name | Type | Default | Description | | --- | --- | --- | --- | | **id** | `string` | `toggle` | The `id` attribute of input field. Make sure to customize when using more toggles on a single page. | | **name** | `string` | `toggle` | The `name` attribute of input field. | | **disabled** | `boolean` | `false` | Whether the toggle should be disabled. | | **required** | `boolean` | `false` | Whether the HTML5 required attribute should be used for toggle (using an invisible fake input). | | **falseValue** | `string\|number\|boolean` | `false` | The value when the toggle is `off`. | | **trueValue** | `string\|number\|boolean` | `true` | The value when toggle is `on`. | | **offLabel** | `string` | | The label when toggle is `off`. | | **onLabel** | `string` | | The label when toggle is `on`. | | **aria** | `object` | | An object containing aria attributes to be added for the toggle. | | **labelledby** | `string` | | The `aria-labelledby` attribute. | | **describedby** | `string` | | The `aria-describedby` attribute. | | **classes** | `object` | | An object of class names that gets merged with the default values. Default: `{`
  `container: 'toggle-container',`
  `toggle: 'toggle',`
  `toggleOn: 'toggle-on',`
  `toggleOff: 'toggle-off',`
  `toggleOnDisabled: 'toggle-on-disabled',`
  `toggleOffDisabled: 'toggle-off-disabled',`
  `handle: 'toggle-handle',`
  `handleOn: 'toggle-handle-on',`
  `handleOff: 'toggle-handle-off',`
  `handleOnDisabled: 'toggle-handle-on-disabled',`
  `handleOffDisabled: 'toggle-handle-off-disabled',`
  `label: 'toggle-label',`
`}`.
The default value can be used with `default.css` and style can be customized with [CSS variables](#styling-with-css-vars). Alternatively this can be overridden with utility classes like [Tailwind CSS](#styling-with-tailwind-css). | Vueform ## Events | Event | Attributes | Description | | --- | --- | --- | | **@change** | `value` | Emitted when the toggle changes. | ## Slots | Slot | Attributes | Description | | --- | --- | --- | | **label** | `checked`, `classList` | The label of the toggle element. The `checked` attribute determines whether the toggle is *on* or *off* so you can display the label accordingly. The `classList` contains the resolved class names. | ## Styling with CSS vars The following CSS variables can be used to customize toggle when using `default.css`: ``` css --toggle-width: 3rem; --toggle-height: 1.25rem; --toggle-border: 0.125rem; --toggle-font-size: 0.75rem; --toggle-duration: 150ms; --toggle-bg-on: #10b981; --toggle-bg-off: #e5e7eb; --toggle-bg-on-disabled: #d1d5db; --toggle-bg-off-disabled: #e5e7eb; --toggle-border-on: #10b981; --toggle-border-off: #e5e7eb; --toggle-border-on-disabled: #d1d5db; --toggle-border-off-disabled: #e5e7eb; --toggle-ring-width: 3px; --toggle-ring-color: #10B98130; --toggle-text-on: #ffffff; --toggle-text-off: #374151; --toggle-text-on-disabled: #9ca3af; --toggle-text-off-disabled: #9ca3af; --toggle-handle-enabled: #ffffff; --toggle-handle-disabled: #f3f4f6; ``` Override them globally: ``` css :root { --toggle-bg-on: red; --toggle-border-on: red; } ``` Or on an instance level: ``` vue ``` ``` css .toggle-red { --toggle-bg-on: red; --toggle-border-on: red; } .toggle-blue { --toggle-bg-on: blue; --toggle-border-on: blue; } ``` ## Styling with Tailwind CSS The `Toggle` component accepts a `classes` property which allows to override default class names. When using utility classes you don't need to import `default.css`. Here's a default styling for Tailwind CSS: ``` vue ``` Certain classes has different states which are merged to the base class when the state is active. For example `handle` will be merged with `handleOn` when the toggle is **on** and **not disabled** resulting in the following classes: ```inline-block bg-white w-5 h-5 top-0 rounded-full absolute transition-all left-full transform -translate-x-full``` The same is true for `toggle`. In case you need to override the same type of utility you might use [@neojp/tailwind-important-variant](https://www.npmjs.com/package/@neojp/tailwindcss-important-variant) and use eg. `bg-green-500!`. ## Accessibility By default the `on` and `off` labels are being read by the screenreaders. If you provide the `labelledby` property that will be read instead of the labels. You might also add a `describedby` property to provide further description. ``` vue
Turn this on if you'd like to receive in-app notifications. ``` ## Examples * [Default toggle](#default-toggle) * [Toggle with labels](#toggle-with-labels) * [Toggle with custom values](#toggle-with-custom-values) * [Toggle with custom labels](#toggle-with-custom-labels) ### Default toggle ``` vue ``` [JSFiddle - Example #1](https://jsfiddle.net/m2hvw7o8/) ### Toggle with labels ``` vue ``` [JSFiddle - Example #2](https://jsfiddle.net/m2hvw7o8/) ### Toggle with custom value ``` vue ``` [JSFiddle - Example #3](https://jsfiddle.net/m2hvw7o8/) ### Toggle with custom labels ``` vue ``` [JSFiddle - Example #4](https://jsfiddle.net/m2hvw7o8/) ## License [MIT](https://github.com/vueform/toggle/blob/main/LICENSE.md)