Checkbox

Skip to page content

BETA

Component demo

Interactive example

Select your extras

Extra shot (50p)

Soya milk

Takeaway cup

Web component

React

<ic-checkbox-grouplabel="Select your extras"name="default">
<ic-checkboxvalue="extra"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="Soya milk"label="Soya milk"checked></ic-checkbox>
<ic-checkboxvalue="keep cup"label="Takeaway cup"disabled="true"></ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your extras"name="default"onIcChange={(ev)=>console.log("onIcChange", ev.detail.value)}>
<IcCheckboxvalue="extra"label="Extra shot (50p)"onIcCheck={(ev)=>console.log("onIcCheck", ev)}/>
<IcCheckboxvalue="Soya milk"label="Soya milk"checked/>
<IcCheckboxvalue="keep cup"label="Takeaway cup"disabled/>
</IcCheckboxGroup>

Checkbox group details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name	Description	Default
Property label Attribute label	The label for the checkbox group to be displayed. Required type: string
Property name Attribute name	The name for the checkbox group to differentiate from other groups. Required type: string
Property disabled Attribute disabled	If`true` , the checkbox group will be set to the disabled state. type: boolean	false
Property helperText Attribute helper-text	The helper text that will be displayed for additional field guidance. type: string	""
Property hideLabel Attribute hide-label	If`true` , the label will be hidden and the required label value will be applied as an aria-label. type: boolean	false
Property required Attribute required	If`true` , the checkbox group will require a value. type: boolean	false
Property size Attribute size	The size of the checkboxes to be displayed. This does not affect the font size of the label. type: IcSizes - "default" \| "large" \| "small"	"default"
Property small Attribute small	This prop should not be used anymore. Set prop `size` to "small" instead. Deprecated	false
Property validationStatus Attribute validation-status	The validation status - e.g. 'error' \| 'warning' \| 'success'. type: IcInformationStatusOrEmpty - "" \| "error" \| "success" \| "warning"	""
Property validationText Attribute validation-text	The validation text - e.g. 'error' \| 'warning' \| 'success'. type: string	""

Property

label

Attribute

label

The label for the checkbox group to be displayed.

Required

type: string

Property

name

Attribute

name

The name for the checkbox group to differentiate from other groups.

Required

type: string

Property

disabled

Attribute

disabled

Iftrue , the checkbox group will be set to the disabled state.

type: boolean

Default: false

Property

helperText

Attribute

helper-text

The helper text that will be displayed for additional field guidance.

type: string

Default: ""

Property

hideLabel

Attribute

hide-label

Iftrue , the label will be hidden and the required label value will be applied as an aria-label.

type: boolean

Default: false

Property

required

Attribute

required

Iftrue , the checkbox group will require a value.

type: boolean

Default: false

Property

size

Attribute

size

The size of the checkboxes to be displayed. This does not affect the font size of the label.

type: IcSizes - "default" | "large" | "small"

Default: "default"

Property

small

Attribute

small

This prop should not be used anymore. Set prop `size` to "small" instead.

Deprecated

Default: false

Property

validationStatus

Attribute

validation-status

The validation status - e.g. 'error' | 'warning' | 'success'.

type: IcInformationStatusOrEmpty - "" | "error" | "success" | "warning"

Default: ""

Property

validationText

Attribute

validation-text

The validation text - e.g. 'error' | 'warning' | 'success'.

type: string

Default: ""

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name	Description	Signature
Web component icChange React onIcChange	Emitted when a checkbox is checked.	IcChangeEventDetail

Web component

icChange

React

onIcChange

Emitted when a checkbox is checked.

IcChangeEventDetail

