Github

Checkbox Group

Checkbox groups let users select multiple related options from the same set.

Component variations

Direction

Checkbox groups can be displayed vertically or horizontally.

Nested Groups

Parent items become indeterminate based on child selection

Usage Guidelines

Import

Import the checkbox group component and item interface:

import-checkbox-group.ts

Copy code

Basic Implementation

Provide a list of items and track selected values:

1. Define items in TypeScript

my.component.ts

Copy code

2. Render in template

my.component.html

Copy code

Nested Groups

Parent items display indeterminate states based on child selection:

1. Define nested items

my.component.ts

Copy code

2. Render nested groups

my.component.html

Copy code

Handling Output

Listen to the valueChange event to react when selected values change:

1. Define handler in TypeScript

my.component.ts

Copy code

2. Bind in template

my.component.html

Copy code

All Available APIs

Example using all available APIs:

checkbox-group-example.html

Copy code

API Reference

Inputs

Property
Type
Default
Required
Description
items
VdCheckboxGroupItem[]
[]
Yes
List of checkbox items, supports nested children
direction
'vertical' | 'horizontal'
'vertical'
No
Layout direction for the top-level list
value
(string | number)[]
[]
No
Array of selected item values
disabled
boolean
false
No
Disables the entire group

Outputs

Property
Type
Description
valueChange
EventEmitter<(string | number)[]>
Emits updated selected values

VdCheckboxGroupItem Interface

Each item in the items array follows this interface:

Property
Type
Required
Description
label
string
Yes
Display text for the checkbox item
value
string | number
No
Unique value emitted on selection. Falls back to label if not provided
description
string
No
Supporting text displayed below the label
disabled
boolean
No
Disables this specific checkbox item
children
VdCheckboxGroupItem[]
No
Nested child items. Parent becomes indeterminate when partially selected

Best Practices

When to Use

  • Use Checkbox Group when this pattern clearly supports the user task.
  • Use it to keep similar interactions consistent across the product.

When Not to Use

  • Avoid using Checkbox Group when a simpler component communicates the same intent.
  • Avoid using it when the pattern introduces unnecessary interaction steps.

Design Guidelines

  • Use nested groups to represent hierarchical choices
  • Prefer vertical layout for long lists to improve readability
  • Keep option labels short and descriptive
  • Use indeterminate state to show partial selections in a group
  • Keep labels, helper text, and actions concise and easy to scan.
  • Use VD variants and states consistently for predictable behavior.
  • Ensure keyboard access and clear focus order for accessibility.

Component playground

Interact with the checkbox group in this section

example.html

Copy code