@payfit/unity-components
Version:
82 lines (81 loc) • 3.48 kB
TypeScript
import { StandardSchemaV1 } from '@standard-schema/spec';
import { ForwardedRef, JSX, PropsWithChildren, ReactNode } from 'react';
import { FieldPath, FieldValues } from 'react-hook-form';
import { Schema } from '../../hooks/use-form.types.js';
import { CheckboxGroupProps } from '../checkbox-group/CheckboxGroup.js';
import { LabelProps } from '../label/Label.js';
interface FieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> extends PropsWithChildren<Pick<LabelProps, 'isRequired' | 'requiredVariant'>> {
/** The name of the field, which should match the form schema. */
name: TName;
/** The label for the checkbox group. */
label: string;
/** Helper text to display below the checkbox group. */
helperText?: ReactNode;
/** A contextual link to display below the checkbox group. */
contextualLink?: ReactNode;
/** The default selected values of the checkbox group. */
defaultValue?: string[];
/** Whether the checkbox group is disabled. */
isDisabled?: boolean;
/** Whether the checkbox group is read-only. */
isReadOnly?: boolean;
/** Whether the checkbox group is invalid. */
isInvalid?: boolean;
/** Whether the checkbox group is loading. */
isLoading?: boolean;
/** Callback when the selection changes. */
onChange?: (value: string[]) => void;
/**
* Handler called when the checkbox receives focus.
*/
onFocus?: CheckboxGroupProps['onFocus'];
/**
* Handler called when the checkbox loses focus.
*/
onBlur?: CheckboxGroupProps['onBlur'];
/**
* Handler that is called when the element's focus status changes.
* @param isFocused
*/
onFocusChange?: (isFocused: boolean) => void;
}
export type CheckboxGroupFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FieldProps<TFieldValues, TName>;
type CheckboxGroupFieldComponent = (<TSchema extends Schema>(props: CheckboxGroupFieldProps<StandardSchemaV1.InferOutput<TSchema>> & {
ref?: ForwardedRef<HTMLDivElement>;
}) => JSX.Element) & {
displayName?: string;
};
/**
* The `CheckboxGroupField` component renders a group of related checkboxes that can be used in forms.
* It integrates with the `Form` component automatically and provides form validation, helper text,
* and error feedback.
* @example
* ```tsx
* const schema = z.object({
* preferences: z.array(z.string())
* })
*
* function MyForm() {
* const { Form } = useUnityForm(schema)
*
* return (
* <Form action={handleSubmit}>
* <CheckboxGroupField<typeof schema>
* name="preferences"
* label="Select your preferences"
* helperText="Choose all that apply"
* >
* <Checkbox value="email">Email notifications</Checkbox>
* <Checkbox value="sms">SMS notifications</Checkbox>
* </CheckboxGroupField>
* </Form>
* )
* }
* ```
* @note The schema type parameter is needed to ensure type safety with the form's schema.
* If you omit it, the `name` prop will not be type-safe.
* @deprecated React Hook Form components are deprecated. Use the TanStack Form version instead.
* @see Storybook docs: https://unity-components.payfit.io/?path=/docs/forms-introduction-to-unity-forms--docs
*/
declare const CheckboxGroupField: CheckboxGroupFieldComponent;
export { CheckboxGroupField };