Checkbox
Use when
Use a checkbox when users need to make a yes/no decision about a single question and the changes don't take effect immediately. For example, use a checkbox in a modal where the user confirms the decision before changes take effect.
Use checkbox groups when users must make multiple, related yes/no decisions.
Use icon checkboxes in a checkbox group when the icons are sufficient to clearly communicate the options.
Use checkboxes to enable conditional inputs as part of a task. For 1-3 inputs, disable the inputs until users select the checkbox. For more than 3 inputs, hide the inputs until users select the checkbox.
Don't use
Don't use checkbox groups when users need to make multiple selections from homogenous lists of more than 5 items. Use a different selection input, such as a lookup field, instead.
However, checkbox groups can include more than 5 checkboxes when users need to make a series of yes/no decisions about heterogenous options.
Don't use a checkbox when users can toggle between two states or options and changes take place immediately. Use toggle switch instead.
Don't use a checkbox group for a lone checkbox in a form or field group.
However, if the form or field group contains both a checkbox group and a lone checkbox, use a checkbox group for the lone checkbox to differentiate it from the other checkboxes.
Individual checkbox
Checkbox group
Icon checkbox
Headings
By default, the labels for checkbox groups aren't treated as HTML headings. To emphasize a label as an HTML heading in a form hierarchy, you can use headingLevelheadingStyle
In rare cases, you can hide a checkbox group label and use other text to present the checkboxes.
Required field marker
You can require a checkbox group to force users to meet criteria that you set, such as a minimum or maximum number of checkboxes to select. Use hint text to communicate those constraints. For example, use hint text to tell users to "Select at least one" or "Select no more than three."
In rare cases, you can require a lone checkbox, such as when you need to force users to select a checkbox to agree to terms of use.
When a checkbox or checkbox group is required, a red asterisk appears to the right of the label. It includes the appropriate ARIA attributes to support users of assistive technologies. For more information about required fields, see the form design guidelines.
Help inline button
When you need to supplement a checkbox or checkbox group label with additional information but don't require persistent inline help, you can place a help inline button beside the label to invoke contextual user assistance.
Hint text
To highlight important considerations about a checkbox or checkbox group, use hint text. This persistent inline help can explain details such as:
- Constraints or requirements on a checkbox group
- Consequences of a choice that may not be apparent
- Additional instructions or context, such as how data is used
Stacked margin
Checkbox groups automatically add vertical spacing between individual checkboxes. For consistent vertical spacing when a checkbox group is immediately followed by another form input, use stacked
Don't use stacked
- Is the last input inside a field group
- Is the last input on a form
Also use stackedstackedsky-margin-stacked-sm
If a checkbox group uses headingLevelstacked
Make checkbox group labels succinct and descriptive. In most cases, use nouns or noun phrases. When necessary, checkbox group labels can use short sentences or sentence fragments.
For details about styling checkbox group labels as headings, see the "Headings" section above.
Similarly, make checkbox labels succinct and descriptive. When necessary, checkbox labels can use short sentences or sentence fragments.
Don't wrap a checkbox group inside a field group component when the checkbox group is the only content.
For example, if a form's "Supported credit cards" section only includes a checkbox group, don't use a field group. Instead, set the checkbox group's headingLevelheadingStyle3h3sky-font-heading-3
Checkbox groups automatically create <fieldset><legend>
In most cases, checkbox group labels aren't treated as HTML headings, but when necessary, you can specify a heading level and heading style. For example, when a lone checkbox group appears on a form with field groups, set the checkbox group's headingLevelheadingStyle3h3sky-font-heading-3
Components
Guidelines
- NPM package
@skyux/formsView in NPM | View in GitHub None found.- Install with NPM
npm install --save-exact @skyux/formsNone found.
import { SkyCheckboxModule } from '@skyux/forms';
Selector: sky-checkbox
Replaces the HTML input element with type="checkbox". When users select a checkbox, its value
is driven through an ngModel attribute that you specify on the sky-checkbox element.
Inputs
checkboxType: string
The background color type after users select a checkbox where the
icon property displays an icon in place of the checkbox. The valid options correspond to
the label component's
label types. "info" creates a blue background, "success" creates a green
background, "warning" creates an orange background, and "danger" creates a red background.
Default: "info"
checked: boolean
Whether the checkbox is selected.
disabled: boolean
Whether the checkbox is disabled.
helpKey: string | undefined
A help key that identifies the global help content to display. When specified along with labelText, a help inline
button is placed beside the checkbox label. Clicking the button invokes global help
as configured by the application. This property only applies when labelText is also specified.
helpPopoverContent: string | TemplateRef<unknown> | undefined
The content of the help popover. When specified along with labelText, a help inline
button is added to the checkbox label. The help inline button displays a popover
when clicked using the specified content and optional title. This property only applies when labelText is also specified.
helpPopoverTitle: string | undefined
The title of the help popover. This property only applies when helpPopoverContent is
also specified.
hintText: string | undefined
Persistent inline help text that provides additional context to the user.
icon: string | undefined
The icon to display in place of the checkbox. To group icon checkboxes
like in the demo, place the checkboxes within a sky-checkbox-group.
iconName: string | undefined
The SVG icon to display in place of the checkbox. To group icon checkboxes
like in the demo, place the checkboxes within a sky-checkbox-group.
id: string | undefined
The ID for the checkbox. If a value is not provided, an autogenerated ID is used.
label: string | undefined
The ARIA label for the checkbox. This sets the checkbox's aria-label attribute
to support accessibility
when the checkbox does not include a visible label. You must set this property for icon
checkboxes. If the checkbox includes a visible label, use labelledBy instead.
labelHidden: boolean
Indicates whether to hide the labelText.
Default: false
labelText: string | undefined
The text to display as the checkbox's label. Use this instead of the sky-checkbox-label when the label is text-only.
Specifying labelText also enables automatic error message handling for checkbox.
labelledBy: string | undefined
The HTML element ID of the element that labels the
checkbox. This sets the checkbox's aria-labelledby attribute
to support accessibility.
If the checkbox does not include a visible label, use label instead.
name: string
The name for the checkbox. If a value is not provided, an autogenerated ID is used.
required: boolean
Whether the input is required for form validation.
When you set this property to true, the component adds aria-required and required
attributes to the input element so that forms display an invalid state until the input element
is complete.
Default: false
stacked: boolean
Whether the checkbox is stacked on another form component. When specified, the appropriate
vertical spacing is automatically added to the checkbox. If the checkbox is within a checkbox group,
set stacked on the checkbox group component instead.
Default: false
tabindex: number | undefined
The index for the checkbox. If not defined, the index is set to the position of the checkbox on load.
Default: 0
Outputs
change: EventEmitter<SkyCheckboxChange>
Fires when the selected value changes.
checkedChange: Observable<boolean>
Fires when users select or deselect the checkbox.
disabledChange: Observable<boolean>
Fires when the selected value changes.
Selector: sky-checkbox-group
Organizes checkboxes into a group.
Inputs
headingHidden: boolean
Indicates whether to hide the headingText.
Default: false
headingLevel: SkyCheckboxGroupHeadingLevel | undefined
The semantic heading level in the document structure. By default, the heading text is not wrapped in a heading element.
headingStyle: SkyCheckboxGroupHeadingStyle
The heading font style.
Default: 4
headingText: string
The text to display as the checkbox group's heading.
helpKey: string | undefined
A help key that identifies the global help content to display. When specified along with headingText, a help inline
button is placed beside the checkbox group heading. Clicking the button invokes global help
as configured by the application. This property only applies when headingText is also specified.
helpPopoverContent: string | TemplateRef<unknown> | undefined
The content of the help popover. When specified along with headingText, a help inline
button is added to the checkbox group fieldset legend. The help inline button displays a popover
when clicked using the specified content and optional title. This property only applies when headingText is also specified.
helpPopoverTitle: string | undefined
The title of the help popover. This property only applies when helpPopoverContent is
also specified.
hintText: string | undefined
Persistent inline help text that provides additional context to the user.
required: boolean
Whether the checkbox group is required.
Default: false
stacked: boolean
Whether the checkbox group is stacked on another form component. When specified, the appropriate vertical spacing is automatically added to the checkbox group.
Selector: sky-checkbox-label
Specifies a label for the checkbox. To display a help button beside the label, include a help button element, such as
sky-help-inline, in the sky-checkbox-label element and a sky-control-help CSS class on that help button
element.
Fires when users select or deselect the checkbox.
interface SkyCheckboxChange {
checked?: boolean;
}Properties
checked?: boolean
The value from the checkbox component.
type SkyCheckboxGroupHeadingLevel = 3 | 4 | 5
type SkyCheckboxGroupHeadingStyle = 3 | 4 | 5SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyCheckboxHarness } from '@skyux/forms/testing';
Harness for interacting with a checkbox component in tests.
Methods
blur(): Promise<void>
Blurs the checkbox.
Returns
Promise<void>
check(): Promise<void>
Puts the checkbox in a checked state by toggling it if it is currently unchecked, or doing nothing if it is already checked.
Returns
Promise<void>
clickHelpInline(): Promise<void>
Clicks the help inline button.
Returns
Promise<void>
focus(): Promise<void>
Focuses the checkbox.
Returns
Promise<void>
getAriaLabel(): Promise<null | string>
Gets the checkbox's aria-label.
Returns
Promise<null | string>
getAriaLabelledby(): Promise<null | string>
Gets the checkbox's aria-labelledby.
Returns
Promise<null | string>
getHelpPopoverContent(): Promise<undefined | string>
Gets the help popover content.
Returns
Promise<undefined | string>
getHelpPopoverTitle(): Promise<undefined | string>
Gets the help popover title.
Returns
Promise<undefined | string>
getHintText(): Promise<string>
Gets the checkbox's hint text.
Returns
Promise<string>
getLabelHidden(): Promise<boolean>
Whether the label is hidden. Only supported when using the labelText input to set the label.
Returns
Promise<boolean>
getLabelText(): Promise<undefined | string>
Gets the checkbox's label text. If the label is set via labelText and labelHidden is true,
the text will still be returned.
Returns
Promise<undefined | string>
getName(): Promise<null | string>
Gets the checkbox's name.
Returns
Promise<null | string>
getValue(): Promise<null | string>
Gets the checkbox's value.
Returns
Promise<null | string>
hasCustomError(errorName: string): Promise<boolean>
Whether the checkbox displays custom error.
Parameters
errorName: string
Returns
Promise<boolean>
hasRequiredError(): Promise<boolean>
Whether the checkbox displays an error that it is required.
Returns
Promise<boolean>
isChecked(): Promise<boolean>
Whether the checkbox is checked.
Returns
Promise<boolean>
isDisabled(): Promise<boolean>
Whether the checkbox is disabled.
Returns
Promise<boolean>
isFocused(): Promise<boolean>
Whether the checkbox is focused.
Returns
Promise<boolean>
isRequired(): Promise<boolean>
Whether the checkbox is required.
Returns
Promise<boolean>
isStacked(): Promise<boolean>
Whether the checkbox is stacked.
Returns
Promise<boolean>
uncheck(): Promise<void>
Puts the checkbox in an unchecked state by toggling it if it is currently checked, or doing nothing if it is already unchecked.
Returns
Promise<void>
SkyCheckboxHarness.with(filters: SkyCheckboxHarnessFilters): HarnessPredicate<SkyCheckboxHarness>
Gets a HarnessPredicate that can be used to search for a
SkyCheckboxHarness that meets certain criteria.
Parameters
filters: SkyCheckboxHarnessFilters
Returns
HarnessPredicate<SkyCheckboxHarness>
A set of criteria that can be used to filter a list of SkyCheckboxHarness instances.
interface SkyCheckboxHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyCheckboxGroupHarness } from '@skyux/forms/testing';
Harness for interacting with a checkbox group component in tests.
Methods
clickHelpInline(): Promise<void>
Clicks the help inline button.
Returns
Promise<void>
getCheckboxes(): Promise<SkyCheckboxHarness[]>
Gets an array of harnesses for the checkboxes in the checkbox group.
Returns
Promise<SkyCheckboxHarness[]>
getHeadingHidden(): Promise<boolean>
Whether the heading is hidden.
Returns
Promise<boolean>
getHeadingLevel(): Promise<undefined | SkyCheckboxGroupHeadingLevel>
The semantic heading level used for the checkbox group. Returns undefined if heading level is not set.
Returns
Promise<undefined | SkyCheckboxGroupHeadingLevel>
getHeadingStyle(): Promise<SkyCheckboxGroupHeadingStyle>
getHeadingText(): Promise<undefined | string>
Gets the checkbox group's heading text. If headingHidden is true,
the text will still be returned.
Returns
Promise<undefined | string>
getHelpPopoverContent(): Promise<undefined | string>
Gets the help popover content.
Returns
Promise<undefined | string>
getHelpPopoverTitle(): Promise<undefined | string>
Gets the help popover title.
Returns
Promise<undefined | string>
getHintText(): Promise<string>
Gets the checkbox group's hint text.
Returns
Promise<string>
getRequired(): Promise<boolean>
Whether the checkbox group is required.
Returns
Promise<boolean>
getStacked(): Promise<boolean>
Whether the checkbox group is stacked.
Returns
Promise<boolean>
hasError(errorName: string): Promise<boolean>
Whether the checkbox group has errors.
Parameters
errorName: string
Returns
Promise<boolean>
hasRequiredError(): Promise<boolean>
Whether all the checkboxes in a required group are unchecked.
Returns
Promise<boolean>
SkyCheckboxGroupHarness.with(filters: SkyCheckboxGroupHarnessFilters): HarnessPredicate<SkyCheckboxGroupHarness>
Gets a HarnessPredicate that can be used to search for a
SkyCheckboxGroupHarness that meets certain criteria.
Parameters
filters: SkyCheckboxGroupHarnessFilters
Returns
HarnessPredicate<SkyCheckboxGroupHarness>
A set of criteria that can be used to filter a list of SkyCheckboxGroupHarness instances.
interface SkyCheckboxGroupHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
Loading...