Checkbox details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name	Description	Default
Property label Attribute label	The label for the checkbox. Required type: string
Property value Attribute value	The value for the checkbox. Required type: string
Property additionalFieldDisplay Attribute additional-field-display	The style of additionalField that will be displayed if used. type: IcAdditionalFieldTypes - "dynamic" \| "static"	"static"
Property checked Attribute checked	If`true` , the checkbox will be set to the checked state. This is only the initial state and will be updated to unchecked if the checkbox is clicked. type: boolean	false
Property disabled Attribute disabled	If`true` , the checkbox will be set to the disabled state. type: boolean	false
Property dynamicText Attribute dynamic-text	The text to be displayed when dynamic. type: string	"This selection requires additional answers"
Property form Attribute form	The <form> element to associate the checkbox with. type: string
Property formaction Attribute formaction	The URL that processes the information submitted by the checkbox. It overrides the action attribute of the checkbox's form owner. Does nothing if there is no form owner. type: string
Property formenctype Attribute formenctype	The way the submitted form data is encoded. type: string
Property formmethod Attribute formmethod	The HTTP method used to submit the form. type: string
Property formnovalidate Attribute formnovalidate	If`true` , the form will not be validated when submitted. type: boolean
Property formtarget Attribute formtarget	The place to display the response from submitting the form. It overrides the target attribute of the checkbox's form owner. type: string
Property groupLabel Attribute group-label	The group label for the checkbox. type: string
Property hideLabel Attribute hide-label	If`true` , the label will be hidden and the required label value will be applied as an aria-label. type: boolean	false
Property indeterminate Attribute indeterminate	If`true` , the indeterminate state will be displayed when checked. type: boolean	false
Property name Attribute name	The name for the checkbox. If not set when used in a checkbox group, the name will be based on the group name. type: string
Property nativeIndeterminateBehaviour Attribute native-indeterminate-behaviour	If`true` , the checkbox will behave like a native checkbox where the`indeterminate` prop sets the indeterminate visual styling, independent of the`checked` state. type: boolean	false
Property size Attribute size	The size of the checkbox to be displayed. This does not affect the font size of the label. If a checkbox is contained in a checkbox group, this will override the size set on checkbox group. type: IcSizes - "default" \| "large" \| "small"
Property small Attribute small	This prop should not be used anymore. Set prop `size` to "small" instead. Deprecated	false

Property

label

Attribute

label

The label for the checkbox.

Required

type: string

Property

value

Attribute

value

The value for the checkbox.

Required

type: string

Property

additionalFieldDisplay

Attribute

additional-field-display

The style of additionalField that will be displayed if used.

type: IcAdditionalFieldTypes - "dynamic" | "static"

Default: "static"

Property

checked

Attribute

checked

Iftrue , the checkbox will be set to the checked state. This is only the initial state and will be updated to unchecked if the checkbox is clicked.

type: boolean

Default: false

Property

disabled

Attribute

disabled

Iftrue , the checkbox will be set to the disabled state.

type: boolean

Default: false

Property

dynamicText

Attribute

dynamic-text

The text to be displayed when dynamic.

type: string

Default: "This selection requires additional answers"

Property

form

Attribute

form

The <form> element to associate the checkbox with.

type: string

Property

formaction

Attribute

formaction

The URL that processes the information submitted by the checkbox. It overrides the action attribute of the checkbox's form owner. Does nothing if there is no form owner.

type: string

Property

formenctype

Attribute

formenctype

The way the submitted form data is encoded.

type: string

Property

formmethod

Attribute

formmethod

The HTTP method used to submit the form.

type: string

Property

formnovalidate

Attribute

formnovalidate

Iftrue , the form will not be validated when submitted.

type: boolean

Property

formtarget

Attribute

formtarget

The place to display the response from submitting the form. It overrides the target attribute of the checkbox's form owner.

type: string

Property

groupLabel

Attribute

group-label

The group label for the checkbox.

type: string

Property

hideLabel

Attribute

hide-label

Iftrue , the label will be hidden and the required label value will be applied as an aria-label.

type: boolean

Default: false

Property

indeterminate

Attribute

indeterminate

Iftrue , the indeterminate state will be displayed when checked.

type: boolean

Default: false

Property

name

Attribute

name

The name for the checkbox. If not set when used in a checkbox group, the name will be based on the group name.

type: string

Property

nativeIndeterminateBehaviour

Attribute

native-indeterminate-behaviour

Iftrue , the checkbox will behave like a native checkbox where theindeterminate prop sets the indeterminate visual styling, independent of thechecked state.

type: boolean

Default: false

Property

size

Attribute

size

The size of the checkbox to be displayed. This does not affect the font size of the label. If a checkbox is contained in a checkbox group, this will override the size set on checkbox group.

type: IcSizes - "default" | "large" | "small"

Property

small

Attribute

small

This prop should not be used anymore. Set prop `size` to "small" instead.

