Forms Documentation

Appearance

Checkbox ​

Basic Usage ​

The Checkbox field renders a single checkbox input. By default, it stores true when checked and false when unchecked.

Example

Receive a summary when review status changes.

php
Checkbox::make('receive_updates')
    ->label('Send project updates')
    ->help('Receive a summary when review status changes.');

Use Checkbox for a single boolean value. For multiple related checkbox options, use CheckboxGroup; for one-of-many choices, use Radio.

Custom Values ​

Use trueValue and falseValue to customize what gets stored when the checkbox is checked or unchecked.

Boolean (default) ​

php
Checkbox::make('is_active')
    ->trueValue(true)
    ->falseValue(false);

String Values ​

Example

Published entries are visible to external reviewers.

php
Checkbox::make('publish_status')
    ->label('Publish this entry')
    ->help('Published entries are visible to external reviewers.')
    ->trueValue('published')
    ->falseValue('draft')
    ->default('published');

Integer Values ​

php
Checkbox::make('enabled')
    ->trueValue(1)
    ->falseValue(0);

The stored values may be strings, numbers, booleans, or null. PHP preserves a model or default value that strictly matches either configured value. Any other value is converted using PHP truthiness, then mapped to trueValue or falseValue. Vue and React also use strict value equality to decide whether the checkbox is checked.

For example, this field writes null when unchecked:

php
Checkbox::make('publish_status')
    ->trueValue('published')
    ->falseValue(null);

Validation ​

Checkbox does not add a boolean or acceptance rule automatically. Add the Laravel rule that matches the stored values. In particular, required() only adds Laravel's required rule; use accepted when the checkbox must be checked:

php
Checkbox::make('terms')
    ->label('I agree to the terms')
    ->rule('accepted');

The required flag is also exposed to the rendered checkbox for accessibility. Package forms use server validation and render with native browser validation disabled.

Validation Key ​

By default, validation errors are shown based on the field's name. You may override which validation key the checkbox listens to for errors:

php
Checkbox::make('agree_to_terms')->validationKey('terms');

Show / Hide Errors ​

By default, validation errors are displayed below the checkbox. You may hide them:

php
Checkbox::make('agree_to_terms')->hideErrors();

Or explicitly show them (this is the default):

php
Checkbox::make('agree_to_terms')->showErrors();

Using the Component Directly ​

You may render Checkbox outside the generated <Form> by passing serialized form.getField(...) props while rendering forms manually, or local state.

vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import { Checkbox } from '@inertiaui/form-vue/components'

type PublishStatus = 'published' | 'draft'

const publishStatus = shallowRef<PublishStatus>('draft')
const trackBlur = () => {}
</script>

<template>
    <Checkbox
        v-model="publishStatus"
        id="publish-status"
        name="publish_status"
        label="Publish this entry"
        help="Published entries are visible to external reviewers."
        true-value="published"
        false-value="draft"
        validation-key="entry.publish_status"
        :show-errors="false"
        required
        precognitive
        invalid
        error="Choose a publish state."
        badge="Workflow"
        badge-class="bg-zinc-100 text-zinc-700"
        label-trailing="Required"
        label-trailing-class="text-zinc-500"
        tooltip="Controls external visibility."
        help-position="below"
        layout="inline"
        control-position="start"
        label-class="font-medium"
        help-class="text-zinc-500"
        error-class="text-red-600"
        wrapper-class="max-w-xl"
        control-class="ring-zinc-300"
        class="shadow-sm"
        data-testid="publish-status"
        aria-label="Publish this entry"
        @blur="trackBlur"
    />
</template>
tsx
import { useState } from 'react'
import { Checkbox } from '@inertiaui/form-react/components'

type PublishStatus = 'published' | 'draft'

export default function PublishStatus() {
    const [publishStatus, setPublishStatus] = useState<PublishStatus>('draft')
    const trackBlur = () => {}

    return (
        <Checkbox
            value={publishStatus}
            onValueChange={(value) => setPublishStatus(value === 'published' ? 'published' : 'draft')}
            id="publish-status"
            name="publish_status"
            label="Publish this entry"
            help="Published entries are visible to external reviewers."
            trueValue="published"
            falseValue="draft"
            validationKey="entry.publish_status"
            showErrors={false}
            required
            precognitive
            invalid
            error="Choose a publish state."
            badge="Workflow"
            badgeClass="bg-zinc-100 text-zinc-700"
            labelTrailing="Required"
            labelTrailingClass="text-zinc-500"
            tooltip="Controls external visibility."
            helpPosition="below"
            layout="inline"
            controlPosition="start"
            labelClass="font-medium"
            helpClass="text-zinc-500"
            errorClass="text-red-600"
            wrapperClass="max-w-xl"
            controlClass="ring-zinc-300"
            class="shadow-sm"
            data-testid="publish-status"
            aria-label="Publish this entry"
            onBlur={trackBlur}
        />
    )
}

Vue uses v-model. React uses controlled value plus onValueChange. Native attributes and listeners target the underlying <input>; see Native Attributes And Events.

Checkbox also inherits the shared validation, conditional visibility, authorization, model binding, form class, and styling APIs for rules, visibility, labels, help text, disabled and required state, layout, and classes.