Components Forms
CheckboxGroup
StableA labelled set of checkboxes that share one array value.
Use CheckboxGroup when users can choose any number of options from a short list. It renders a fieldset and legend, so the group label is announced with each option, and manages the selected values as a string array. For more than about eight options, consider MultiSelect.
Overview
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';
export function Basic() {
return (
<CheckboxGroup
label="Notify me when"
description="Notifications are sent to your work email."
defaultValue={['signed']}
>
<Checkbox value="viewed" label="A signer opens the document" />
<Checkbox value="signed" label="A signer completes signing" />
<Checkbox value="declined" label="A signer declines" />
<Checkbox value="expired" label="A request expires" />
</CheckboxGroup>
);
}Light, dark and high contrast
Every Stance component is designed and tested in all three appearance modes.
Import
import { CheckboxGroup, Checkbox } from '@bindshq/stance-react';Examples
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';
export function Horizontal() {
return (
<CheckboxGroup
label="Show in signature"
orientation="horizontal"
defaultValue={['phone', 'logo']}
>
<Checkbox value="phone" label="Phone" />
<Checkbox value="address" label="Address" />
<Checkbox value="logo" label="Logo" />
<Checkbox value="social" label="Social links" />
</CheckboxGroup>
);
}import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';
export function Validation() {
return (
<CheckboxGroup label="Deploy to" required error="Choose at least one destination">
<Checkbox value="m365" label="Microsoft 365" />
<Checkbox value="google" label="Google Workspace" />
</CheckboxGroup>
);
}Selected: pdf
import * as React from 'react';
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';
export function Controlled() {
const [value, setValue] = React.useState<string[]>(['pdf']);
return (
<div style={{ display: 'grid', gap: 12 }}>
<CheckboxGroup label="Export formats" value={value} onValueChange={setValue}>
<Checkbox value="pdf" label="PDF" />
<Checkbox value="docx" label="Word (DOCX)" />
<Checkbox value="html" label="HTML" />
</CheckboxGroup>
<span style={{ fontSize: 14 }}>Selected: {value.join(', ') || 'none'}</span>
</div>
);
}API reference
| Prop | Type | Default | Description |
|---|---|---|---|
label* required | ReactNode | None | Group label, rendered as the legend. |
value | string[] | None | Controlled selected values. |
defaultValue | string[] | [] | Initial selected values. |
onValueChange | (value: string[]) => void | None | Called with the new selection. |
name | string | None | Form field name applied to every checkbox. |
description | ReactNode | None | Help text under the legend. |
error | ReactNode | None | Error message; marks every checkbox invalid. |
required | boolean | false | Shows a required indicator on the legend. |
disabled | boolean | false | Disables all checkboxes. |
orientation | 'vertical' | 'horizontal' | 'vertical' | Layout of the options. |
hideLabel | boolean | false | Visually hide the legend. |
size | 'sm' | 'md' | 'md' | Size of every checkbox. |
Accessibility
- Uses <fieldset> and <legend>, so the group name is announced when focus enters the group.
- Description and error are linked to the fieldset; the error uses role="alert".
- Each checkbox remains a separate tab stop, matching native behaviour.
Keyboard
| Keys | Action |
|---|---|
| Tab | Moves between checkboxes. |
| Space | Toggles the focused checkbox. |