Checkbox Input

Renders <input type="checkbox">. A single toggle input that can be checked or unchecked. Default sanitizer: none.

Class: PinkCrab\Form_Components\Element\Field\Input\Checkbox
Make helper: Make::checkbox( 'name', fn(Checkbox $f) => $f->... )

Basic Usage

$this->component( new Input_Component(
		Checkbox::make( 'agree' )
			->label( 'I agree to the terms' )
	) )

Basic

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <label for="agree" class="pc-form__label">I agree to the terms</label>
        <input type="checkbox" name="agree" class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input" />
    </div>

Using Make Helper

use PinkCrab\Form_Components\Util\Make;

$this->component( Make::checkbox( 'agree_terms', fn( $f ) => $f
    ->label( 'I agree to the terms' )
    ->value( 'yes' )
) );

Methods

label( string $label )

Sets the visible label text for the checkbox.

Checkbox::make( 'subscribe' )->label( 'Subscribe to newsletter' )

Generated HTML

<div id="form-field_subscribe" class="pc-form__element pc-form__element--checkbox_input">
    <label for="subscribe" class="pc-form__label">Subscribe to newsletter</label>
    <input type="checkbox" name="subscribe"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
</div>

value( string|float|int $value )

Sets the value submitted when the checkbox is checked. Non-string values are cast to string.

Checkbox::make( 'opt_in' )
			->label( 'Opt in to marketing' )
			->value( 'yes' )
			->checked( true )

value

Generated HTML

<div id="form-field_opt_in" class="pc-form__element pc-form__element--checkbox_input">
    <label for="opt_in" class="pc-form__label">Opt in to marketing</label>
        <input type="checkbox" name="opt_in" class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input" checked="" value="yes" />
    </div>

set_existing( mixed $value )

Sets the current value. No sanitizer is applied by default for checkbox inputs.

Checkbox::make( 'subscribe' )
    ->label( 'Subscribe' )
    ->value( 'yes' )
    ->set_existing( 'yes' )

Generated HTML

<div id="form-field_subscribe" class="pc-form__element pc-form__element--checkbox_input">
    <label for="subscribe" class="pc-form__label">Subscribe</label>
    <input type="checkbox" name="subscribe"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        value="yes"
    />
</div>

checked( bool $checked = true )

Sets whether the checkbox is in a checked state.

Checkbox::make( 'newsletter' )
			->label( 'Subscribe to newsletter' )
			->checked( true )

checked

Generated HTML

<div id="form-field_newsletter" class="pc-form__element pc-form__element--checkbox_input">
    <label for="newsletter" class="pc-form__label">Subscribe to newsletter</label>
        <input type="checkbox" name="newsletter" class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input" checked="" />
    </div>

is_checked()

Returns whether the checkbox is currently checked.

$checkbox = Checkbox::make( 'opt_in' )
    ->checked( true );

$checkbox->is_checked(); // true

Generated HTML

<div id="form-field_opt_in" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="opt_in"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        checked=""
    />
</div>

disabled( bool $disabled = true )

Disables the checkbox. It is visible but cannot be toggled or submitted.

Checkbox::make( 'mandatory' )
			->label( 'Mandatory option' )
			->checked( true )
			->disabled( true )

disabled

Generated HTML

<div id="form-field_mandatory" class="pc-form__element pc-form__element--checkbox_input">
    <label for="mandatory" class="pc-form__label">Mandatory option</label>
        <input type="checkbox" name="mandatory" class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input" checked="" disabled="" />
    </div>

error_notification( string $message )

Displays an error message below the field.

Checkbox::make( 'confirm' )
			->label( 'Confirm your choice' )
			->warning_notification( 'Please confirm to continue.' )

error_notification

Generated HTML

<div id="form-field_confirm" class="pc-form__element pc-form__element--checkbox_input pc-form__element pc-form__element--checkbox_input notification-warning">
    <label for="confirm" class="pc-form__label">Confirm your choice</label>
        <input type="checkbox" name="confirm" class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input pc-form__element__field pc-form__element__field--checkbox_input notification-warning" />
        <div class="pc-form__notification pc-form__notification--warning">Please confirm to continue.</div>
        </div>

warning_notification( string $message )

Displays a warning message below the field.

Checkbox::make( 'data_sharing' )
    ->label( 'Share my data' )
    ->warning_notification( 'Your data will be shared with partners.' )

Generated HTML

<div id="form-field_data_sharing" class="pc-form__element pc-form__element--checkbox_input notification-warning">
    <label for="data_sharing" class="pc-form__label">Share my data</label>
    <input type="checkbox" name="data_sharing"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input notification-warning"
    />
    <div class="pc-form__notification pc-form__notification--warning">Your data will be shared with partners.</div>
</div>

success_notification( string $message )

Displays a success message below the field.

Checkbox::make( 'verified' )
    ->label( 'Email Verified' )
    ->checked( true )
    ->success_notification( 'Your email has been verified.' )

Generated HTML

<div id="form-field_verified" class="pc-form__element pc-form__element--checkbox_input notification-success">
    <label for="verified" class="pc-form__label">Email Verified</label>
    <input type="checkbox" name="verified"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input notification-success"
        checked=""
    />
    <div class="pc-form__notification pc-form__notification--success">Your email has been verified.</div>
</div>

info_notification( string $message )

Displays an info message below the field.

Checkbox::make( 'optional' )
    ->label( 'Enable notifications' )
    ->info_notification( 'You can change this later in settings.' )

Generated HTML

<div id="form-field_optional" class="pc-form__element pc-form__element--checkbox_input notification-info">
    <label for="optional" class="pc-form__label">Enable notifications</label>
    <input type="checkbox" name="optional"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input notification-info"
    />
    <div class="pc-form__notification pc-form__notification--info">You can change this later in settings.</div>
