@payfit/unity-components
Version:
77 lines (76 loc) • 3.34 kB
TypeScript
import { StandardSchemaV1 } from '@standard-schema/spec';
import { ForwardedRef, JSX, ReactNode } from 'react';
import { FieldPath, FieldValues } from 'react-hook-form';
import { Schema } from '../../hooks/use-form.types.js';
import { LabelProps } from '../label/Label.js';
interface FieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> extends Pick<LabelProps, 'isRequired' | 'requiredVariant'> {
/** The name of the field, which should match the form schema. */
name: TName;
/** The label for the checkbox. */
children: ReactNode;
/** Helper text to display below the checkbox. */
helperText?: ReactNode;
/** A contextual link to display below the checkbox. */
contextualLink?: ReactNode;
/** The default selected value of the checkbox. */
defaultSelected?: boolean;
/** Whether the checkbox is disabled. */
isDisabled?: boolean;
/** Whether the checkbox is read-only. */
isReadOnly?: boolean;
/** Whether the checkbox is invalid. */
isInvalid?: boolean;
/** Whether the checkbox is loading. */
isLoading?: boolean;
}
export type CheckboxFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FieldProps<TFieldValues, TName>;
type CheckboxFieldComponent = (<TSchema extends Schema>(props: CheckboxFieldProps<StandardSchemaV1.InferOutput<TSchema>> & {
ref?: ForwardedRef<HTMLLabelElement>;
}) => JSX.Element) & {
displayName?: string;
};
/**
* The `CheckboxField` component enhances the base Checkbox with form integration capabilities,
* making it easy to handle boolean values in forms with proper validation and feedback.
*
* It provides form validation, helper text, and error feedback while maintaining the same
* API as the base Checkbox component. The component automatically integrates with Unity's
* form context and handles value updates through the form's state management.
* @param {CheckboxFieldProps} props - Props for the CheckboxField component
* @see {@link CheckboxFieldProps} for all available props
* @example
* ```tsx
* import { useUnityForm, CheckboxField } from '@payfit/unity-components'
* import * as z from 'zod'
*
* function Example() {
* const schema = z.object({
* acceptTerms: z.boolean().refine(Boolean, {
* message: 'You must accept the terms',
* }),
* })
*
* const { Form } = useUnityForm(schema)
*
* return (
* <Form action={handleSubmit}>
* <CheckboxField<typeof schema>
* name="acceptTerms"
* helperText="Please read our terms carefully"
* >
* Accept terms and conditions
* </CheckboxField>
* </Form>
* )
* }
* ```
* @remarks
* [API](/?path=/docs/forms-checkboxfield--docs) • [Demo](/?path=/story/forms-checkboxfield--primary)
* @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 CheckboxField: CheckboxFieldComponent;
export { CheckboxField };