Checkbox

Enables users to select (or deselect) a single option in response to a question.

Examples

Usage

Use the checkbox component when you need to help users toggle a single option on or off.

Do:

place the checkbox to the left of its label for accessibility
provide a clear, concise label that describes the action or agreement
if needed, provide a short hint below the label to clarify what the checkbox does
keep hint text to a single sentence without full stop
use it to check if the user agrees to something specific, like accepting the terms and conditions or choosing to join a service
position any links to terms and conditions or related content before the checkbox, rather than placing them inside the label

Avoid:

using a single checkbox when the user must choose one option from a list, use radio buttons instead
triggering immediate actions with a checkbox, use a button for that
pre-selecting the checkbox unless there is a strong, user-centred reason
placing links inside checkbox labels, as this can cause usability and accessibility issues, particularly for touchscreen users
placing links in hint text, as screen readers may not announce them properly

Please correct the errors and try again.

Required fields are marked with an asterisk

Checkbox

Checkbox label

Copy


                <turas-checkbox asp-for="Checkbox" checkbox-label="Checkbox label" hide-required-marker heading-label="Checkbox" />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker">Checkbox</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox field is required." id="Checkbox" name="Checkbox" value="true" /><input name="Checkbox" type="hidden" value="false" />
<label class="control-label" for="Checkbox">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="Checkbox" data-valmsg-replace="true"></span>
</fieldset>

Checkbox required

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxRequired" checkbox-label="Checkbox label" />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker  ">Checkbox required</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The checkbox required must be acknowledged" id="CheckboxRequired" name="CheckboxRequired" value="true" /><input name="CheckboxRequired" type="hidden" value="false" />
<label class="control-label" for="CheckboxRequired">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxRequired" data-valmsg-replace="true"></span>
</fieldset>

Checkbox guidance text

I am some guidance text

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxGuidanceText" checkbox-label="Checkbox label" guidance-text="I am some guidance text" hide-required-marker />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox guidance text</legend>
<div class="form-field-guidance-text">I am some guidance text</div>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox guidance text field is required." id="CheckboxGuidanceText" name="CheckboxGuidanceText" value="true" /><input name="CheckboxGuidanceText" type="hidden" value="false" />
<label class="control-label" for="CheckboxGuidanceText">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxGuidanceText" data-valmsg-replace="true"></span>
</fieldset>

Checkbox guidance text accordion

A paragraph.

List item
List item
List item

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxGuidanceTextAccordion" checkbox-label="Checkbox label" hide-required-marker>
                    <turas-form-guidance collapses>
                        <p>A paragraph.</p>
                        <ul>
                            <li>List item</li>
                            <li>List item</li>
                            <li>List item</li>
                        </ul>
                    </turas-form-guidance>
                </turas-checkbox>

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox guidance text accordion</legend>
<div class="turas-form-guidance-collapse">
            <button class="turas-form-guidance-collapse-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapse-14886f6d-a00d-4793-901f-095cbcedef0d" aria-expanded="false" aria-controls="collapse-14886f6d-a00d-4793-901f-095cbcedef0d"><span class="visually-hidden">Guidance</span></button>              
            <div class="turas-form-guidance-collapse-content collapse" id="collapse-14886f6d-a00d-4793-901f-095cbcedef0d">   
                <div class="form-field-guidance-text"><span class=""></span>
                    
                        <p>A paragraph.</p>
                        <ul>
                            <li>List item</li>
                            <li>List item</li>
                            <li>List item</li>
                        </ul>
                       
                </div>
            </div></div>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox guidance text accordion field is required." id="CheckboxGuidanceTextAccordion" name="CheckboxGuidanceTextAccordion" value="true" /><input name="CheckboxGuidanceTextAccordion" type="hidden" value="false" />
<label class="control-label" for="CheckboxGuidanceTextAccordion">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxGuidanceTextAccordion" data-valmsg-replace="true"></span>
</fieldset>

Checkbox additional classes

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxAdditionalClasses" checkbox-label="Checkbox label" hide-required-marker additional-classes="remove-max-width" />

