Toggle API

Global API (window.Toggles)

The component exposes a global registry to interact with toggle instances programmatically.

window.Toggles.getAll()

Returns an array of all initialized Toggle class instances on the page.

window.Toggles.findById(id)

Returns the Toggle instance with the matching button ID.

window.Toggles.findByTarget(targetId)

Returns an array of Toggle instances that target the specified element ID.

---

Instance API (Toggle)

Each toggle instance provides properties and methods for state control.

Properties

• id: The unique ID of the toggle (generated if not present on the button).

• button: The HTML button element.

• target: The HTML target element (resolved at runtime).

• isEnabled: Boolean indicating if the toggle is currently active (supports getter and setter).

• config: The parsed configuration object (read-only via getConfig()).

Methods

• enable(): Activates the toggle.

• disable(): Deactivates the toggle.

• toggle(): Flips the current state.

• setEnabled(boolean): Explicitly sets the state.

• updateLabelWidth(): Force recalculation of label widths (if in alternate mode).

• on(eventName, handler): Adds an event listener to the target element.

• off(eventName, handler): Removes an event listener from the target element.

• getConfig(): Returns a copy of the parsed configuration from data attributes.

---

Events

Events are dispatched from the target element. They bubble up and are not cancelable.

Event Name	Detail	Description
toggle:enable	{ id, isEnabled: true }	Fired when the toggle is activated.
toggle:disable	{ id, isEnabled: false }	Fired when the toggle is deactivated.
toggle:change	{ id, isEnabled: boolean }	Fired on any state change.

---

Examples

Programmatic Toggle Control

// Find a toggle by its button ID
const menuToggle = window.Toggles.findById("menu-toggle");

// Open the toggle target
menuToggle.enable();

// Close the toggle target
menuToggle.disable();

// Toggle the current state
menuToggle.toggle();

// Set state explicitly
menuToggle.setEnabled(true);  // Open
menuToggle.setEnabled(false); // Close

// Check current state
if (menuToggle.isEnabled) {
  console.log("Menu is open");
}

// Get all toggle instances
const allToggles = window.Toggles.getAll();
console.log(`Found ${allToggles.length} toggles on the page`);

Finding Toggles by Target

// Find all toggle buttons that control "mobile-menu"
const menuToggles = window.Toggles.findByTarget("mobile-menu");

console.log(`${menuToggles.length} buttons control the mobile menu`);

// Disable all of them (closes the menu)
menuToggles.forEach(toggle => toggle.disable());

// Enable via any of them (opens the menu, all stay synced)
menuToggles[0].enable();

Event Listeners for State Changes

const menuTarget = document.getElementById("mobile-menu");

// Listen for enable (open)
menuTarget.addEventListener("toggle:enable", (e) => {
  console.log(`Toggle ${e.detail.id} opened the menu`);
  
  // Track analytics
  analytics.track("menu_opened");
});

// Listen for disable (close)
menuTarget.addEventListener("toggle:disable", (e) => {
  console.log(`Toggle ${e.detail.id} closed the menu`);
});

// Listen for any state change
menuTarget.addEventListener("toggle:change", (e) => {
  const { id, isEnabled } = e.detail;
  console.log(`Menu is now ${isEnabled ? "open" : "closed"}`);
  
  // Update UI based on state
  document.body.classList.toggle("menu-active", isEnabled);
});

Using Instance Event Methods

const toggle = window.Toggles.findById("menu-toggle");

// Add event listener via instance method (attaches to target element)
function handleChange(e) {
  console.log(`State changed: ${e.detail.isEnabled}`);
}

toggle.on("toggle:change", handleChange);

// Later, remove the listener
toggle.off("toggle:change", handleChange);

Reading Toggle Configuration

const toggle = window.Toggles.findById("menu-toggle");

// Get a copy of the parsed configuration
const config = toggle.getConfig();

console.log(config);
// Output:
// {
//   targetId: "mobile-menu",
//   targetToggledClass: "is-open",
//   freezeScroll: true,
//   labelMode: "alternate",
//   nextFocusId: null,
//   targetIsModal: false
// }

// Access individual config values
if (config.freezeScroll) {
  console.log("This toggle freezes scroll when active");
}

Close All Open Toggles

// Close all active toggles on the page
function closeAllToggles() {
  window.Toggles.getAll()
    .filter(toggle => toggle.isEnabled)
    .forEach(toggle => toggle.disable());
}

// Example: Close all toggles on route change (SPA)
window.addEventListener("popstate", closeAllToggles);

// Example: Close all toggles with Escape (handled automatically, but custom logic)
document.addEventListener("keydown", (e) => {
  if (e.key === "Escape") {
    closeAllToggles();
  }
});