Bootstrap Checkbox Laravel Package

Getting Started

This is a jQuery plugin that replaces native checkboxes with Bootstrap-styled three-state controls (checked / unchecked / indeterminate). There is no Laravel service provider, no config file, and no Composer distribution — you consume it as static assets.

1. Pull the package into your asset pipeline (pin the version, since the last published release was 2019-09-08):

   npm install bootstrap-checkbox --save
   

   Copy bootstrap-checkbox.css and bootstrap-checkbox.js from the package into resources/css / resources/js, or alias them in vite.config.js / webpack.mix.js.
2. Load in the correct order: jQuery → Bootstrap (this targets the Bootstrap 3-era markup/classes) → bootstrap-checkbox.js.
3. Mark up a normal checkbox in Blade and initialize it:

   <input type="checkbox" class="checkbox" name="notifications" value="1" checked>
   

   $('input.checkbox').checkbox();
   

Look first at the README's options/methods/events table — that is the real API surface — and the examples/ folder in the repo. First use case: a settings toggle or "remember me" control where you want a button-like checkbox with custom checked/unchecked/indeterminate icons and labels.

Implementation Patterns

Initialize from a single entry point. Wrap initialization in one module or a small Alpine/vanilla helper so every page uses the same options:

window.initCheckboxes = (root = document) => {
  $(root).find('input.checkbox:not([data-bs-checkbox-init])')
    .attr('data-bs-checkbox-init', '1')
    .checkbox({
      checkedClass: 'fa fa-check',
      uncheckedClass: '',
      onChange: () => {}
    });
};

Read and write state through the plugin, not the DOM. Use $el.checkbox('state') (returns checked / unchecked / indeterminate) and the setter methods (check, uncheck, indeterminate, toggle, enable, disable, destroy). Avoid reading .prop('checked') on the visible widget — reflect state on the underlying input instead.

Wire behavior to callbacks. The plugin's onChange / onChecked / onUnchecked / onIndeterminate options fire more reliably than delegated jQuery events on the generated markup. Use them for dependent-field toggling:

$('#has-company').checkbox({
  onChange: function () {
    const on = $(this).checkbox('state') === 'checked';
    $('#company-name').prop('disabled', !on);
  }
});

Header "select all" pattern. Use the indeterminate state for a table header checkbox: set indeterminate when some rows are selected, checked when all are, unchecked when none. Always recompute it after row-level changes rather than tracking a boolean.

Form integration. Keep the original <input> in the DOM (the plugin hides it; confirm in the inspector that name/value still submit). For Laravel, remember the unchecked-checkbox problem — pair it with a hidden input or use $request->boolean() / the boolean and accepted validation rules.

Lifecycle management. After AJAX/partial reloads or Livewire/Turbo navigation, re-run initCheckboxes(container). Before removing or re-rendering a container, call $el.checkbox('destroy') to avoid orphaned markup and duplicate handlers.

Gotchas and Tips

• Bootstrap version drift. Despite the repo name, the styling assumes Bootstrap 3 markup. Bootstrap 4/5 class changes and CSS variables will require overrides; test visually before trusting it in a BS5 app.
• Unmaintained since 2019. No security or Bootstrap 5 updates. Pin the exact version in package.json and budget for migration to native form-check / form-switch if you upgrade Bootstrap.
• jQuery global required. Load order mistakes (plugin before jQuery, or $ overwritten by another library) produce silent no-ops. Check the console and verify $.fn.checkbox exists.
• Double initialization. Calling .checkbox() on an already-initialized element can nest markup and duplicate events. Guard with a data attribute (as above) or destroy first.
• Indeterminate is display-only. It is not a submittable value; the server sees checked or unchecked. Don't build server logic that expects a third state.
• Disabled vs. validation. The plugin's enable/disable methods and the Bootstrap disabled attribute are separate concepts. Server-rendered validation errors won't naturally target the generated widget — add error styling to the wrapper yourself.
• Accessibility. The generated control may not expose a proper role/aria-checked and may not be keyboard-operable in all themes. Add aria-label, test with keyboard and a screen reader, and keep the native input as the accessible source of truth where possible.
• Debugging. Inspect the DOM after init to see exactly which element carries name/value and which classes the plugin applies; most "state won't save" bugs are a mismatch between the widget and the hidden input.
• Extension points. Custom icons/labels via checkedIcon, uncheckedIcon, indeterminateIcon, checkedLabel, etc., and per-instance option overrides are the cleanest customization route — avoid patching the distributed CSS/JS, or your next package update will overwrite it.