Deprecated

Default: false

Slots

A slot allows for any type of element or markup to be passed into and rendered within a web component. This creates more flexibility than using a prop which must take a specific type of data.

Content can be slotted into a component by adding it as a top-level child of the component.

Slots can have a name to identify them. These specify which slot the content will be inserted into, and therefore where it will be rendered and how it will be used within the component. The name of the slot to be used can be specified by passing it via a slot attribute on the slotted content.

Name	Description
Slot additional-field	Content to be displayed alongside a checkbox.

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name	Description	Signature
Web component checkboxChecked React onCheckboxChecked	This event should not be used anymore. Use icCheck instead. Deprecated	void
Web component icCheck React onIcCheck	Emitted when a checkbox has been checked.	void

Web component

checkboxChecked

React

onCheckboxChecked

This event should not be used anymore. Use icCheck instead.

Deprecated

void

Web component

icCheck

React

onIcCheck

Emitted when a checkbox has been checked.

void

Methods

Name	Description	Signature
Method setFocus	Sets focus on the checkbox.	setFocus() => Promise<void>

Method

setFocus

Sets focus on the checkbox.

setFocus() => Promise<void>

Variants

Hidden label

Interactive example

Extra shot (50p)

Soya milk

Web component

React

<ic-checkbox-grouplabel="Select your extras"hide-label="true"name="1">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your extras"hideLabelname="1">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>

Helper text

Interactive example

Select your extras

Additional charges may apply.

Extra shot (50p)

Soya milk

Web component

React

<ic-checkbox-grouplabel="Select your extras"name="1"helper-text="Additional charges may apply.">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your extras"name="1"helperText="Additional charges may apply.">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>

Sizes

Interactive example

Select your extras

Extra shot (50p)

Soya milk

Select your extras

Extra shot (50p)

Soya milk

Select your extras

Extra shot (50p)

Soya milk

Web component

React

<ic-checkbox-grouplabel="Select your extras"name="1"size="small">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>
<ic-checkbox-grouplabel="Select your extras"name="2">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>
<ic-checkbox-grouplabel="Select your extras"name="3"size="large">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your extras"name="1"size="small">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>
<IcCheckboxGrouplabel="Select your extras"name="2">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>
<IcCheckboxGrouplabel="Select your extras"name="3"size="large">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>

Setting each checkbox size

Interactive example

Extra shot (50p)

Web component

React

<ic-checkboxvalue="valueName1"label="Extra shot (50p)"size="small"/>
<ic-checkboxvalue="valueName2"label="Extra shot (50p)"/>
<ic-checkboxvalue="valueName3"label="Extra shot (50p)"size="large"/>

<IcCheckboxvalue="valueName1"label="Extra shot (50p)"size="small"/>
<IcCheckboxvalue="valueName2"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName3"label="Extra shot (50p)"size="large"/>

Conditional

Interactive example

Which coffee do you like best?

Americano

Espresso

Flat white

Latte

Cappuccino

Other

Web component

React

<ic-checkbox-grouplabel="Which coffee do you like best?"name="conditional">
<ic-checkboxvalue="americano"label="Americano"></ic-checkbox>
<ic-checkboxvalue="espresso"label="Espresso"></ic-checkbox>
<ic-checkboxvalue="flatwhite"label="Flat white"></ic-checkbox>
<ic-checkboxvalue="latte"label="Latte"></ic-checkbox>
<ic-checkboxvalue="cappuccino"label="Cappuccino"></ic-checkbox>
<ic-checkboxvalue="other"label="Other">
<ic-text-field
slot="additional-field"
label="Please let us know..."
></ic-text-field>
</ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Which coffee do you like best?"name="conditional">
<IcCheckboxvalue="americano"label="Americano"/>
<IcCheckboxvalue="espresso"label="Espresso"/>
<IcCheckboxvalue="flatwhite"label="Flat white"/>
<IcCheckboxvalue="latte"label="Latte"/>
<IcCheckboxvalue="cappuccino"label="Cappuccino"/>
<IcCheckboxvalue="other"label="Other">
<IcTextField
slot="additional-field"
label="Please let us know..."
/>
</IcCheckbox>
</IcCheckboxGroup>

Conditional dynamic

Interactive example

