Guide
API Reference
Guide
API Reference

Types API Reference

Core Types

FieldValue

Base type for any field value.

type FieldValue = any;

FieldValues

Base type for form data structure.

type FieldValues = Record<string, FieldValue>;

AnyRecord

Utility type for objects with string keys and unknown values.

type AnyRecord = Record<string, unknown>;

PartialRecord

Utility type for partial records.

type PartialRecord<K extends keyof any, T> = {
  [P in K]?: T;
};

Prettify

Utility type to improve TypeScript IDE display of complex types.

type Prettify<T> = {
  [K in keyof T]: T[K];
} & {};

Validation Types

VALIDATION_OUTCOME

Enum representing the validation state of a field or form.

enum VALIDATION_OUTCOME {
  VALID = 'VALID',
  INVALID = 'INVALID', 
  UNDETERMINED = 'UNDETERMINED'
}
  • VALID: Validation passed
  • INVALID: Validation failed
  • UNDETERMINED: Validation hasn't been performed or is pending

ValidationStatus

Object containing validation information for a field.

interface ValidationStatus {
  status: VALIDATION_OUTCOME;
  message: string | undefined;
}
  • status: Current validation outcome
  • message: Error message when status is INVALID, undefined otherwise

Validator

Function type for validation rules.

type Validator = (value: FieldValue) => boolean | Promise<boolean>;

Returns true if valid, false if invalid. Can be synchronous or asynchronous.

Form Types

UseFormOptions

Options for configuring a form instance.

interface UseFormOptions<T extends FieldValues> {
  defaultValues?: Partial<T>;
  onUpdateAfterBlur?: (values: Partial<T>, data?: AnyRecord) => void;
}
  • defaultValues: Initial field values
  • onUpdateAfterBlur: Callback triggered after field blur when field is valid

FormContextApi

API interface for form instances.

interface FormContextApi<T extends FieldValues> {
  // Value management
  getFormValues(): Partial<T>;
  setFormValues(newValues: Partial<T>): void;
  resetForm(): void;
  
  // Form submission
  handleSubmit(callback: (values: Partial<T>) => void): () => void;
  
  // Internal methods (used by components)
  // ... (implementation details)
}

FormValues

Type representing form values with optional fields.

type FormValues<T extends FieldValues, Keys extends keyof T> = {
  [K in Keys]: T[K] | undefined;
};

FormValidations

Type representing validation statuses for form fields.

type FormValidations<T extends FieldValues, Keys extends keyof T> = {
  [K in Keys]: ValidationStatus | undefined;
};

Watch Types

WATCH_MODE

Enum for different value watching modes.

enum WATCH_MODE {
  ON_CHANGE = 'ON_CHANGE',
  ON_BLUR = 'ON_BLUR'
}
  • ON_CHANGE: Values update on every change
  • ON_BLUR: Values update only when field loses focus

Wizard Types

StepValidator

Function type for step-level validation in wizards.

type StepValidator<WizardValues extends Record<string, FieldValues>, Step extends keyof WizardValues> = (
  stepValues: WizardValues[Step] | undefined
) => boolean | Promise<boolean>;

Returns true to allow progression to next step, false to block.

Steps

Type for configuring wizard steps.

type Steps<WizardValues extends Record<string, FieldValues>> = {
  [K in keyof WizardValues]: {
    name: K;
    onNext?: StepValidator<WizardValues, K>;
  };
}[keyof WizardValues][];

Array of step configurations with optional validation.

WizardContextApi

API interface for wizard instances.

interface WizardContextApi<WizardValues extends Record<string, FieldValues>> {
  // Step information
  steps: (keyof WizardValues)[];
  currentStep: keyof WizardValues | undefined;
  isLastStep: boolean;
  isFirstStep: boolean;
  hasNoFooter: boolean;
  isStepReady: boolean;

  // Navigation
  goNext(): Promise<void>;
  goPrevious(): void;
  goBackTo(step: keyof WizardValues): void;

  // Data access
  getValuesOfStep<Step extends keyof WizardValues>(stepName: Step): WizardValues[Step] | undefined;
  getValuesOfCurrentStep<Step extends keyof WizardValues>(): WizardValues[Step] | undefined;
  getValuesOfSteps(): WizardValues;
  
  // Internal methods
  // ... (implementation details)
}

Component Prop Types

FieldRenderProps

Props passed to Field render function.

interface FieldRenderProps<T extends FieldValues, K extends keyof T> {
  name: K;
  value: T[K] | undefined;
  onFocus(): void;
  onBlur(): void;
  onChange(value: T[K] | undefined): void;
}

FieldRenderState

State information passed to Field render function.

interface FieldRenderState {
  isPristine: boolean;
  validationStatus: ValidationStatus;
}
  • isPristine: Whether the field has been interacted with
  • validationStatus: Current validation status and message

FieldProps

Props for the Field component.

interface FieldProps<T extends FieldValues, K extends keyof T> {
  name: K;
  children?: ReactNode; // Rules
  render(fieldProps: FieldRenderProps<T, K>, fieldState: FieldRenderState): ReactNode | null;
  data?: AnyRecord;
  defaultValue?: T[K];
}

FormProps

Props for the Form component.

interface FormProps<T extends FieldValues> extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
  children: ReactNode;
  form: FormContextApi<T>;
  onSubmit?: () => void;
}

RuleProps

Props for the Rule component.

interface RuleProps {
  validationFn: Validator;
  message: string;
  isDebounced?: boolean;
}

StepProps

Props for the Step component.

interface StepProps<WizardValues extends Record<string, FieldValues>, Step extends keyof WizardValues> {
  children: ReactNode;
  name: Step;
  onNext?: StepValidator<WizardValues, Step>;
  noFooter?: boolean;
  title?: string;
}

Utility Functions

mapValidationStatusesToOutcome

Utility function to determine overall outcome from multiple validation statuses.

function mapValidationStatusesToOutcome(statuses: ValidationStatus[]): VALIDATION_OUTCOME;

Takes an array of validation statuses and returns:

  • VALID if all are valid
  • INVALID if any are invalid
  • UNDETERMINED if any are undetermined and none are invalid

Generic Constraints

Most types use these constraints to ensure type safety:

// Form types must extend FieldValues
T extends FieldValues

// Field names must be keys of the form type
K extends keyof T

// Wizard values must be a record of FieldValues
WizardValues extends Record<string, FieldValues>

// Step names must be keys of WizardValues
Step extends keyof WizardValues

Example Type Usage

Strongly Typed Form

interface UserForm {
  email: string;
  password: string;
  age: number;
  isAdmin: boolean;
}

const form = useForm<UserForm>({
  defaultValues: {
    isAdmin: false
  }
});

// Type-safe field access
const validations = useValidations(form, ['email', 'password']); // Only allows valid keys
const values = useOnChangeValues(form, ['email']); // values.email is string | undefined

Strongly Typed Wizard

interface RegistrationWizard {
  personal: {
    firstName: string;
    lastName: string;
    dateOfBirth: Date;
  };
  account: {
    email: string;
    password: string;
    confirmPassword: string;
  };
  preferences: {
    newsletter: boolean;
    theme: 'light' | 'dark';
  };
}

const wizard = useWizard<RegistrationWizard>(
  (data) => {
    // data is fully typed as RegistrationWizard
    console.log(data.personal.firstName); // TypeScript knows this exists
  }
);

// Type-safe step form
const { form } = useStepForm<RegistrationWizard, 'personal'>();
// form is typed for RegistrationWizard['personal'] only
Sur cette page