Checkbox

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<Checkbox label="This is a checkbox" />

<Checkbox label="This is a checkbox" />

Introduction

import { Checkbox } from '@telus-uds/ds-allium'

Checkbox component represents a checkbox, either isolated or within a form.

Guidance

caution

In most cases, CheckboxGroup should be used instead of using Checkbox directly.

Pass the CheckboxGroup an items array and it will render Checkbox buttons for each item in the array with appropriate accessibility props, web form tags and state management.

Controlled version

If the checkbox is controlled from outside, it needs to receive checked and onChange props.

Uncontrolled version

In case of uncontrolled checkbox you can use defaultChecked prop to provide the initial value. Whenever the checkbox gets toggled, it calls the onChange callback with the new value (boolean).

Using within forms

You can pass name and value props if you need a particular checkbox to be a part of a group of checkboxes on a form.

Validation and feedback

You can use the feedback prop to provide a comment related to the checkbox element. If the comment is related to a validation error, the checkbox and the feedback can be styled accordingly by setting the error prop to true (can also be done without feedback).

Accessibility

Checkbox component accepts all the common accessibility props, but also sets some defaults, including accessibility role 'checkbox' and accessibility state that depends on the other props (checked, inactive) or the internal state in case of uncontrolled checkbox.

Platform considerations

The component is available on both native platforms and web.

Props

• Use label prop to provide a label for the checkbox.
• For a disabled Checkbox set the inactive prop to true.

Name	Type	Default	Description
checked	bool		Use 'checked' for controlled Checkbox. For uncontrolled Checkbox, use the 'defaultChecked' prop.
defaultChecked	bool		Use 'defaultChecked' to provide the initial value for an uncontrolled Checkbox.
error	bool	false	Whether the underlying input triggered a validation error or not.
feedback	string		A detailed description of related validation error or additional instructions (depending on the 'error' prop).
id	string		Checkbox ID.
inactive	bool		Whether the corresponding input is disabled or active.
label	string		The label.
name	string		Associate this checkbox with a group (set as the name attribute).
onChange	func		Callback called when a controlled checkbox gets interacted with.
tokens	custom		System tokens prop, see tokens for more details
value	string | number | bool		The value. Must be unique within the group.
variant	objectOf		System variant prop, see variants for more details

Tokens

In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.

View Tokens

Prop Name	Token Property	Token Type
tokens	containerBackgroundColor	color
	feedbackMarginBottom	size
	feedbackMarginTop	size
	feedbackPosition	position
	icon	icon
	iconBackgroundColor	color
	iconColor	color
	iconSize	size
	inputBackgroundColor	color
	inputBorderColor	color
	inputBorderRadius	radius
	inputBorderWidth	border
	inputHeight	size
	inputOutlineColor	color
	inputOutlineWidth	border
	inputShadow	shadow
	inputWidth	size
	labelColor	color
	labelFontName	fontName
	labelFontSize	fontSize
	labelFontWeight	fontWeight
	labelLineHeight	lineHeight
	labelMarginLeft	size

Figma

Variants

This component does not have any stylistic variants.

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support