Toggle

Pair framework: Toggle

Pair\Html\FormControls\Toggle renders a switch-like checkbox control. Compared with Checkbox, it is more opinionated in markup because it already includes the wrapper label, the visual track, and the optional inline text.

This makes it especially useful for settings screens, feature flags, and modern forms where the visual language is closer to a switch than to a classic checkbox.

Main methods

Toggle defines:

• suppressLabel(bool $suppress = true): self
• value(bool $value): static
• render(): string

Most other configuration methods come from FormControl:

• label()
• labelClass()
• required()
• disabled()
• readonly()
• id()
• class()
• data()
• aria()
• description()
• validate()

Render structure

The generated markup is intentionally richer than a plain checkbox:

• wrapper <label class="toggle">
• internal <input type="checkbox" value="1">
• <span class="track" aria-hidden="true"></span>
• optional <span class="...">Label</span> unless suppressed

That means Toggle often renders as a self-contained component rather than a field plus a separate external label.

Most-used method: suppressLabel(...)

By default, Toggle prints the inline label text resolved by getLabelText().

If you need an icon-only or visually minimal switch, call suppressLabel().

$darkMode = (new \Pair\Html\FormControls\Toggle('darkMode'))
    // Hide the inline text while keeping the switch markup.
    ->suppressLabel(true)
    ->value(false)
    ->data('setting', 'dark-mode');

Rendering behavior

render():

• computes the checked state from the current boolean value
• always renders the submitted checkbox value as "1"
• wraps the whole control in <label class="toggle">
• prints the checkbox input with value="1"
• prints the visual track span
• prints the inline label span unless label suppression is enabled

Example:

$enabled = (new \Pair\Html\FormControls\Toggle('enabled'))
    // A toggle is a good fit for boolean settings with immediate meaning.
    ->label('Enabled')
    ->value(true);

echo $enabled->render();

Example with a custom label class:

$notifications = (new \Pair\Html\FormControls\Toggle('notifications'))
    ->label('Push notifications')
    // labelClass affects the inline text span rendered by Toggle.
    ->labelClass('toggle-text')
    ->value($user->notifications)
    ->class('js-notification-toggle');

Value contract

Toggle::value(...) accepts only booleans:

• ->value(true) marks the switch as checked
• ->value(false) leaves it unchecked
• ->value(1), ->value(0), ->value('1'), and other non-boolean values throw TypeError

This differs intentionally from the base FormControl contract. A toggle's PHP-side value describes checked state, not the submitted HTML value. The rendered input still submits value="1" when checked.

When Form::fill(...) or Form::values(...) populates a toggle from persisted data, Pair casts stored 0 and 1 values to booleans before calling Toggle::value(...).

Validation behavior

Unlike Checkbox, Toggle does not override validate().

So the current implementation uses the base FormControl::validate() method:

• required() is checked against the submitted POST value
• minLength() and maxLength() are technically available from the base class, although they are rarely useful here

This is an important difference from Checkbox, whose validate() always returns true.

Practical examples

1. Standard boolean preference

$enabled = (new \Pair\Html\FormControls\Toggle('enabled'))
    // Keep the switch synchronized with the current persisted value.
    ->label('Enabled')
    ->value((bool)$record->enabled);

2. Settings toggle with frontend hooks

$autoReply = (new \Pair\Html\FormControls\Toggle('autoReply'))
    ->label('Automatic reply')
    ->value((bool)$account->autoReply)
    // data-* attributes can drive conditional panels or AJAX saves.
    ->data('target', '#auto-reply-settings');

3. Inline toggle without visible text

$darkMode = (new \Pair\Html\FormControls\Toggle('darkMode'))
    ->value((bool)$preferences->darkMode)
    // Suppress the text when another visual label already exists nearby.
    ->suppressLabel();

4. Toggle with explicit id and description

$betaFeature = (new \Pair\Html\FormControls\Toggle('betaFeature'))
    // Explicit ids help when help text or JS targets the switch.
    ->id('beta-feature')
    ->label('Enable beta feature')
    ->description('This setting unlocks experimental UI paths.')
    ->value((bool)$user->betaFeature);

Secondary methods worth knowing

• labelClass(...) Here it affects the inline label span rendered inside the toggle component.
• renderLabel() Usually less useful than on other controls because Toggle already renders its own wrapper label.
• required() Supported through FormControl, unlike the more permissive Checkbox behavior.

Notes

• Toggle requires frontend CSS for classes such as toggle and track to look like a real switch.
• It is visually similar to Checkbox, but validation behavior is different because Toggle uses the base validator.
• Use boolean values when configuring the toggle directly; use Form::fill(...) or Form::values(...) when binding persisted 0/1 state from records.
• If your design already provides a separate external label, suppressLabel() keeps the markup cleaner.

See also: Checkbox, FormControl, Button.