@payfit/unity-components
Version:
71 lines (70 loc) • 3.22 kB
TypeScript
import { StandardSchemaV1 } from '@standard-schema/spec';
import { ForwardedRef, JSX } from 'react';
import { FieldPath, FieldValues } from 'react-hook-form';
import { Schema } from '../../hooks/use-form.types.js';
interface FieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> {
/** The name of the field, which should match the form schema. */
name: TName;
/** The label for the toggle switch. */
label: string;
/** Helper text to display below the toggle switch. */
switchHelperText?: string;
/** The default selected value of the toggle switch. */
defaultSelected?: boolean;
/** Whether the toggle switch is disabled. */
isDisabled?: boolean;
/** Whether the toggle switch is read-only. */
isReadOnly?: boolean;
/** Whether the toggle switch is invalid. */
isInvalid?: boolean;
/** Whether the toggle switch is loading. */
isLoading?: boolean;
/** Whether the label is visually hidden and accessible only to screen readers. */
isLabelSrOnly?: boolean;
}
export type ToggleSwitchFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FieldProps<TFieldValues, TName>;
type ToggleSwitchFieldComponent = (<TSchema extends Schema>(props: ToggleSwitchFieldProps<StandardSchemaV1.InferOutput<TSchema>> & {
ref?: ForwardedRef<HTMLLabelElement>;
}) => JSX.Element) & {
displayName?: string;
};
/**
* The `ToggleSwitchField` component enhances the base ToggleSwitch with form integration capabilities.
* It automatically integrates with Unity's form context and handles value updates through the form's state management.
*
* The component provides form validation, helper text, and error feedback while maintaining the same
* API as the base ToggleSwitch component. It's the recommended way to use toggle switches within forms.
* @param {ToggleSwitchFieldProps} props - Props for the ToggleSwitchField component
* @example
* ```tsx
* import { useUnityForm, ToggleSwitchField } from '@payfit/unity-components'
* import * as z from 'zod'
*
* function Example() {
* const schema = z.object({
* enableFeature: z.boolean(),
* })
*
* const { Form } = useUnityForm(schema)
*
* return (
* <Form action={handleSubmit}>
* <ToggleSwitchField<typeof schema>
* name="enableFeature"
* label="Enable feature"
* helperText="Turn this on to enable the feature."
* />
* </Form>
* )
* }
* ```
* @see {@link ToggleSwitchFieldProps} for all available props
* @remarks
* [API](/?path=/docs/forms-toggleswitchfield--docs) • [Demo](/?path=/story/forms-toggleswitchfield--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 ToggleSwitchField: ToggleSwitchFieldComponent;
export { ToggleSwitchField };