Checkbox

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

Loading...

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

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

Introduction

import { Checkbox } from '@telus-uds/components-base'

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

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
error	bool	false	Whether the underlying input triggered a validation error or not.
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.
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).
value	union		The value. Must be unique within the group.
onChange	func		Callback called when a controlled checkbox gets interacted with.
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details