2.0 release

Author: adamberecz

CHANGELOG.md

@@ -1,4 +1,11 @@
-## v1.1.0
+## v2.0.0
+
+> `2021-06-03`
+
+### 🎉 Features
+  - **BREAKING:** Removed `width`, `height`, `speed`, `colors`, `fontSize` properties and `off`, `on` slots.
+  - **BREAKING:** Completely updated `default` style and classnames.
+  - Added `required`, `classes`, `labelledby`, `describedby` properties and `label` slot.
 
 > `2021-01-06`
 

README.md

@@ -21,7 +21,7 @@
     <img alt="npm" src="https://img.shields.io/npm/v/@vueform/toggle">
   </a>
 
-  <h1>Vue 3 Toggle</h1>
+  <h1>Vue 3 Toggle with Tailwind support</h1>
 
   <a href="https://vueform.com?ref=github" target="_blank">
     <br>
@@ -53,17 +53,19 @@
 ## Toggle features
 
 * Vue 2 & 3 support
+* Tailwind & utility class support
 * No dependencies
 * Lightweight (<2 kB gzipped)
 * 100% coverage
+* TypeScript support
+* Accessibility support
 * ESM support
-* Fully configurable
-* Dynamic styles
+* Configrable styles via CSS vars
 * On / Off labels
 
 ## Demo 
 