Copy


                <fieldset class="form-group form-single-checkbox remove-max-width"><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox additional classes</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox additional classes field is required." id="CheckboxAdditionalClasses" name="CheckboxAdditionalClasses" value="true" /><input name="CheckboxAdditionalClasses" type="hidden" value="false" />
<label class="control-label" for="CheckboxAdditionalClasses">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxAdditionalClasses" data-valmsg-replace="true"></span>
</fieldset>

Checkbox in a row

Checkbox label

Checkbox in a row

Checkbox label

Copy


                <div class="row">
                    <div class="col-md-6">
                        <turas-checkbox asp-for="CheckboxInARowOne" checkbox-label="Checkbox label" hide-required-marker />
                    </div>
                    <div class="col-md-6">
                        <turas-checkbox asp-for="CheckboxInARowTwo" checkbox-label="Checkbox label" hide-required-marker />
                    </div>
                </div>

Copy


                <div class="row">
                    <div class="col-md-6">
                        <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox in a row</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox in a row field is required." id="CheckboxInARowOne" name="CheckboxInARowOne" value="true" /><input name="CheckboxInARowOne" type="hidden" value="false" />
<label class="control-label" for="CheckboxInARowOne">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxInARowOne" data-valmsg-replace="true"></span>
</fieldset>
                    </div>
                    <div class="col-md-6">
                        <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox in a row</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox in a row field is required." id="CheckboxInARowTwo" name="CheckboxInARowTwo" value="true" /><input name="CheckboxInARowTwo" type="hidden" value="false" />
<label class="control-label" for="CheckboxInARowTwo">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxInARowTwo" data-valmsg-replace="true"></span>
</fieldset>
                    </div>
                </div>

Checkbox in a row required

Checkbox label

Checkbox in a row required

Checkbox label

Copy


                <div class="row">
                    <div class="col-md-6">
                        <turas-checkbox asp-for="CheckboxRequiredInARowOne" checkbox-label="Checkbox label" />
                    </div>
                    <div class="col-md-6">
                        <turas-checkbox asp-for="CheckboxRequiredInARowTwo" checkbox-label="Checkbox label" />
                    </div>
                </div>

Copy


                <div class="row">
                    <div class="col-md-6">
                        <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker  ">Checkbox in a row required</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The checkbox required required must be acknowledged" id="CheckboxRequiredInARowOne" name="CheckboxRequiredInARowOne" value="true" /><input name="CheckboxRequiredInARowOne" type="hidden" value="false" />
<label class="control-label" for="CheckboxRequiredInARowOne">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxRequiredInARowOne" data-valmsg-replace="true"></span>
</fieldset>
                    </div>
                    <div class="col-md-6">
                        <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker  ">Checkbox in a row required</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The checkbox required required must be acknowledged" id="CheckboxRequiredInARowTwo" name="CheckboxRequiredInARowTwo" value="true" /><input name="CheckboxRequiredInARowTwo" type="hidden" value="false" />
<label class="control-label" for="CheckboxRequiredInARowTwo">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxRequiredInARowTwo" data-valmsg-replace="true"></span>
</fieldset>
                    </div>
                </div>

Checkbox hide validation message

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxRequiredHideValidationMessage" checkbox-label="Checkbox label" hide-validation-message />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker  ">Checkbox hide validation message</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The checkbox hide validation message must be acknowledged" id="CheckboxRequiredHideValidationMessage" name="CheckboxRequiredHideValidationMessage" value="true" /><input name="CheckboxRequiredHideValidationMessage" type="hidden" value="false" />
<label class="control-label" for="CheckboxRequiredHideValidationMessage">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
</fieldset>

Checkbox disabled

Checkbox label

Copy


                <turas-checkbox asp-for="CheckboxDisabled" checkbox-label="Checkbox label" hide-required-marker asp-is-disabled="True" />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker suppressRequiredFieldMarker ">Checkbox disabled</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" disabled="disabled" type="checkbox" data-val="true" data-val-required="The Checkbox disabled field is required." id="CheckboxDisabled" name="CheckboxDisabled" value="true" /><input name="CheckboxDisabled" type="hidden" value="false" />