Which coffee do you like best?

Americano

Espresso

Flat white

Latte

Cappuccino

Other

Web component

React

<ic-checkbox-grouplabel="Which coffee do you like best?"name="dynamic">
<ic-checkboxvalue="americano"label="Americano"></ic-checkbox>
<ic-checkboxvalue="espresso"label="Espresso"></ic-checkbox>
<ic-checkboxvalue="flatwhite"label="Flat white"></ic-checkbox>
<ic-checkboxvalue="latte"label="Latte"></ic-checkbox>
<ic-checkboxvalue="cappuccino"label="Cappuccino"></ic-checkbox>
<ic-checkboxadditional-field-display="dynamic"value="other"label="Other">
<ic-text-field
slot="additional-field"
label="Please let us know..."
></ic-text-field>
</ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Which coffee do you like best?"name="dynamic">
<IcCheckboxvalue="americano"label="Americano"/>
<IcCheckboxvalue="espresso"label="Espresso"/>
<IcCheckboxvalue="flatwhite"label="Flat white"/>
<IcCheckboxvalue="latte"label="Latte"/>
<IcCheckboxvalue="cappuccino"label="Cappuccino"/>
<IcCheckboxadditionalFieldDisplay="dynamic"value="other"label="Other">
<IcTextField
slot="additional-field"
label="Please let us know..."
/>
</IcCheckbox>
</IcCheckboxGroup>

Validation

Interactive example

Select your extras

Extra shot (50p)

Soya milk

Sorry, this is currently unavailable.

Web component

React

<ic-checkbox-grouplabel="Select your extras"name="1"validation-status="error"validation-text="Sorry, this is currently unavailable.">
<ic-checkboxvalue="valueName1"label="Extra shot (50p)"></ic-checkbox>
<ic-checkboxvalue="valueName2"label="Soya milk"checked="true"></ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your extras"name="1"validationStatus="error"validationText="Sorry, this is currently unavailable.">
<IcCheckboxvalue="valueName1"label="Extra shot (50p)"/>
<IcCheckboxvalue="valueName2"label="Soya milk"checked/>
</IcCheckboxGroup>

Indeterminate

Interactive example

Select your preferred drinks

Drinks

Tea

Coffee

Mocha

Espresso

Cappuccino

Juice

Web component

React

<ic-checkbox-grouplabel="Select your preferred drinks"name="1">
<ic-checkboxvalue="drinks"label="Drinks"checked="true"indeterminate="true">
<ic-checkbox-grouplabel="Coffee"hide-label="true"slot="additional-field"name="2">
<ic-checkboxvalue="tea"label="Tea"></ic-checkbox>
<ic-checkboxvalue="coffee"label="Coffee"checked="true"indeterminate="true">
<ic-checkbox-grouplabel="Coffees"hide-label="true"slot="additional-field"name="3">
<ic-checkboxvalue="mocha"label="Mocha"></ic-checkbox>
<ic-checkboxvalue="espresso"label="Espresso"checked="true"></ic-checkbox>
<ic-checkboxvalue="cappuccino"label="Cappuccino"></ic-checkbox>
</ic-checkbox-group>
</ic-checkbox>
<ic-checkboxvalue="juice"label="Juice"></ic-checkbox>
</ic-checkbox-group>
</ic-checkbox>
</ic-checkbox-group>

<IcCheckboxGrouplabel="Select your preferred drinks"name="1">
<IcCheckboxvalue="drinks"label="Drinks"checkedindeterminate>
<IcCheckboxGroupname="2"label="Coffee"hideLabelslot="additional-field">
<IcCheckboxvalue="tea"label="Tea"/>
<IcCheckboxvalue="coffee"label="Coffee"checkedindeterminate>
<IcCheckboxGrouplabel="Coffees"hideLabelslot="additional-field"name="3">
<IcCheckboxvalue="mocha"label="Mocha"/>
<IcCheckboxvalue="espresso"label="Espresso"checked/>
<IcCheckboxvalue="cappuccino"label="Cappuccino"/>
</IcCheckboxGroup>
</IcCheckbox>
<IcCheckboxvalue="juice"label="Juice"/>
</IcCheckboxGroup>
</IcCheckbox>
</IcCheckboxGroup>

Last reviewed 31 May 2024 .