A lightweight Stimulus controller to dynamically toggle the visibility of elements based on the value of user inputs such as dropdowns, checkboxes, and radio buttons. It uses data attributes to define toggle sets and conditions.
- Supports dropdowns, checkboxes, and radio buttons.
- Easily configurable with
data-*attributes. - Handles toggling for grouped or individual elements.
- Supports a11y by toggling
aria-hiddenattribute, settingaria-controlson the toggle controls, as well asaria-expandedwhen necessary.
Install via npm:
npm add stimulus-toggle-kit- Import the controller into your Stimulus setup:
import { Application } from "@hotwired/stimulus";
import ToggleController from "toggle-controller";
const application = Application.start();
application.register("toggle", ToggleController);- Configure your HTML with the required data-* attributes.
Basic example:
<div data-controller="toggle">
<!-- select controller target -->
<select data-toggle-target="select" data-action="toggle#changed">
<option>Select an option</option>
<option value="option1">Option 1</option>
<option value="option2">Option 2</option>
</select>
<!-- checkbox controller target -->
<input type="checkbox" data-toggle-target="checkbox" data-action="toggle#changed" value="option3">
<!-- radio controller target -->
<div data-toggle-target="radio">
<label>
<input type="radio" data-action="toggle#changed" name="option" value="option4">
Option 4
</label>
<label>
<input type="radio" data-action="toggle#changed" name="option" value="option5">
Option 5
</label>
</div>
<!-- element controller targets -->
<div data-toggle-target="element" data-values="option1,option3,option4">
Content for options 1, 3 or 4
</div>
<div data-toggle-target="element" data-values="option2,option5">
Content for options 2 or 5
</div>
</div>More advanced example, using multiple toggle sets:
<div data-controller="toggle">
<!-- set1 controller targets -->
<select data-toggle-target="select" data-action="toggle#changed" data-toggle-set="set1">
<option value="option1">Option 1</option>
<option value="option2">Option 2</option>
</select>
<input type="checkbox" data-toggle-target="checkbox" data-action="toggle#changed" value="option3" data-toggle-set="set1">
<!-- set2 controller targets -->
<select data-toggle-target="select" data-action="toggle#changed" data-toggle-set="set2">
<option value="option4">Option 4</option>
<option value="option5">Option 5</option>
</select>
<input type="checkbox" data-toggle-target="checkbox" data-action="toggle#changed" value="option6" data-toggle-set="set2">
<!-- element controller targets -->
<div data-toggle-target="element" data-values="option1,option3" data-toggle-set="set1">
Content for Option 1 or 3 from set1
</div>
<div data-toggle-target="element" data-values="option2" data-toggle-set="set1">
Content for Option 2 from set1
</div>
<div data-toggle-target="element" data-values="option4,option6" data-toggle-set="set2">
Content for Option 4 or 6 from set2
</div>
<div data-toggle-target="element" data-values="option5" data-toggle-set="set2">
Content for Option 5 from set2
</div>
</div>data-toggle-set(optional)- Specifies the toggle set(s) the element belongs to. Comma-separated for multiple sets.
data-values- Defines the value(s) that should make the element visible. Comma-separated for multiple values.
data-toggle-target- Indicates the target type
element- this will make the element a toggle targetselect- this will make the select element a toggle controlcheckbox- this will make the checkbox element a toggle controlradio- this will make the radio elements within the parent element toggle controls- Please note, all of the radio buttons of the same name should be wrapped in a containing div with the
data-toggle-target="radio"attribute. See example above.
- Please note, all of the radio buttons of the same name should be wrapped in a containing div with the