<label class="control-label" for="CheckboxDisabled">Checkbox label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxDisabled" data-valmsg-replace="true"></span>
</fieldset>

Checkbox hide heading label

Copy


                <turas-checkbox asp-for="CheckboxHideHideHeadingLabel" hide-heading-label />

Copy


                <fieldset class="form-group form-single-checkbox "><legend class="control-label requiredFieldMarker  sr-only">Checkbox hide heading label</legend>
<div class="form-check custom-checkbox">
<input class="form-check-input" type="checkbox" data-val="true" data-val-required="The Checkbox hide heading label field is required." id="CheckboxHideHideHeadingLabel" name="CheckboxHideHideHeadingLabel" value="true" /><input name="CheckboxHideHideHeadingLabel" type="hidden" value="false" />
<label class="control-label" for="CheckboxHideHideHeadingLabel">Checkbox hide heading label</label>
</div><!-- end form-check custom-checkbox -->
<span class="field-validation-valid" data-valmsg-for="CheckboxHideHideHeadingLabel" data-valmsg-replace="true"></span>
</fieldset>

Parameters for turas-checkbox

asp-for - Binds the checkbox to a model property
checkbox-label - Sets the label text for the checkbox
hide-required-marker - Hides the required marker if the checkbox is required
heading-label - Sets a heading label for the checkbox
guidance-text - Provides additional guidance text for the checkbox
additional-classes - Allows for custom CSS classes to be added to the checkbox
asp-is-disabled - Disables the checkbox if set to true
hide-heading-label - Hides the heading label for the checkbox
hide-validation-message - Hides the validation message for the checkbox

Testing

Check that the checkbox:

can be used with a keyboard only, using Tab to enter or leave the checkbox, Space to select an option with no keyboard traps
shows a visible focus state on the checkbox that has keyboard focus
focus moves logically in and out of the checkbox
screen readers announce the question, each option and which option is selected
hint text or instructions are read out by screen readers
error messages are announced by screen readers and associated with the checkbox
selecting an option does not automatically submit the form, move focus or take users to another page
users are told when they must select an option
remains usable at 400% zoom and supports reflow without horizontal scrolling
makes it clear when selecting an option will reveal additional fields
users can select an option by clicking or tapping its label

Developer considerations

When using the checkbox component in your form:

always associate the checkbox with a visible <label> using for and id
use the native <input type="checkbox"> element where possible
ensure the checkbox has an accessible name using a visible label
ensure each checkbox has a meaningful value
avoid pre-selecting the checkbox unless there is a clear user benefit and it does not create a risk of unintended choices
ensure custom checkbox components maintain native checkbox behaviour
write error messages that explain what went wrong and how to fix it
ensure the control works without JavaScript where possible
ensure a visible focus state that meets contrast requirements
ensure the component remains usable when text is resized and content reflows
ensure sufficient touch target size and spacing, with a target size of at least 24 × 24 CSS pixels

Required fields

If your form contains fields that users must complete:

clearly indicate when the checkbox or group is required by using a visual indicator such as an asterisk
do not rely on the visual indicator alone (for example, an asterisk) to communicate that a field is required and include the help text “Required fields are marked with an asterisk *” at the top of every page of the form
ensure the required state of the checkbox or group is programmatically available to assistive technologies using aria-required="true"

Conditional behaviour

If your checkbox reveals additional content based on a user's selection:

only reveal content when it is logically dependent on the selection
do not automatically move focus when content is revealed
place revealed content directly after the checkbox that controls it in the DOM
hide the content from all users, including assistive technology users, until it is needed
ensure hidden fields are not focusable
when revealed, ensure the content is reachable in the natural tab order
consider adding hint text to explain that additional fields may appear
use the Turas conditional reveal pattern so the new content is available to screen readers

Actions panel

Checkbox group

Checkbox

Examples

Usage

Parameters for turas-checkbox

Testing

Developer considerations

Required fields

Conditional behaviour

Was this page helpful?