## Component Name
Checkbox
## Description
Checkbox is a form control that allows users to select one or multiple options from a set of choices. It can be used individually or grouped together using CheckboxGroup for managing related options. Checkboxes support various states including checked, unchecked, indeterminate, disabled, and can display help text or error messages to guide users.
## TypeScript Types
The following types represent the props that the Checkbox component and its subcomponents accept. These allow you to properly configure the component according to your needs.
```typescript
/**
* Props for the Checkbox component
*/
type CheckboxProps = {
/**
* The label for the checkbox
*/
children?: React.ReactNode;
/**
* The default state of the checkbox (uncontrolled)
* @default false
*/
defaultChecked?: boolean;
/**
* Error message to display when validation state is error
*/
errorText?: string;
/**
* Help text to display below the checkbox
*/
helpText?: string;
/**
* Whether the checkbox is checked (controlled)
*/
isChecked?: boolean;
/**
* Whether the checkbox is disabled
* @default false
*/
isDisabled?: boolean;
/**
* Whether the checkbox is in an indeterminate state
* @default false
*/
isIndeterminate?: boolean;
/**
* Whether the checkbox is required
* @default false
*/
isRequired?: boolean;
/**
* Name of the checkbox for form submission
*/
name?: string;
/**
* Callback fired when the checkbox state changes
*/
onChange?: (event: { isChecked: boolean; name?: string; value?: string }) => void;
/**
* Size of the checkbox
* @default 'medium'
*/
size?: 'small' | 'medium' | 'large';
/**
* The validation state of the checkbox
*/
validationState?: 'error' | 'none';
/**
* Value of the checkbox for form submission
*/
value?: string;
} & StyledPropsBlade &
TestID;
/**
* Props for the CheckboxGroup component
*/
type CheckboxGroupProps = {
/**
* The checkboxes to be grouped
*/
children: React.ReactNode;
/**
* The default selected values (uncontrolled)
*/
defaultValue?: string[];
/**
* Error message to display when validation state is error
*/
errorText?: string;
/**
* Help text to display below the checkbox group
*/
helpText?: string;
/**
* Whether the checkbox group is disabled
* @default false
*/
isDisabled?: boolean;
/**
* Whether the checkbox group is required
* @default false
*/
isRequired?: boolean;
/**
* The label for the checkbox group
*/
label: string;
/**
* Position of the label relative to the checkbox group
*/
labelPosition?: 'top' | 'left';
/**
* Name of the checkbox group for form submission
*/
name?: string;
/**
* Indicator for whether the checkbox group is required or optional
* @default 'none'
*/
necessityIndicator?: 'none' | 'required' | 'optional';
/**
* Callback fired when any checkbox in the group changes
*/
onChange?: (event: { values: string[]; name?: string }) => void;
/**
* Size of the checkboxes in the group
* @default 'medium'
*/
size?: 'small' | 'medium' | 'large';
/**
* The validation state of the checkbox group
*/
validationState?: 'error' | 'none';
/**
* The selected values (controlled)
*/
value?: string[];
} & StyledPropsBlade &
TestID;
```
## Examples
### Payment Setup Form with Checkboxes
This comprehensive example demonstrates a payment setup form with both single checkboxes and checkbox groups. It covers various use cases including:
- Controlled and uncontrolled checkboxes
- Required validation with error states
- Indeterminate state with "select all" functionality
- Different checkbox sizes
- Help text and error messaging
- Label positioning options for CheckboxGroup
```tsx
import React, { useState, useRef } from 'react';
import { Checkbox, CheckboxGroup, Box, Text, Button, Heading } from '@razorpay/blade/components';
const PaymentSetupForm = () => {
// State for form submission
const [formSubmitted, setFormSubmitted] = useState(false);
// State for terms agreement (single controlled checkbox)
const [termsAgreed, setTermsAgreed] = useState(false);
// State for notification preferences (single checkboxes)
const [emailNotifications, setEmailNotifications] = useState(true);
const [smsNotifications, setSmsNotifications] = useState(false);
// Ref for focusing checkbox
const termsCheckboxRef = useRef(null);
// State for payment methods (checkbox group with select all functionality)
const paymentMethods = ['credit_card', 'debit_card', 'netbanking', 'upi', 'wallet'];
const [selectedPaymentMethods, setSelectedPaymentMethods] = useState(['credit_card', 'upi']);
// Calculate select all states
const allMethodsSelected = selectedPaymentMethods.length === paymentMethods.length;
const someMethodsSelected = selectedPaymentMethods.length > 0 && !allMethodsSelected;
const noMethodsSelected = selectedPaymentMethods.length === 0;
// Handlers for payment methods
const handleSelectAllMethods = (event) => {
if (event.isChecked) {
setSelectedPaymentMethods([...paymentMethods]);
} else {
setSelectedPaymentMethods([]);
}
};
const handlePaymentMethodsChange = (event) => {
setSelectedPaymentMethods(event.values);
};
// Handler for form submission
const handleSubmit = (e) => {
e.preventDefault();
setFormSubmitted(true);
// Focus terms checkbox if not agreed
if (!termsAgreed) {
termsCheckboxRef.current?.focus();
return;
}
// If validation passes, submit form data
if (termsAgreed && !noMethodsSelected) {
console.log('Form submitted successfully!', {
termsAgreed,
emailNotifications,
smsNotifications,
selectedPaymentMethods,
});
alert('Payment setup completed successfully!');
}
};
return (
);
};
export default PaymentSetupForm;
```
### Product Configuration Form
This example showcases a product configuration form with checkboxes for customizing a product purchase. It demonstrates different Checkbox sizes and validation states.
```tsx
import React, { useState } from 'react';
import { Checkbox, CheckboxGroup, Box, Text, Button, Heading } from '@razorpay/blade/components';
const ProductConfigurationForm = () => {
// State for selected features
const [selectedFeatures, setSelectedFeatures] = useState(['basic_reporting']);
// State for add-ons
const [giftWrap, setGiftWrap] = useState(false);
const [expressShipping, setExpressShipping] = useState(false);
const [insuranceAdded, setInsuranceAdded] = useState(false);
// State for validation
const [showValidation, setShowValidation] = useState(false);
// Validate and submit
const handleSubmit = (e) => {
e.preventDefault();
setShowValidation(true);
if (selectedFeatures.length > 0) {
console.log('Configuration submitted:', {
selectedFeatures,
addOns: {
giftWrap,
expressShipping,
insuranceAdded,
},
});
alert('Product configured successfully!');
}
};
return (
);
};
export default ProductConfigurationForm;
```