diff --git a/README.md b/README.md index 5132901..883e176 100644 --- a/README.md +++ b/README.md @@ -12,20 +12,23 @@ **Bootstrap 5 Toggle** is a bootstrap plugin/widget that converts checkboxes into toggles. -*** +--- #### Library Distributions -Branch | Bootstrap Support | Last Release ----|---|--- -[bootstrap5-toggle](https://github.com/palcarazm/bootstrap5-toggle) | [![Bootstrap 5](https://img.shields.io/static/v1?label=bootstrap&message=v5.X.X&color=informational&logo=bootstrap&logoColor=white)](https://getbootstrap.com/docs/5.0) | [![Latest release](https://img.shields.io/github/package-json/v/palcarazm/bootstrap5-toggle/master?logo=github)](https://github.com/palcarazm/bootstrap5-toggle/releases) -[bootstrap5-toggle v3.X.X](https://github.com/palcarazm/bootstrap5-toggle/tree/v3.X.X) | [![Bootstrap 4](https://img.shields.io/static/v1?label=bootstrap&message=v4.X.X&color=informational&logo=bootstrap&logoColor=white)](https://getbootstrap.com/docs/4.0) | [![Latest release](https://img.shields.io/github/package-json/v/palcarazm/bootstrap5-toggle/v3.X.X?logo=github)](https://github.com/palcarazm/bootstrap5-toggle/releases) + +| Branch | Bootstrap Support | Last Release | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [bootstrap5-toggle](https://github.com/palcarazm/bootstrap5-toggle) | [![Bootstrap 5](https://img.shields.io/static/v1?label=bootstrap&message=v5.X.X&color=informational&logo=bootstrap&logoColor=white)](https://getbootstrap.com/docs/5.0) | [![Latest release](https://img.shields.io/github/package-json/v/palcarazm/bootstrap5-toggle/master?logo=github)](https://github.com/palcarazm/bootstrap5-toggle/releases) | +| [bootstrap5-toggle v3.X.X](https://github.com/palcarazm/bootstrap5-toggle/tree/v3.X.X) | [![Bootstrap 4](https://img.shields.io/static/v1?label=bootstrap&message=v4.X.X&color=informational&logo=bootstrap&logoColor=white)](https://getbootstrap.com/docs/4.0) | [![Latest release](https://img.shields.io/github/package-json/v/palcarazm/bootstrap5-toggle/v3.X.X?logo=github)](https://github.com/palcarazm/bootstrap5-toggle/releases) | # Demos -**Demos and API Docs:** https://palcarazm.github.io/bootstrap5-toggle/ + +**Demos and API Docs:** https://palcarazm.github.io/bootstrap5-toggle/ ![Demo GIF](img/bootstrap5-toggle-demo.gif) # Related Bootstrap Puglins +
-*** +--- -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_ - [Installation](#installation) - [CDN](#cdn) @@ -61,56 +65,71 @@ Branch | Bootstrap Support | Last Release -************************************************************************************************** +--- # Installation ## CDN + [![JSDelivr Badge](https://img.shields.io/jsdelivr/npm/hm/bootstrap5-toggle?color=success&label=hits&logo=jsdelivr&logoColor=white)](https://www.jsdelivr.com/package/npm/bootstrap5-toggle) + ### jQuery Interface + ```html - - + + ``` ### ECMAS Interface + ```html - - + + ``` ## Download + [![Latest release](https://img.shields.io/github/package-json/v/palcarazm/bootstrap5-toggle/master?logo=github)](https://github.com/palcarazm/bootstrap5-toggle/releases) ## NPM + [![NPM Badge](https://img.shields.io/npm/dm/bootstrap5-toggle?logo=npm&color=success)](https://www.npmjs.com/package/bootstrap5-toggle) + ```ksh -npm install bootstrap5-toggle +npm install bootstrap5-toggle@4.3.5 ``` ## Yarn + ```ksh -yarn add bootstrap5-toggle +yarn add bootstrap5-toggle@4.3.5 ``` # Usage ## Initialize With HTML + Simply add `data-toggle="toggle"` to automatically convert a plain checkbox into a bootstrap 5 toggle. ```html - + ``` ## Initialize With Code -Toggles can also be initialized via JavaScript code. + +Toggles can also be initialized via JavaScript code. EX: Initialize id `chkToggle` with a single line of JavaScript. + ```html - + ``` @@ -118,130 +137,149 @@ EX: Initialize id `chkToggle` with a single line of JavaScript. # API ## Options -* Options can be passed via data attributes or JavaScript -* For data attributes, append the option name to `data-` (ex: `data-on="Enabled"`) + +- Options can be passed via data attributes or JavaScript +- For data attributes, append the option name to `data-` (ex: `data-on="Enabled"`) ```html - - + + ``` -Name |Type |Default |Description | -----------|-----------|-----------|----------------------------| -`on` |string/html|"On" |Text of the on toggle -`off` |string/html|"Off" |Text of the off toggle -`size` |string |"normal" |Size of the toggle. Possible values are: `large`, `normal`, `small`, `mini`. -`onstyle` |string |"primary" |Style of the on toggle. Possible values are: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark` and with `outline-` prefix -`offstyle`|string |"secondary"|Style of the off toggle. Possible values are: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark` and with `outline-` prefix -`onvalue` |string |*null* |Sets on state value -`offvalue`|string |*null* |Sets off state value -`style` |string | |Appends the value to the class attribute of the toggle. This can be used to apply custom styles. Refer to Custom Styles for reference. -`width` |integer |*null* |Sets the width of the toggle. if set to *null*, width will be auto-calculated. -`height` |integer |*null* |Sets the height of the toggle. if set to *null*, height will be auto-calculated. -`tabindex`|integer |0 |Sets the tabindex of the toggle. -`tristate`|boolean |false |Sets tristate support +| Name | Type | Default | Description | +| ---------- | ----------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `on` | string/html | "On" | Text of the on toggle | +| `off` | string/html | "Off" | Text of the off toggle | +| `size` | string | "normal" | Size of the toggle. Possible values are: `large`, `normal`, `small`, `mini`. | +| `onstyle` | string | "primary" | Style of the on toggle. Possible values are: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark` and with `outline-` prefix | +| `offstyle` | string | "secondary" | Style of the off toggle. Possible values are: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark` and with `outline-` prefix | +| `onvalue` | string | _null_ | Sets on state value | +| `offvalue` | string | _null_ | Sets off state value | +| `style` | string | | Appends the value to the class attribute of the toggle. This can be used to apply custom styles. Refer to Custom Styles for reference. | +| `width` | integer | _null_ | Sets the width of the toggle. if set to _null_, width will be auto-calculated. | +| `height` | integer | _null_ | Sets the height of the toggle. if set to _null_, height will be auto-calculated. | +| `tabindex` | integer | 0 | Sets the tabindex of the toggle. | +| `tristate` | boolean | false | Sets tristate support | ## Methods + Methods can be used to control toggles directly. ```html - + ``` -Method |Example |Description --------------|-----------------------------------------------------|------------------------------------------ -initialize | `$('#toggle-demo').bootstrapToggle()` |Initializes the toggle plugin with options -destroy | `$('#toggle-demo').bootstrapToggle('destroy')` |Destroys the toggle -on | `$('#toggle-demo').bootstrapToggle('on')` |Sets the toggle to 'On' state -off | `$('#toggle-demo').bootstrapToggle('off')` |Sets the toggle to 'Off' state -toggle | `$('#toggle-demo').bootstrapToggle('toggle')` |Toggles the state of the toggle on/off -enable | `$('#toggle-demo').bootstrapToggle('enable')` |Enables the toggle -disable | `$('#toggle-demo').bootstrapToggle('disable')` |Disables the toggle -readonly | `$('#toggle-demo').bootstrapToggle('readonly')` |Disables the toggle but preserve checkbox enabled -indeterminate| `$('#toggle-demo').bootstrapToggle('indeterminate')`|Sets the toggle to 'indeterminate' state -determinate | `$('#toggle-demo').bootstrapToggle('determinate')` |Sets the toggle to 'determinate' state +| Method | Example | Description | +| ------------- | ---------------------------------------------------- | ------------------------------------------------- | +| initialize | `$('#toggle-demo').bootstrapToggle()` | Initializes the toggle plugin with options | +| destroy | `$('#toggle-demo').bootstrapToggle('destroy')` | Destroys the toggle | +| on | `$('#toggle-demo').bootstrapToggle('on')` | Sets the toggle to 'On' state | +| off | `$('#toggle-demo').bootstrapToggle('off')` | Sets the toggle to 'Off' state | +| toggle | `$('#toggle-demo').bootstrapToggle('toggle')` | Toggles the state of the toggle on/off | +| enable | `$('#toggle-demo').bootstrapToggle('enable')` | Enables the toggle | +| disable | `$('#toggle-demo').bootstrapToggle('disable')` | Disables the toggle | +| readonly | `$('#toggle-demo').bootstrapToggle('readonly')` | Disables the toggle but preserve checkbox enabled | +| indeterminate | `$('#toggle-demo').bootstrapToggle('indeterminate')` | Sets the toggle to 'indeterminate' state | +| determinate | `$('#toggle-demo').bootstrapToggle('determinate')` | Sets the toggle to 'determinate' state | # Events ## Event Propagation + Note All events are propagated to and from input element to the toggle. You should listen to events from the `` directly rather than look for custom events. ```html - + ``` ## Stopping Event Propagation + Passing `true` to the on, off, toggle, determinate and indeterminate methods will enable the silent option to prevent the control from propagating the change event in cases where you want to update the controls on/off state, but do not want to fire the onChange event. ```html - - - - - + + + + + ``` ## API vs Input + This also means that using the API or Input to trigger events will work both ways. ```html - - - - - + + + + + ``` + # Collaborators welcom! + - :sos: ¿Do you need some help? Open a issue in [GitHub help wanted](https://github.com/palcarazm/bootstrap5-toggle/issues/new?assignees=&labels=help+wanted&template=help-wanted.md&title=%5BHELP%5D) - - :bug: ¿Do you find a bug? Open a issue in [GitHub bug report](https://github.com/palcarazm/bootstrap5-toggle/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) - - :bulb: ¿Do you have a great idea? Open a issue in [GitHub feature request](https://github.com/palcarazm/bootstrap5-toggle/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D) - - :computer: ¿Do you know how to fix a bug? Open a pull request in [GitHub pull repuest](https://github.com/palcarazm/bootstrap5-toggle/compare). +- :bug: ¿Do you find a bug? Open a issue in [GitHub bug report](https://github.com/palcarazm/bootstrap5-toggle/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) +- :bulb: ¿Do you have a great idea? Open a issue in [GitHub feature request](https://github.com/palcarazm/bootstrap5-toggle/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D) +- :computer: ¿Do you know how to fix a bug? Open a pull request in [GitHub pull repuest](https://github.com/palcarazm/bootstrap5-toggle/compare). [![GitHub Contributors](https://contrib.rocks/image?repo=palcarazm/bootstrap5-toggle)](https://github.com/palcarazm/bootstrap5-toggle/graphs/contributors)