</div>

pre_description( string $description )

Sets a description or hint displayed before the input.

Checkbox::make( 'agree' )
    ->label( 'I agree to the terms' )
    ->pre_description( 'Please review the terms before agreeing.' )

post_description( string $description )

Sets a description or help text displayed after the input, before any notification.

Checkbox::make( 'agree' )
    ->label( 'I agree to the terms' )
    ->post_description( 'You can withdraw consent at any time.' )

before( string $html ) / after( string $html )

HTML content before or after the input within the wrapper.

Checkbox::make( 'agree' )
    ->label( 'I agree' )
    ->before( '<span>Please review the terms</span>' )
    ->after( '<span>Required</span>' )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <span>Please review the terms</span>
    <label for="agree" class="pc-form__label">I agree</label>
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
    <span>Required</span>
</div>

id( string $id )

Sets a custom HTML id on the input element.

Checkbox::make( 'agree' )->id( 'terms-checkbox' )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree" id="terms-checkbox"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
</div>

wrapper_id( string $id )

Sets a custom HTML id on the wrapper div.

Checkbox::make( 'agree' )->wrapper_id( 'terms-wrapper' )

Generated HTML

<div id="terms-wrapper" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
</div>

data( string $key, string $value )

Adds a data-* attribute to the input.

Checkbox::make( 'feature' )->data( 'toggle', 'section-advanced' )

Generated HTML

<div id="form-field_feature" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="feature"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        data-toggle="section-advanced"
    />
</div>

wrapper_data( string $key, string $value )

Adds a data-* attribute to the wrapper div.

Checkbox::make( 'feature' )->wrapper_data( 'group', 'preferences' )

Generated HTML

<div id="form-field_feature" class="pc-form__element pc-form__element--checkbox_input" data-group="preferences">
    <input type="checkbox" name="feature"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
</div>

add_class( string $class )

Adds a CSS class to the input element.

Checkbox::make( 'agree' )->add_class( 'terms-checkbox' )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input terms-checkbox"
    />
</div>

add_wrapper_class( string $class )

Adds a CSS class to the wrapper div.

Checkbox::make( 'agree' )->add_wrapper_class( 'checkbox-field' )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input checkbox-field">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
    />
</div>

show_wrapper( bool $show = true )

Controls whether the wrapping <div> is rendered.

Checkbox::make( 'inline' )->show_wrapper( false )

Generated HTML

<input type="checkbox" name="inline"
    class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
/>

tabindex( int $index )

Sets the tab order of the input.

Checkbox::make( 'agree' )->tabindex( 2 )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        tabindex="2"
    />
</div>

attribute( string $key, mixed $value )

Sets an arbitrary HTML attribute on the input.

Checkbox::make( 'agree' )->attribute( 'aria-describedby', 'terms-description' )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        aria-describedby="terms-description"
    />
</div>

attributes( array $attrs )

Sets multiple arbitrary HTML attributes at once.

Checkbox::make( 'agree' )->attributes( array(
    'title'    => 'Accept terms and conditions',
    'tabindex' => '1',
) )

Generated HTML

<div id="form-field_agree" class="pc-form__element pc-form__element--checkbox_input">
    <input type="checkbox" name="agree"
        class="form-control checkbox-input pc-form__element__field pc-form__element__field--checkbox_input"
        title="Accept terms and conditions" tabindex="1"
    />
</div>

sanitizer( callable $fn )

Sets a sanitization callback applied when set_existing() is called. Default: none.

Using a built-in helper:

use PinkCrab\Form_Components\Util\Sanitize;

Checkbox::make( 'agree' )
    ->sanitizer( Sanitize::TEXT )
    ->set_existing( 'yes' )

Using a custom callable:

Checkbox::make( 'agree' )
    ->sanitizer( function( $value ) {
        return $value === 'yes' ? 'yes' : 'no';
    } )
    ->set_existing( 'yes' )

Built-in sanitizer helpers:

Constant	Function	Description
`Sanitize::TEXT`	`sanitize_text_field()`	Strips tags, removes extra whitespace
`Sanitize::TEXTAREA`	`sanitize_textarea_field()`	Like TEXT but preserves line breaks
`Sanitize::URL`	`esc_url_raw()`	Sanitises a URL for database storage
`Sanitize::EMAIL`	`sanitize_email()`	Strips invalid email characters
`Sanitize::HEX_COLOR`	`sanitize_hex_color()`	Validates hex colour (#fff or #ffffff)
`Sanitize::NUMBER`	Custom numeric parser	Parses to int or float
`Sanitize::NOOP`	Pass-through	No sanitization applied

validator( Validator $validator )

Sets a Respect\Validation validator for server-side validation.

use Respect\Validation\Validator as v;

Checkbox::make( 'agree' )->validator( v::in( array( 'yes', 'no' ) ) )

style( Style $style )

Sets a custom style for the field, overriding the default.

use PinkCrab\Form_Components\Style\Default_Style;

Checkbox::make( 'agree' )->style( new Default_Style() )

Traits

Trait	Methods
Label	`label()`, `get_label()`, `has_label()`
Single_Value	`value()`, `get_value()`, `has_value()`
Checked	`checked()`, `is_checked()`
Disabled	`disabled()`, `is_disabled()`
Description	`pre_description()`, `post_description()`, `get_pre_description()`, `get_post_description()`, `has_pre_description()`, `has_post_description()`
Notification	`error_notification()`, `warning_notification()`, `success_notification()`, `info_notification()`
Form_Style	`style()`, `get_style()`, `has_explicit_style()`