-Check out our [demo](https://jsfiddle.net/quc03rf4/).
+Check out our [demo](https://jsfiddle.net/4ckev9rx/).
 
 ## Installation
 
@@ -145,6 +147,102 @@ After that make sure to change the imported module to Vue 2 version of Toggle, a
 import Toggle from '@vueform/toggle/dist/toggle.vue2.js'
 ```
 
+## Styling with CSS vars
+
+The following CSS variables can be used to customize the toggle button when using `default.css`:
+``` CSS
+var(--toggle-width, 3rem);
+var(--toggle-height, 1.25rem);
+var(--toggle-border, 0.125rem) solid;
+var(--toggle-font-size, 0.75rem);
+var(--toggle-duration, 150ms);
+var(--toggle-bg-on, #10b981);
+var(--toggle-bg-off, #e5e7eb);
+var(--toggle-bg-on-disabled, #d1d5db);
+var(--toggle-bg-off-disabled, #e5e7eb);
+var(--toggle-border-on, #10b981);
+var(--toggle-border-off, #e5e7eb);
+var(--toggle-border-on-disabled, #d1d5db);
+var(--toggle-border-off-disabled, #e5e7eb);
+var(--toggle-text-on, #ffffff);
+var(--toggle-text-off, #374151);
+var(--toggle-text-on-disabled, #9ca3af);
+var(--toggle-text-off-disabled, #9ca3af);
+var(--toggle-handle-enabled, #ffffff);
+var(--toggle-handle-disabled, #f3f4f6);
+```
+
+You might override them globally:
+
+``` css
+:root {
+  --toggle-bg-on: red;
+  --toggle-border-on: red;
+}
+```
+
+Or on an instance level:
+
+``` vue
+<Toggle v-model="value" class="my-toggle-red" />
+<Toggle v-model="value" class="my-toggle-blue" />
+```
+
+``` css
+.my-toggle-red {
+  --toggle-bg-on: red;
+  --toggle-border-on: red;
+}
+
+.my-toggle-blue {
+  --toggle-bg-on: blue;
+  --toggle-border-on: blue;
+}
+```
+
+## Styling with Tailwind CSS
+
+The `Toggle` component accepts a `classes` property where you can override default class names. In this case you don't need to required `default.css`. Here's a default styling for Tailwind CSS:
+
+``` vue
+<Toggle v-model="value" :classes="{
+  container: 'inline-block',
+  toggle: 'flex w-12 h-5 rounded-full relative cursor-pointer transition items-center box-content border-2 text-xs leading-none',
+  toggleOn: 'bg-green-500 border-green-500 justify-start text-white',
+  toggleOff: 'bg-gray-200 border-gray-200 justify-end text-gray-700',
+  toggleOnDisabled: 'bg-gray-300 border-gray-300 justify-start text-gray-400 cursor-not-allowed',
+  toggleOffDisabled: 'bg-gray-200 border-gray-200 justify-end text-gray-400 cursor-not-allowed',
+  handle: 'inline-block bg-white w-5 h-5 top-0 rounded-full absolute transition-all',
+  handleOn: 'left-full transform -translate-x-full',
+  handleOff: 'left-0',
+  handleOnDisabled: 'bg-gray-100 left-full transform -translate-x-full',
+  handleOffDisabled: 'bg-gray-100 left-0',
+  label: 'text-center w-8 border-box whitespace-nowrap select-none',
+}" />
+```
+
+If the button is **enabled** and **on** the `toggle` and `toggleOn` classes will be added to the toggle div:
+ ```flex w-12 h-5 rounded-full relative cursor-pointer transition items-center box-content border-2 text-xs leading-none bg-green-500 border-green-500 justify-start text-white```
+
+Likewise if the the button is **disabled** and **on** the `toggle` and `toggleOnDisabled` classes will be added:
+ ```flex w-12 h-5 rounded-full relative cursor-pointer transition items-center box-content border-2 text-xs leading-none bg-gray-300 border-gray-300 justify-start text-gray-400 cursor-not-allowed```
+
+The same is true `off` states and `handle`.
+
+This way you can customize the parts of the toggle button without having to worry about over-riding the same type of utility classes, like backgrounds or text colors.
+
+## 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
+<div>
+  <label id="toggle-label">Turn on notifications</label>
+  <Toggle v-model="value" labelledby="toggle-label" describedby="toggle-description" />
+</div>
+<small id="toggle-description">Turn this on if you'd like to receive in-app notifications.</small>
+```
+
 ## Support
 
 Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](https://github.com/vueform/toggle/issues).
@@ -156,15 +254,14 @@ Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](htt
 | **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`. |
-| **width** | `number` | `54` | The width of the toggle in `px`. |
-| **height** | `number` | `24` | The height of the toggle in `px`. |
-| **speed** | `number` | `300` | The speed of toggle switch in `milliseconds`. |
-| **colors** | `object` |  | The colors of toggle. Default:<br/>`{`<br/>&nbsp;&nbsp;`background: {`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`on: '#41b883',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`off: '#d4e0e7',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`disabled: '#d4e0e7'`<br/>&nbsp;&nbsp;`},`<br/>&nbsp;&nbsp;`text: {`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`on: '#ffffff',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`off: '#80878c',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`disabled: '#80878c'`<br/>&nbsp;&nbsp;`},`<br/>&nbsp;&nbsp;`handle: {`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`on: '#ffffff',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`off: '#ffffff',`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`disabled: '#f2faff'`<br/>&nbsp;&nbsp;`}` |
-| **fontSize** | `string` | `13px` | The font size of toggle labels. |
+| **labelledby** | `string` | | The `aria-labelledby` attribute. |
+| **describedby** | `string` | | The `aria-describedby` attribute. |
+| **classes** | `object` | | The object of classes to be applied for different parts of the toggle. Default: `{`<br>&nbsp;&nbsp;`container: 'toggle-container',`<br>&nbsp;&nbsp;`toggle: 'toggle',`<br>&nbsp;&nbsp;`toggleOn: 'toggle-on',`<br>&nbsp;&nbsp;`toggleOff: 'toggle-off',`<br>&nbsp;&nbsp;`toggleOnDisabled: 'toggle-on-disabled',`<br>&nbsp;&nbsp;`toggleOffDisabled: 'toggle-off-disabled',`<br>&nbsp;&nbsp;`handle: 'toggle-handle',`<br>&nbsp;&nbsp;`handleOn: 'toggle-handle-on',`<br>&nbsp;&nbsp;`handleOff: 'toggle-handle-off',`<br>&nbsp;&nbsp;`handleOnDisabled: 'toggle-handle-on-disabled',`<br>&nbsp;&nbsp;`handleOffDisabled: 'toggle-handle-off-disabled',`<br>&nbsp;&nbsp;`label: 'toggle-label',`<br>`}`.<br> 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). |
 
 ## Events
 
@@ -174,17 +271,16 @@ Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](htt
 
 ## Slots
 
-| Slot |  Description |
-| --- | --- |
-| **off** | Rendered when the toggle is `off` (by default `offLabel`). |
-| **on** | Rendered when the toggle is `on` (by default `onLabel`). |
+| 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. |
 
 ## Examples
 
 * [Default toggle](#default-toggle)
 * [Toggle with labels](#toggle-with-labels)
 * [Toggle with custom values](#toggle-with-custom-values)
-* [Toggle with custom styles](#toggle-with-custom-styles)
+* [Toggle with custom labels](#toggle-with-custom-labels)
 
 ### Default toggle
 
@@ -194,53 +290,45 @@ Join our [Discord channel](https://discord.gg/WhX2nG6GTQ) or [open an issue](htt
 />
 ```
 
-[JSFiddle - Example #1](https://jsfiddle.net/quc03rf4/)
+[JSFiddle - Example #1](https://jsfiddle.net/4ckev9rx/)
 
 ### Toggle with labels
 
 ``` vue
 <Toggle
   v-model="value"
-  id="example2"
   on-label="On"
   off-label="Off"
 />
 ```
 
-[JSFiddle - Example #2](https://jsfiddle.net/quc03rf4/)
+[JSFiddle - Example #2](https://jsfiddle.net/4ckev9rx/)
 
-### Toggle with custom values
+### Toggle with custom value
 
 ``` vue
 <Toggle
   v-model="value"
-  id="example3"
   true-value="on"
   false-value="off"
 />
 ```
 
-[JSFiddle - Example #3](https://jsfiddle.net/quc03rf4/)
+[JSFiddle - Example #3](https://jsfiddle.net/4ckev9rx/)
 
-### Toggle with custom styles
+### Toggle with custom labels
 
 ``` vue
 <Toggle
   v-model="value"
-  id="example4"
-  font-size="15px"
-  :width="80"
-  :height="30"
-  :speed="500"
-  :colors="{
-    background: {
-      on: '#35495e'
-    }
-  }"
-/>
+>
+  <template v-slot:label="{ checked, classList }">
+    <span :class="classList.label">{{ checked ? 'On' : 'Off' }}</span>
+  </template>
+</Toggle>
 ```
 
-[JSFiddle - Example #4](https://jsfiddle.net/quc03rf4/)
+[JSFiddle - Example #4](https://jsfiddle.net/4ckev9rx/)
 
 ## About Vueform