|
1 | | -# bootstrap-switch-button |
2 | | -Bootstrap Switch Button |
| 1 | +[](https://opensource.org/licenses/mit-license.php) [](https://getbootstrap.com/docs/4.1) [](https://snyk.io/test/npm/bootstrap-switch-button) [](https://www.jsdelivr.com/package/gh/gitbrent/bootstrap-switch-button) |
| 2 | + |
| 3 | +# Bootstrap Switch Button |
| 4 | + |
| 5 | +**Bootstrap Switch Button** is a bootstrap plugin/widget that converts checkboxes into toggles. |
| 6 | + |
| 7 | +Visit https://gitbrent.github.io/bootstrap-switch-button/ for interactive demos. |
| 8 | + |
| 9 | +************************************************************************************************** |
| 10 | + |
| 11 | +<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
| 12 | +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 13 | +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* |
| 14 | + |
| 15 | +- [Demos](#demos) |
| 16 | +- [Installation](#installation) |
| 17 | + - [CDN](#cdn) |
| 18 | + - [Download](#download) |
| 19 | + - [NPM](#npm) |
| 20 | + - [Yarn](#yarn) |
| 21 | +- [Usage](#usage) |
| 22 | + - [Initialize With HTML](#initialize-with-html) |
| 23 | + - [Initialize With Code](#initialize-with-code) |
| 24 | +- [API](#api) |
| 25 | + - [Options](#options) |
| 26 | + - [Methods](#methods) |
| 27 | +- [Events](#events) |
| 28 | + - [Event Propagation](#event-propagation) |
| 29 | + - [API vs Input](#api-vs-input) |
| 30 | + |
| 31 | +<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 32 | + |
| 33 | +************************************************************************************************** |
| 34 | + |
| 35 | +# Demos |
| 36 | +Visit https://gitbrent.github.io/bootstrap-switch-button/ for interactive checkbox toggle demos. |
| 37 | + |
| 38 | +# Installation |
| 39 | + |
| 40 | +## CDN |
| 41 | +```html |
| 42 | +<link href="https://cdn.jsdelivr.net/gh/gitbrent/bootstrap-switch-button@1.0.0/css/bootstrap-switch-button.min.css" rel="stylesheet"> |
| 43 | +<script src="https://cdn.jsdelivr.net/gh/gitbrent/bootstrap-switch-button@1.0.0/js/bootstrap-switch-button.min.js"></script> |
| 44 | +``` |
| 45 | + |
| 46 | +## Download |
| 47 | +[Latest GitHub Release](https://github.com/gitbrent/bootstrap-switch-button/releases/latest) |
| 48 | + |
| 49 | +## NPM |
| 50 | +```ksh |
| 51 | +npm install bootstrap-switch-button |
| 52 | +``` |
| 53 | + |
| 54 | +## Yarn |
| 55 | +```ksh |
| 56 | +yarn install bootstrap-switch-button |
| 57 | +``` |
| 58 | + |
| 59 | +# Usage |
| 60 | + |
| 61 | +## Initialize With HTML |
| 62 | +Simply add `data-toggle="toggle"` to automatically convert a plain checkbox into a bootstrap 4 toggle. |
| 63 | + |
| 64 | +```html |
| 65 | +<input id="chkToggle" type="checkbox" data-toggle="toggle"> |
| 66 | +``` |
| 67 | + |
| 68 | +## Initialize With Code |
| 69 | +Toggles can also be initialized via JavaScript code. |
| 70 | + |
| 71 | +EX: Initialize id `chkToggle` with a single line of JavaScript. |
| 72 | +```html |
| 73 | +<input id="chkToggle" type="checkbox" checked> |
| 74 | +<script> |
| 75 | + $(function(){ |
| 76 | + $('#chkToggle').bootstrapToggle(); |
| 77 | + }); |
| 78 | +</script> |
| 79 | +``` |
| 80 | + |
| 81 | +# API |
| 82 | + |
| 83 | +## Options |
| 84 | +* Options can be passed via data attributes or JavaScript |
| 85 | +* For data attributes, append the option name to `data-` (ex: `data-on="Enabled"`) |
| 86 | + |
| 87 | +```html |
| 88 | +<input type="checkbox" data-toggle="toggle" data-on="Enabled" data-off="Disabled"> |
| 89 | +<input type="checkbox" id="toggle-two"> |
| 90 | +<script> |
| 91 | + $(function() { |
| 92 | + $('#toggle-two').bootstrapToggle({ |
| 93 | + on: 'Enabled', |
| 94 | + off: 'Disabled' |
| 95 | + }); |
| 96 | + }) |
| 97 | +</script> |
| 98 | +``` |
| 99 | + |
| 100 | +Name |Type |Default |Description | |
| 101 | +----------|-----------|----------|----------------------------| |
| 102 | +`on` |string/html|"On" |Text of the on toggle |
| 103 | +`off` |string/html|"Off" |Text of the off toggle |
| 104 | +`size` |string |"normal" |Size of the toggle. Possible values are: `large`, `normal`, `small`, `mini`. |
| 105 | +`onstyle` |string |"primary" |Style of the on toggle. Possible values are: `primary`,`secondary`,`success`,`danger`,`warning`,`info`,`light`,`dark` |
| 106 | +`offstyle`|string |"light" |Style of the off toggle. Possible values are: `primary`,`secondary`,`success`,`danger`,`warning`,`info`,`light`,`dark` |
| 107 | +`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. |
| 108 | +`width` |integer |*null* |Sets the width of the toggle. if set to *null*, width will be auto-calculated. |
| 109 | +`height` |integer |*null* |Sets the height of the toggle. if set to *null*, height will be auto-calculated. |
| 110 | + |
| 111 | +## Methods |
| 112 | +Methods can be used to control toggles directly. |
| 113 | + |
| 114 | +```html |
| 115 | +<input id="toggle-demo" type="checkbox" data-toggle="toggle"> |
| 116 | +``` |
| 117 | + |
| 118 | +Method |Example |Description |
| 119 | +-----------|------------------------------------------------|------------------------------------------ |
| 120 | +initialize | `$('#toggle-demo').bootstrapToggle()` |Initializes the toggle plugin with options |
| 121 | +destroy | `$('#toggle-demo').bootstrapToggle('destroy')` |Destroys the toggle |
| 122 | +on | `$('#toggle-demo').bootstrapToggle('on')` |Sets the toggle to 'On' state |
| 123 | +off | `$('#toggle-demo').bootstrapToggle('off')` |Sets the toggle to 'Off' state |
| 124 | +toggle | `$('#toggle-demo').bootstrapToggle('toggle')` |Toggles the state of the toggle on/off |
| 125 | +enable | `$('#toggle-demo').bootstrapToggle('enable')` |Enables the toggle |
| 126 | +disable | `$('#toggle-demo').bootstrapToggle('disable')` |Disables the toggle |
| 127 | + |
| 128 | +# Events |
| 129 | + |
| 130 | +## Event Propagation |
| 131 | +Note All events are propagated to and from input element to the toggle. |
| 132 | + |
| 133 | +You should listen to events from the `<input type="checkbox">` directly rather than look for custom events. |
| 134 | + |
| 135 | +```html |
| 136 | +<input id="toggle-event" type="checkbox" data-toggle="toggle"> |
| 137 | +<div id="console-event"></div> |
| 138 | +<script> |
| 139 | + $(function() { |
| 140 | + $('#toggle-event').change(function() { |
| 141 | + $('#console-event').html('Toggle: ' + $(this).prop('checked')) |
| 142 | + }) |
| 143 | + }) |
| 144 | +</script> |
| 145 | +``` |
| 146 | + |
| 147 | +## API vs Input |
| 148 | +This also means that using the API or Input to trigger events will work both ways. |
| 149 | + |
| 150 | +```html |
| 151 | +<input id="toggle-trigger" type="checkbox" data-toggle="toggle"> |
| 152 | +<button class="btn btn-success" onclick="toggleApiOn()" >On by API</button> |
| 153 | +<button class="btn btn-danger" onclick="toggleApiOff()">Off by API</button> |
| 154 | +<button class="btn btn-success" onclick="toggleInpOn()" >On by Input</button> |
| 155 | +<button class="btn btn-danger" onclick="toggleInpOff()">Off by Input</button> |
| 156 | +<script> |
| 157 | + function toggleApiOn() { |
| 158 | + $('#toggle-trigger').bootstrapToggle('on') |
| 159 | + } |
| 160 | + function toggleApiOff() { |
| 161 | + $('#toggle-trigger').bootstrapToggle('off') |
| 162 | + } |
| 163 | + function toggleInpOn() { |
| 164 | + $('#toggle-trigger').prop('checked', true).change() |
| 165 | + } |
| 166 | + function toggleInpOff() { |
| 167 | + $('#toggle-trigger').prop('checked', false).change() |
| 168 | + } |
| 169 | +</script> |
| 170 | +``` |
0 commit comments