Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@palcarazm
palcarazm committed Nov 23, 2022
1 parent c7250b3 commit 713fc53
Showing 1 changed file with 121 additions and 83 deletions.
204 changes: 121 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,33 +12,37 @@

**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

<div align="center">
<a href="https://github.com/palcarazm/bs-darkmode" title="Boostrap Darkmode"
><img
src="https://github-readme-stats.vercel.app/api/pin/?username=palcarazm&repo=bs-darkmode&border_radius=10&show_owner=true"
/></a>
</div>

***
---

<!-- To update TOC run .\node_modules\.bin\doctoc README.md --github -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**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)
Expand All @@ -61,187 +65,221 @@ Branch | Bootstrap Support | Last Release

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

**************************************************************************************************
---

# 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
<link href="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.2/css/bootstrap5-toggle.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.2/js/bootstrap5-toggle.min.js"></script>
<link
href="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.5/css/bootstrap5-toggle.min.css"
rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.5/js/bootstrap5-toggle.min.js"></script>
```

### ECMAS Interface

```html
<link href="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.2/css/bootstrap5-toggle.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.2/js/bootstrap5-toggle.ecmas.min.js"></script>
<link
href="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.5/css/bootstrap5-toggle.min.css"
rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/bootstrap5-toggle@4.3.5/js/bootstrap5-toggle.ecmas.min.js"></script>
```

## 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
<input id="chkToggle" type="checkbox" data-toggle="toggle">
<input id="chkToggle" type="checkbox" data-toggle="toggle" />
```

## 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
<input id="chkToggle" type="checkbox" checked>
<input id="chkToggle" type="checkbox" checked />
<script>
$(function(){
$('#chkToggle').bootstrapToggle();
$(function () {
$("#chkToggle").bootstrapToggle();
});
</script>
```

# 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
<input type="checkbox" data-toggle="toggle" data-on="Enabled" data-off="Disabled">
<input type="checkbox" id="toggle-two">
<input
type="checkbox"
data-toggle="toggle"
data-on="Enabled"
data-off="Disabled" />
<input type="checkbox" id="toggle-two" />
<script>
$(function() {
$('#toggle-two').bootstrapToggle({
on: 'Enabled',
off: 'Disabled'
$(function () {
$("#toggle-two").bootstrapToggle({
on: "Enabled",
off: "Disabled",
});
})
});
</script>
```

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
<input id="toggle-demo" type="checkbox" data-toggle="toggle">
<input id="toggle-demo" type="checkbox" data-toggle="toggle" />
```

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 `<input type="checkbox">` directly rather than look for custom events.

```html
<input id="toggle-event" type="checkbox" data-toggle="toggle">
<input id="toggle-event" type="checkbox" data-toggle="toggle" />
<div id="console-event"></div>
<script>
$(function() {
$('#toggle-event').change(function() {
$('#console-event').html('Toggle: ' + $(this).prop('checked'))
})
})
$(function () {
$("#toggle-event").change(function () {
$("#console-event").html("Toggle: " + $(this).prop("checked"));
});
});
</script>
```

## 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
<input id="toggle-silent" type="checkbox" data-toggle="toggle">
<button class="btn btn-success" onclick="toggleApiOnSilent()" >On by API (silent)</button>
<button class="btn btn-success" onclick="toggleApiOffSilent()">Off by API (silent)</button>
<button class="btn btn-warning" onclick="toggleApiOnNotSilent()">On by API (not silent)</button>
<button class="btn btn-warning" onclick="toggleApiOffNotSilent()">On by API (not silent)</button>
<input id="toggle-silent" type="checkbox" data-toggle="toggle" />
<button class="btn btn-success" onclick="toggleApiOnSilent()">
On by API (silent)
</button>
<button class="btn btn-success" onclick="toggleApiOffSilent()">
Off by API (silent)
</button>
<button class="btn btn-warning" onclick="toggleApiOnNotSilent()">
On by API (not silent)
</button>
<button class="btn btn-warning" onclick="toggleApiOffNotSilent()">
On by API (not silent)
</button>
<script>
function toggleApiOnSilent() {
$('#toggle-silent').bootstrapToggle('on', true);
$("#toggle-silent").bootstrapToggle("on", true);
}
function toggleApiOffSilent() {
$('#toggle-silent').bootstrapToggle('off', true);
$("#toggle-silent").bootstrapToggle("off", true);
}
function toggleApiOnNotSilent() {
$('#toggle-silent').bootstrapToggle('on');
$("#toggle-silent").bootstrapToggle("on");
}
function toggleApiOffNotSilent() {
$('#toggle-silent').bootstrapToggle('off');
$("#toggle-silent").bootstrapToggle("off");
}
</script>
```

## API vs Input

This also means that using the API or Input to trigger events will work both ways.

```html
<input id="toggle-trigger" type="checkbox" data-toggle="toggle">
<button class="btn btn-success" onclick="toggleApiOn()" >On by API</button>
<button class="btn btn-danger" onclick="toggleApiOff()">Off by API</button>
<button class="btn btn-success" onclick="toggleInpOn()" >On by Input</button>
<button class="btn btn-danger" onclick="toggleInpOff()">Off by Input</button>
<input id="toggle-trigger" type="checkbox" data-toggle="toggle" />
<button class="btn btn-success" onclick="toggleApiOn()">On by API</button>
<button class="btn btn-danger" onclick="toggleApiOff()">Off by API</button>
<button class="btn btn-success" onclick="toggleInpOn()">On by Input</button>
<button class="btn btn-danger" onclick="toggleInpOff()">Off by Input</button>
<script>
function toggleApiOn() {
$('#toggle-trigger').bootstrapToggle('on')
$("#toggle-trigger").bootstrapToggle("on");
}
function toggleApiOff() {
$('#toggle-trigger').bootstrapToggle('off')
$("#toggle-trigger").bootstrapToggle("off");
}
function toggleInpOn() {
$('#toggle-trigger').prop('checked', true).change()
$("#toggle-trigger").prop("checked", true).change();
}
function toggleInpOff() {
$('#toggle-trigger').prop('checked', false).change()
$("#toggle-trigger").prop("checked", false).change();
}
</script>
```

# 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)

Expand Down

0 comments on commit 713fc53

Please sign in to comment.