react-forms

Pool

Modern, performant React form library - 78% smaller than Formik, perfect TypeScript inference

$ lpm install @lpm.dev/neo.react-forms

README API Skills3 Dependencies1 Versions1

272 exportsTypeScript

dist

Functions

useForm

function useForm<Values extends Record<string, unknown>>(options: UseFormOptions<Values>): UseFormReturn<Values>

Main useForm hook

Parameter	Type	Description
`options`	`UseFormOptions<Values>`

dist/adapters

Functions

zodAdapter

function zodAdapter<T extends ZodObject>(schema: T): ValidationSchema<ZodInfer<T>>

Convert Zod object schema to ValidationSchema

Parameter	Type	Description
`schema`	`T`	- Zod object schema

zodForm

function zodForm<T extends ZodObject>(schema: T, initialValues: ZodInfer<T>): {
    initialValues: ZodInfer<T>;
    validate: ValidationSchema<ZodInfer<T>>;
}

Helper to create form with Zod schema and automatic type inference

Parameter	Type	Description
`schema`	`T`	- Zod schema
`initialValues`	`ZodInfer<T>`	- Initial form values (must match schema type)

dist/adapters

Functions

zodAdapter

function zodAdapter<T extends ZodObject>(schema: T): ValidationSchema<ZodInfer<T>>

Convert Zod object schema to ValidationSchema

Parameter	Type	Description
`schema`	`T`	- Zod object schema

zodForm

function zodForm<T extends ZodObject>(schema: T, initialValues: ZodInfer<T>): {
    initialValues: ZodInfer<T>;
    validate: ValidationSchema<ZodInfer<T>>;
}

Helper to create form with Zod schema and automatic type inference

Parameter	Type	Description
`schema`	`T`	- Zod schema
`initialValues`	`ZodInfer<T>`	- Initial form values (must match schema type)

dist/index-B4V7GjKf

Functions

required

function required(message?: string): Validator<string>

Required field validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

function email(message?: string): Validator<string>

Email validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

url

function url(message?: string): Validator<string>

URL validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

minLength

function minLength(min: number, message?: string): Validator<string>

Minimum length validator

Parameter	Type	Description
`min`	`number`	- Minimum length
`message`optional	`string`	- Custom error message

maxLength

function maxLength(max: number, message?: string): Validator<string>

Maximum length validator

Parameter	Type	Description
`max`	`number`	- Maximum length
`message`optional	`string`	- Custom error message

pattern

function pattern(pattern: RegExp, message?: string): Validator<string>

Pattern validator (regex)

Parameter	Type	Description
`pattern`	`RegExp`	- Regular expression
`message`optional	`string`	- Custom error message

alphanumeric

function alphanumeric(message?: string): Validator<string>

Alphanumeric validator (letters and numbers only)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

alpha

function alpha(message?: string): Validator<string>

Alpha validator (letters only)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

lowercase

function lowercase(message?: string): Validator<string>

Lowercase validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

uppercase

function uppercase(message?: string): Validator<string>

Uppercase validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

trimmed

function trimmed(message?: string): Validator<string>

Trim validator (no leading/trailing whitespace)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

contains

function contains(substring: string, message?: string): Validator<string>

Contains validator (must include substring)

Parameter	Type	Description
`substring`	`string`	- Substring to check for
`message`optional	`string`	- Custom error message

startsWith

function startsWith(prefix: string, message?: string): Validator<string>

Starts with validator

Parameter	Type	Description
`prefix`	`string`	- Prefix to check for
`message`optional	`string`	- Custom error message

endsWith

function endsWith(suffix: string, message?: string): Validator<string>

Ends with validator

Parameter	Type	Description
`suffix`	`string`	- Suffix to check for
`message`optional	`string`	- Custom error message

min

function min(minValue: number, message?: string): Validator<number>

Minimum value validator

Parameter	Type	Description
`minValue`	`number`	- Minimum allowed value
`message`optional	`string`	- Custom error message

max

function max(maxValue: number, message?: string): Validator<number>

Maximum value validator

Parameter	Type	Description
`maxValue`	`number`	- Maximum allowed value
`message`optional	`string`	- Custom error message

between

function between(minValue: number, maxValue: number, message?: string): Validator<number>

Range validator (between min and max)

Parameter	Type	Description
`minValue`	`number`	- Minimum value
`maxValue`	`number`	- Maximum value
`message`optional	`string`	- Custom error message

integer

function integer(message?: string): Validator<number>

Integer validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

positive

function positive(message?: string): Validator<number>

Positive number validator (> 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

negative

function negative(message?: string): Validator<number>

Negative number validator (< 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

nonNegative

function nonNegative(message?: string): Validator<number>

Non-negative validator (>= 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

nonPositive

function nonPositive(message?: string): Validator<number>

Non-positive validator (<= 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

safeInteger

function safeInteger(message?: string): Validator<number>

Safe integer validator (within Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

finite

function finite(message?: string): Validator<number>

Finite number validator (not Infinity or NaN)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

multipleOf

function multipleOf(divisor: number, message?: string): Validator<number>

Multiple of validator (divisible by)

Parameter	Type	Description
`divisor`	`number`	- The number to divide by
`message`optional	`string`	- Custom error message

even

function even(message?: string): Validator<number>

Even number validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

odd

function odd(message?: string): Validator<number>

Odd number validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

compose

function compose<T, Values = unknown>(validators: Validator<T, Values>[]): Validator<T, Values>

Compose multiple validators (runs all, returns first error)

Parameter	Type	Description
`validators`	`Validator<T, Values>[]`	- Array of validators to compose

optional

function optional<T, Values = unknown>(validator: Validator<T, Values>): Validator<T | null | undefined, Values>

Optional validator (only validates if value exists)

Parameter	Type	Description
`validator`	`Validator<T, Values>`	- Validator to make optional

when

function when<T, Values = unknown>(condition: (value: T, values?: Values) => boolean, validator: Validator<T, Values>): Validator<T, Values>

Conditional validator (only validates if condition is true)

Parameter	Type	Description
`condition`	`(value: T, values?: Values) => boolean`	- Function that returns true if validation should run
`validator`	`Validator<T, Values>`	- Validator to run conditionally

custom

function custom<T, Values = unknown>(validate: (value: T, values?: Values) => string | null | Promise<string | null>): Validator<T, Values>

Create custom validator

Parameter	Type	Description
`validate`	`(value: T, values?: Values) => string \| null \| Promise<string \| null>`	- Validation function

test

function test<T, Values = unknown>(test: (value: T, values?: Values) => boolean | Promise<boolean>, message: string): Validator<T, Values>

Test validator (custom test function)

Parameter	Type	Description
`test`	`(value: T, values?: Values) => boolean \| Promise<boolean>`	- Test function (returns true if valid)
`message`	`string`	- Error message

oneOf

function oneOf<T, Values = unknown>(values: T[], message?: string): Validator<T, Values>

One of validator (value must be in list)

Parameter	Type	Description
`values`	`T[]`	- Allowed values
`message`optional	`string`	- Custom error message

notOneOf

function notOneOf<T, Values = unknown>(values: T[], message?: string): Validator<T, Values>

Not one of validator (value must NOT be in list)

Parameter	Type	Description
`values`	`T[]`	- Disallowed values
`message`optional	`string`	- Custom error message

equals

function equals<T, Values = unknown>(expected: T, message?: string): Validator<T, Values>

Equals validator (value must equal expected)

Parameter	Type	Description
`expected`	`T`	- Expected value
`message`optional	`string`	- Custom error message

notEquals

function notEquals<T, Values = unknown>(notExpected: T, message?: string): Validator<T, Values>

Not equals validator (value must NOT equal expected)

Parameter	Type	Description
`notExpected`	`T`	- Value to avoid
`message`optional	`string`	- Custom error message

debounce

function debounce<T extends (...args: any[]) => Promise<any>>(fn: T, wait: number): T & {
    cancel: () => void;
}

Debounce function

Parameter	Type	Description
`fn`	`T`	- Function to debounce
`wait`	`number`	- Milliseconds to wait

debounceValidator

function debounceValidator<T>(validator: (value: T) => Promise<string | null>, wait?: number): (value: T) => Promise<string | null>

Create a debounced validator

Parameter	Type	Description
`validator`	`(value: T) => Promise<string \| null>`	- Async validator function
`wait`optional	`number`	- Debounce delay in milliseconds (default: 300ms)

Variables

index_alphatypeof alpha

Tree-shakeable validators Import only what you need: ```ts import { required, email, min, max } from '@lpm.dev/neo.react-forms/validators' ``` Or import from specific categories: ```ts import { required, email } from '@lpm.dev/neo.react-forms/validators/string' import { min, max } from '@lpm.dev/neo.react-forms/validators/number' ```

index_alphanumerictypeof alphanumeric

index_betweentypeof between

index_composetypeof compose

index_containstypeof contains

index_customtypeof custom

index_debouncetypeof debounce

index_debounceValidatortypeof debounceValidator

index_emailtypeof email

index_endsWithtypeof endsWith

index_equalstypeof equals

index_eventypeof even

index_finitetypeof finite

index_integertypeof integer

index_lowercasetypeof lowercase

index_maxtypeof max

index_maxLengthtypeof maxLength

index_mintypeof min

index_minLengthtypeof minLength

index_multipleOftypeof multipleOf

index_negativetypeof negative

index_nonNegativetypeof nonNegative

index_nonPositivetypeof nonPositive

index_notEqualstypeof notEquals

index_notOneOftypeof notOneOf

index_oddtypeof odd

index_oneOftypeof oneOf

index_optionaltypeof optional

index_patterntypeof pattern

index_positivetypeof positive

index_requiredtypeof required

index_safeIntegertypeof safeInteger

index_startsWithtypeof startsWith

index_testtypeof test

index_trimmedtypeof trimmed

index_uppercasetypeof uppercase

index_urltypeof url

index_whentypeof when

dist/index-BzVbBKH3

Functions

required

function required(message?: string): Validator<string>

Required field validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

function email(message?: string): Validator<string>

Email validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

url

function url(message?: string): Validator<string>

URL validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

minLength

function minLength(min: number, message?: string): Validator<string>

Minimum length validator

Parameter	Type	Description
`min`	`number`	- Minimum length
`message`optional	`string`	- Custom error message

maxLength

function maxLength(max: number, message?: string): Validator<string>

Maximum length validator

Parameter	Type	Description
`max`	`number`	- Maximum length
`message`optional	`string`	- Custom error message

pattern

function pattern(pattern: RegExp, message?: string): Validator<string>

Pattern validator (regex)

Parameter	Type	Description
`pattern`	`RegExp`	- Regular expression
`message`optional	`string`	- Custom error message

alphanumeric

function alphanumeric(message?: string): Validator<string>

Alphanumeric validator (letters and numbers only)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

alpha

function alpha(message?: string): Validator<string>

Alpha validator (letters only)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

lowercase

function lowercase(message?: string): Validator<string>

Lowercase validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

uppercase

function uppercase(message?: string): Validator<string>

Uppercase validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

trimmed

function trimmed(message?: string): Validator<string>

Trim validator (no leading/trailing whitespace)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

contains

function contains(substring: string, message?: string): Validator<string>

Contains validator (must include substring)

Parameter	Type	Description
`substring`	`string`	- Substring to check for
`message`optional	`string`	- Custom error message

startsWith

function startsWith(prefix: string, message?: string): Validator<string>

Starts with validator

Parameter	Type	Description
`prefix`	`string`	- Prefix to check for
`message`optional	`string`	- Custom error message

endsWith

function endsWith(suffix: string, message?: string): Validator<string>

Ends with validator

Parameter	Type	Description
`suffix`	`string`	- Suffix to check for
`message`optional	`string`	- Custom error message

min

function min(minValue: number, message?: string): Validator<number>

Minimum value validator

Parameter	Type	Description
`minValue`	`number`	- Minimum allowed value
`message`optional	`string`	- Custom error message

max

function max(maxValue: number, message?: string): Validator<number>

Maximum value validator

Parameter	Type	Description
`maxValue`	`number`	- Maximum allowed value
`message`optional	`string`	- Custom error message

between

function between(minValue: number, maxValue: number, message?: string): Validator<number>

Range validator (between min and max)

Parameter	Type	Description
`minValue`	`number`	- Minimum value
`maxValue`	`number`	- Maximum value
`message`optional	`string`	- Custom error message

integer

function integer(message?: string): Validator<number>

Integer validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

positive

function positive(message?: string): Validator<number>

Positive number validator (> 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

negative

function negative(message?: string): Validator<number>

Negative number validator (< 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

nonNegative

function nonNegative(message?: string): Validator<number>

Non-negative validator (>= 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

nonPositive

function nonPositive(message?: string): Validator<number>

Non-positive validator (<= 0)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

safeInteger

function safeInteger(message?: string): Validator<number>

Safe integer validator (within Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

finite

function finite(message?: string): Validator<number>

Finite number validator (not Infinity or NaN)

Parameter	Type	Description
`message`optional	`string`	- Custom error message

multipleOf

function multipleOf(divisor: number, message?: string): Validator<number>

Multiple of validator (divisible by)

Parameter	Type	Description
`divisor`	`number`	- The number to divide by
`message`optional	`string`	- Custom error message

even

function even(message?: string): Validator<number>

Even number validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

odd

function odd(message?: string): Validator<number>

Odd number validator

Parameter	Type	Description
`message`optional	`string`	- Custom error message

compose

function compose<T, Values = unknown>(validators: Validator<T, Values>[]): Validator<T, Values>

Compose multiple validators (runs all, returns first error)

Parameter	Type	Description
`validators`	`Validator<T, Values>[]`	- Array of validators to compose

optional

function optional<T, Values = unknown>(validator: Validator<T, Values>): Validator<T | null | undefined, Values>

Optional validator (only validates if value exists)

Parameter	Type	Description
`validator`	`Validator<T, Values>`	- Validator to make optional

when

function when<T, Values = unknown>(condition: (value: T, values?: Values) => boolean, validator: Validator<T, Values>): Validator<T, Values>

Conditional validator (only validates if condition is true)

Parameter	Type	Description
`condition`	`(value: T, values?: Values) => boolean`	- Function that returns true if validation should run
`validator`	`Validator<T, Values>`	- Validator to run conditionally

custom

function custom<T, Values = unknown>(validate: (value: T, values?: Values) => string | null | Promise<string | null>): Validator<T, Values>

Create custom validator

Parameter	Type	Description
`validate`	`(value: T, values?: Values) => string \| null \| Promise<string \| null>`	- Validation function

test

function test<T, Values = unknown>(test: (value: T, values?: Values) => boolean | Promise<boolean>, message: string): Validator<T, Values>

Test validator (custom test function)

Parameter	Type	Description
`test`	`(value: T, values?: Values) => boolean \| Promise<boolean>`	- Test function (returns true if valid)
`message`	`string`	- Error message

oneOf

function oneOf<T, Values = unknown>(values: T[], message?: string): Validator<T, Values>

One of validator (value must be in list)

Parameter	Type	Description
`values`	`T[]`	- Allowed values
`message`optional	`string`	- Custom error message

notOneOf

function notOneOf<T, Values = unknown>(values: T[], message?: string): Validator<T, Values>

Not one of validator (value must NOT be in list)

Parameter	Type	Description
`values`	`T[]`	- Disallowed values
`message`optional	`string`	- Custom error message

equals

function equals<T, Values = unknown>(expected: T, message?: string): Validator<T, Values>

Equals validator (value must equal expected)

Parameter	Type	Description
`expected`	`T`	- Expected value
`message`optional	`string`	- Custom error message

notEquals

function notEquals<T, Values = unknown>(notExpected: T, message?: string): Validator<T, Values>

Not equals validator (value must NOT equal expected)

Parameter	Type	Description
`notExpected`	`T`	- Value to avoid
`message`optional	`string`	- Custom error message

debounce

function debounce<T extends (...args: any[]) => Promise<any>>(fn: T, wait: number): T & {
    cancel: () => void;
}

Debounce function

Parameter	Type	Description
`fn`	`T`	- Function to debounce
`wait`	`number`	- Milliseconds to wait

debounceValidator

function debounceValidator<T>(validator: (value: T) => Promise<string | null>, wait?: number): (value: T) => Promise<string | null>

Create a debounced validator

Parameter	Type	Description
`validator`	`(value: T) => Promise<string \| null>`	- Async validator function
`wait`optional	`number`	- Debounce delay in milliseconds (default: 300ms)

Variables

index_alphatypeof alpha

index_alphanumerictypeof alphanumeric

index_betweentypeof between

index_composetypeof compose

index_containstypeof contains

index_customtypeof custom

index_debouncetypeof debounce

index_debounceValidatortypeof debounceValidator

index_emailtypeof email

index_endsWithtypeof endsWith

index_equalstypeof equals

index_eventypeof even

index_finitetypeof finite

index_integertypeof integer

index_lowercasetypeof lowercase

index_maxtypeof max

index_maxLengthtypeof maxLength

index_mintypeof min

index_minLengthtypeof minLength

index_multipleOftypeof multipleOf

index_negativetypeof negative

index_nonNegativetypeof nonNegative

index_nonPositivetypeof nonPositive

index_notEqualstypeof notEquals

index_notOneOftypeof notOneOf

index_oddtypeof odd

index_oneOftypeof oneOf

index_optionaltypeof optional

index_patterntypeof pattern

index_positivetypeof positive

index_requiredtypeof required

index_safeIntegertypeof safeInteger

index_startsWithtypeof startsWith

index_testtypeof test

index_trimmedtypeof trimmed

index_uppercasetypeof uppercase

index_urltypeof url

index_whentypeof when

dist/index-CK1rLQVa

Functions

configureDebug

function configureDebug(config: Partial<DebugConfig>): void

Configure debug mode

Parameter	Type	Description
`config`	`Partial<DebugConfig>`	- Debug configuration

getDebugConfig

function getDebugConfig(): DebugConfig

Get current debug configuration

debugValueChange

function debugValueChange(formId: string, fieldName: string, oldValue: any, newValue: any): void

Log field value change

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`oldValue`	`any`
`newValue`	`any`

debugValidation

function debugValidation(formId: string, fieldName: string, result: {
    valid: boolean;
    error?: string;
    duration: number;
}): void

Log validation run

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`result`	`{ valid: boolean; error?: string; duration: number; }`

debugSubmission

function debugSubmission(formId: string, result: {
    success: boolean;
    duration: number;
    error?: any;
}): void

Log form submission

Parameter	Type	Description
`formId`	`string`
`result`	`{ success: boolean; duration: number; error?: any; }`

debugStateUpdate

function debugStateUpdate(formId: string, fieldName: string, state: {
    touched?: boolean;
    dirty?: boolean;
    error?: string;
}): void

Log field state update

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`state`	`{ touched?: boolean; dirty?: boolean; error?: string; }`

debugFormCreated

function debugFormCreated(formId: string, initialValues: any): void

Log form creation

Parameter	Type	Description
`formId`	`string`
`initialValues`	`any`

createFormId

function createFormId(customId?: string): string

Parameter	Type	Description
`customId`optional	`string`

debugFormState

function debugFormState(formId: string, state: any): void

Log form state snapshot (useful for debugging)

Parameter	Type	Description
`formId`	`string`
`state`	`any`

createTimer

function createTimer(): () => number

Performance timer utility

getFieldAriaProps

function getFieldAriaProps(options: {
    name: string;
    hasError?: boolean;
    isRequired?: boolean;
    errorId?: string;
    descriptionId?: string;
}): A11yFieldProps

Generate ARIA attributes for a form field

Parameter	Type	Description
`options`	`{ name: string; hasError?: boolean; isRequired?: boolean; errorId?: string; descriptionId?: string; }`	- Field state and configuration

generateFieldIds

function generateFieldIds(fieldName: string): {
    errorId: string;
    descriptionId: string;
}

Generate unique IDs for error and description elements

Parameter	Type	Description
`fieldName`	`string`	- Field name

getLabelProps

function getLabelProps(fieldName: string, labelText?: string): {
    htmlFor: string;
    children?: string;
}

Get accessible label props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`labelText`optional	`string`	- Label text

getErrorProps

function getErrorProps(fieldName: string, error?: string): {
    id: string;
    role: 'alert';
    'aria-live': 'polite';
    children?: string;
}

Get accessible error message props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`error`optional	`string`	- Error message

getDescriptionProps

function getDescriptionProps(fieldName: string, description?: string): {
    id: string;
    children?: string;
}

Get accessible description props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`description`optional	`string`	- Description text

announceToScreenReader

function announceToScreenReader(message: string, priority?: 'polite' | 'assertive'): void

Announce message to screen readers

Parameter	Type	Description
`message`	`string`	- Message to announce
`priority`optional	`'polite' \| 'assertive'`	- Announcement priority ('polite' or 'assertive')

announceValidationError

function announceValidationError(fieldName: string, error: string): void

Validation error announcer for screen readers

Parameter	Type	Description
`fieldName`	`string`
`error`	`string`

announceFormSubmission

function announceFormSubmission(success: boolean, message?: string): void

Form submission announcer for screen readers

Parameter	Type	Description
`success`	`boolean`
`message`optional	`string`

enhanceErrorMessage

function enhanceErrorMessage(error: string): EnhancedError

Enhance an error message with suggestions

Parameter	Type	Description
`error`	`string`	- Original error message

formatError

function formatError(error: string | EnhancedError, format?: 'message' | 'suggestion' | 'full'): string

Format error message with suggestion

Parameter	Type	Description
`error`	`string \| EnhancedError`	- Error message or enhanced error
`format`optional	`'message' \| 'suggestion' \| 'full'`	- Format type

createValidationError

function createValidationError(message: string, suggestion?: string, code?: string): EnhancedError

Create a validation error with suggestion

Parameter	Type	Description
`message`	`string`	- Error message
`suggestion`optional	`string`	- Helpful suggestion
`code`optional	`string`	- Error code

createFormSnapshot

function createFormSnapshot<Values extends Record<string, unknown>>(formState: FormState<Values>, initialValues: Values): FormSnapshot<Values>

Create a form state snapshot for DevTools inspection

Parameter	Type	Description
`formState`	`FormState<Values>`	- Current form state
`initialValues`	`Values`	- Initial form values (for dirty detection)

logFormState

function logFormState<Values extends Record<string, unknown>>(formId: string, snapshot: FormSnapshot<Values>): void

Log form state to console in a developer-friendly format

Parameter	Type	Description
`formId`	`string`	- Form identifier
`snapshot`	`FormSnapshot<Values>`	- Form snapshot

exposeFormToWindow

function exposeFormToWindow<Values extends Record<string, unknown>>(formId: string, snapshot: FormSnapshot<Values>): void

Expose form state to window for DevTools access

Parameter	Type	Description
`formId`	`string`	- Form identifier
`snapshot`	`FormSnapshot<Values>`	- Form snapshot

diffFormState

function diffFormState<Values extends Record<string, unknown>>(before: FormSnapshot<Values>, after: FormSnapshot<Values>): {
    changedFields: string[];
    newErrors: Partial<Record<Path<Values>, string>>;
    clearedErrors: string[];
    touchedFields: string[];
}

Create a form state diff between two snapshots

Parameter	Type	Description
`before`	`FormSnapshot<Values>`	- Previous snapshot
`after`	`FormSnapshot<Values>`	- Current snapshot

createPerformanceMonitor

function createPerformanceMonitor(): {
    startTimer: (operation: string) => () => void;
    getMetrics: () => Record<string, number>;
    logMetrics: () => void;
}

Create performance monitor for a form

Variables

ErrorMessages

{
    readonly required: (fieldName?: string) => string;
    readonly email: "Please enter a valid email address";
    readonly emailRequired: "Email address is required";
    readonly passwordTooShort: (minLength: number) => string;
    readonly passwordsMatch: "Passwords must match";
    readonly passwordWeak: "Password must include uppercase, lowercase, number, and special character";
    readonly minNumber: (min: number) => string;
    readonly maxNumber: (max: number) => string;
    readonly numberBetween: (min: number, max: number) => string;
    readonly minLength: (min: number) => string;
    readonly maxLength: (max: number) => string;
    readonly url: "Please enter a valid URL (e.g., https://example.com)";
    readonly phone: "Please enter a valid phone number";
    readonly date: "Please enter a valid date";
    readonly dateAfter: (date: string) => string;
    readonly dateBefore: (date: string) => string;
    readonly invalid: (fieldName?: string) => string;
}

Common error messages (pre-defined for consistency)

index_ErrorMessagestypeof ErrorMessages

index_announceFormSubmissiontypeof announceFormSubmission

index_announceToScreenReadertypeof announceToScreenReader

index_announceValidationErrortypeof announceValidationError

index_configureDebugtypeof configureDebug

index_createFormIdtypeof createFormId

index_createFormSnapshottypeof createFormSnapshot

index_createPerformanceMonitortypeof createPerformanceMonitor

index_createTimertypeof createTimer

index_createValidationErrortypeof createValidationError

index_debugFormCreatedtypeof debugFormCreated

index_debugFormStatetypeof debugFormState

index_debugStateUpdatetypeof debugStateUpdate

index_debugSubmissiontypeof debugSubmission

index_debugValidationtypeof debugValidation

index_debugValueChangetypeof debugValueChange

index_diffFormStatetypeof diffFormState

index_enhanceErrorMessagetypeof enhanceErrorMessage

index_exposeFormToWindowtypeof exposeFormToWindow

index_formatErrortypeof formatError

index_generateFieldIdstypeof generateFieldIds

index_getDebugConfigtypeof getDebugConfig

index_getDescriptionPropstypeof getDescriptionProps

index_getErrorPropstypeof getErrorProps

index_getFieldAriaPropstypeof getFieldAriaProps

index_getLabelPropstypeof getLabelProps

index_logFormStatetypeof logFormState

dist/index-DcOeuAnw

Functions

configureDebug

function configureDebug(config: Partial<DebugConfig>): void

Configure debug mode

Parameter	Type	Description
`config`	`Partial<DebugConfig>`	- Debug configuration

getDebugConfig

function getDebugConfig(): DebugConfig

Get current debug configuration

debugValueChange

function debugValueChange(formId: string, fieldName: string, oldValue: any, newValue: any): void

Log field value change

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`oldValue`	`any`
`newValue`	`any`

debugValidation

function debugValidation(formId: string, fieldName: string, result: {
    valid: boolean;
    error?: string;
    duration: number;
}): void

Log validation run

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`result`	`{ valid: boolean; error?: string; duration: number; }`

debugSubmission

function debugSubmission(formId: string, result: {
    success: boolean;
    duration: number;
    error?: any;
}): void

Log form submission

Parameter	Type	Description
`formId`	`string`
`result`	`{ success: boolean; duration: number; error?: any; }`

debugStateUpdate

function debugStateUpdate(formId: string, fieldName: string, state: {
    touched?: boolean;
    dirty?: boolean;
    error?: string;
}): void

Log field state update

Parameter	Type	Description
`formId`	`string`
`fieldName`	`string`
`state`	`{ touched?: boolean; dirty?: boolean; error?: string; }`

debugFormCreated

function debugFormCreated(formId: string, initialValues: any): void

Log form creation

Parameter	Type	Description
`formId`	`string`
`initialValues`	`any`

createFormId

function createFormId(customId?: string): string

Parameter	Type	Description
`customId`optional	`string`

debugFormState

function debugFormState(formId: string, state: any): void

Log form state snapshot (useful for debugging)

Parameter	Type	Description
`formId`	`string`
`state`	`any`

createTimer

function createTimer(): () => number

Performance timer utility

getFieldAriaProps

function getFieldAriaProps(options: {
    name: string;
    hasError?: boolean;
    isRequired?: boolean;
    errorId?: string;
    descriptionId?: string;
}): A11yFieldProps

Generate ARIA attributes for a form field

Parameter	Type	Description
`options`	`{ name: string; hasError?: boolean; isRequired?: boolean; errorId?: string; descriptionId?: string; }`	- Field state and configuration

generateFieldIds

function generateFieldIds(fieldName: string): {
    errorId: string;
    descriptionId: string;
}

Generate unique IDs for error and description elements

Parameter	Type	Description
`fieldName`	`string`	- Field name

getLabelProps

function getLabelProps(fieldName: string, labelText?: string): {
    htmlFor: string;
    children?: string;
}

Get accessible label props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`labelText`optional	`string`	- Label text

getErrorProps

function getErrorProps(fieldName: string, error?: string): {
    id: string;
    role: 'alert';
    'aria-live': 'polite';
    children?: string;
}

Get accessible error message props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`error`optional	`string`	- Error message

getDescriptionProps

function getDescriptionProps(fieldName: string, description?: string): {
    id: string;
    children?: string;
}

Get accessible description props

Parameter	Type	Description
`fieldName`	`string`	- Field name
`description`optional	`string`	- Description text

announceToScreenReader

function announceToScreenReader(message: string, priority?: 'polite' | 'assertive'): void

Announce message to screen readers

Parameter	Type	Description
`message`	`string`	- Message to announce
`priority`optional	`'polite' \| 'assertive'`	- Announcement priority ('polite' or 'assertive')

announceValidationError

function announceValidationError(fieldName: string, error: string): void

Validation error announcer for screen readers

Parameter	Type	Description
`fieldName`	`string`
`error`	`string`

announceFormSubmission

function announceFormSubmission(success: boolean, message?: string): void

Form submission announcer for screen readers

Parameter	Type	Description
`success`	`boolean`
`message`optional	`string`

enhanceErrorMessage

function enhanceErrorMessage(error: string): EnhancedError

Enhance an error message with suggestions

Parameter	Type	Description
`error`	`string`	- Original error message

formatError

function formatError(error: string | EnhancedError, format?: 'message' | 'suggestion' | 'full'): string

Format error message with suggestion

Parameter	Type	Description
`error`	`string \| EnhancedError`	- Error message or enhanced error
`format`optional	`'message' \| 'suggestion' \| 'full'`	- Format type

createValidationError

function createValidationError(message: string, suggestion?: string, code?: string): EnhancedError

Create a validation error with suggestion

Parameter	Type	Description
`message`	`string`	- Error message
`suggestion`optional	`string`	- Helpful suggestion
`code`optional	`string`	- Error code

createFormSnapshot

function createFormSnapshot<Values extends Record<string, unknown>>(formState: FormState<Values>, initialValues: Values): FormSnapshot<Values>

Create a form state snapshot for DevTools inspection

Parameter	Type	Description
`formState`	`FormState<Values>`	- Current form state
`initialValues`	`Values`	- Initial form values (for dirty detection)

logFormState

function logFormState<Values extends Record<string, unknown>>(formId: string, snapshot: FormSnapshot<Values>): void

Log form state to console in a developer-friendly format

Parameter	Type	Description
`formId`	`string`	- Form identifier
`snapshot`	`FormSnapshot<Values>`	- Form snapshot

exposeFormToWindow

function exposeFormToWindow<Values extends Record<string, unknown>>(formId: string, snapshot: FormSnapshot<Values>): void

Expose form state to window for DevTools access

Parameter	Type	Description
`formId`	`string`	- Form identifier
`snapshot`	`FormSnapshot<Values>`	- Form snapshot

diffFormState

function diffFormState<Values extends Record<string, unknown>>(before: FormSnapshot<Values>, after: FormSnapshot<Values>): {
    changedFields: string[];
    newErrors: Partial<Record<Path<Values>, string>>;
    clearedErrors: string[];
    touchedFields: string[];
}

Create a form state diff between two snapshots

Parameter	Type	Description
`before`	`FormSnapshot<Values>`	- Previous snapshot
`after`	`FormSnapshot<Values>`	- Current snapshot

createPerformanceMonitor

function createPerformanceMonitor(): {
    startTimer: (operation: string) => () => void;
    getMetrics: () => Record<string, number>;
    logMetrics: () => void;
}

Create performance monitor for a form

Variables

ErrorMessages

{
    readonly required: (fieldName?: string) => string;
    readonly email: "Please enter a valid email address";
    readonly emailRequired: "Email address is required";
    readonly passwordTooShort: (minLength: number) => string;
    readonly passwordsMatch: "Passwords must match";
    readonly passwordWeak: "Password must include uppercase, lowercase, number, and special character";
    readonly minNumber: (min: number) => string;
    readonly maxNumber: (max: number) => string;
    readonly numberBetween: (min: number, max: number) => string;
    readonly minLength: (min: number) => string;
    readonly maxLength: (max: number) => string;
    readonly url: "Please enter a valid URL (e.g., https://example.com)";
    readonly phone: "Please enter a valid phone number";
    readonly date: "Please enter a valid date";
    readonly dateAfter: (date: string) => string;
    readonly dateBefore: (date: string) => string;
    readonly invalid: (fieldName?: string) => string;
}

Common error messages (pre-defined for consistency)

index_ErrorMessagestypeof ErrorMessages

index_announceFormSubmissiontypeof announceFormSubmission

index_announceToScreenReadertypeof announceToScreenReader

index_announceValidationErrortypeof announceValidationError

index_configureDebugtypeof configureDebug

index_createFormIdtypeof createFormId

index_createFormSnapshottypeof createFormSnapshot

index_createPerformanceMonitortypeof createPerformanceMonitor

index_createTimertypeof createTimer

index_createValidationErrortypeof createValidationError

index_debugFormCreatedtypeof debugFormCreated

index_debugFormStatetypeof debugFormState

index_debugStateUpdatetypeof debugStateUpdate

index_debugSubmissiontypeof debugSubmission

index_debugValidationtypeof debugValidation

index_debugValueChangetypeof debugValueChange

index_diffFormStatetypeof diffFormState

index_enhanceErrorMessagetypeof enhanceErrorMessage

index_exposeFormToWindowtypeof exposeFormToWindow

index_formatErrortypeof formatError

index_generateFieldIdstypeof generateFieldIds

index_getDebugConfigtypeof getDebugConfig

index_getDescriptionPropstypeof getDescriptionProps

index_getErrorPropstypeof getErrorProps

index_getFieldAriaPropstypeof getFieldAriaProps

index_getLabelPropstypeof getLabelProps

index_logFormStatetypeof logFormState

dist

Functions

useForm

function useForm<Values extends Record<string, unknown>>(options: UseFormOptions<Values>): UseFormReturn<Values>

Main useForm hook

Parameter	Type	Description
`options`	`UseFormOptions<Values>`

dist/types-Cd70yggL

Functions

getValueByPath

function getValueByPath<T>(obj: T, path: string): unknown

Get value at a nested path

Parameter	Type	Description
`obj`	`T`	- Object to get value from
`path`	`string`	- Dot-separated path (e.g., "user.profile.name")

setValueByPath

function setValueByPath<T>(obj: T, path: string, value: unknown): T

Set value at a nested path (immutably)

Parameter	Type	Description
`obj`	`T`	- Object to set value in
`path`	`string`	- Dot-separated path
`value`	`unknown`	- Value to set

Classes

FormStore

Form state store Manages form state with field-level subscription support. This enables isolated re-renders - only components that subscribe to a specific field will re-render when that field changes.

constructor(initialValues: Values, computed?: Partial<Record<keyof Values, (values: Values) => unknown>>)

Method	Return Type	Description
`getVersion()`	`number`	Get current version (for useSyncExternalStore)
`getValues()`	`Values`	Get current form values
`getValue(name)`	`ValueAtPath<Values, P>`	Get value at specific field path
`setValue(name, value)`	`void`	Set value at specific field path
`getError(name)`	`string \| undefined`	Get error for specific field
`setError(name, error)`	`void`	Set error for specific field
`getTouched(name)`	`boolean`	Get touched state for specific field
`setTouched(name, touched)`	`void`	Set touched state for specific field
`getFieldState(name)`	`FieldState<ValueAtPath<Values, P>>`	Get complete field state
`subscribe(name, callback)`	`Unsubscribe`	Subscribe to field changes Returns unsubscribe function
`subscribeToStore(callback)`	`() => void`	Subscribe to any store change (for form-level re-renders)
`startValidation(name)`	`AbortController`	Start async validation for a field
`endValidation(name)`	`void`	End async validation for a field
`cancelValidation(name)`	`void`	Cancel pending validation for a field
`isFieldValidating(name)`	`boolean`	Check if a specific field is validating
`isValidating()`	`boolean`	Check if any field is validating
`getValidatingFields()`	`string[]`	Get all fields currently validating
`reset(newInitialValues)`	`void`	Reset form to initial values
`getErrors()`	`Partial<Record<Path<Values>, string>>`	Get all errors
`getTouchedFields()`	`Partial<Record<Path<Values>, boolean>>`	Get all touched fields
`isDirty()`	`boolean`	Check if form is dirty (any field changed)
`isValid()`	`boolean`	Check if form is valid (no errors)

dist/types-Cd70yggL

Functions

getValueByPath

function getValueByPath<T>(obj: T, path: string): unknown

Get value at a nested path

Parameter	Type	Description
`obj`	`T`	- Object to get value from
`path`	`string`	- Dot-separated path (e.g., "user.profile.name")

setValueByPath

function setValueByPath<T>(obj: T, path: string, value: unknown): T

Set value at a nested path (immutably)

Parameter	Type	Description
`obj`	`T`	- Object to set value in
`path`	`string`	- Dot-separated path
`value`	`unknown`	- Value to set

Classes

FormStore

constructor(initialValues: Values, computed?: Partial<Record<keyof Values, (values: Values) => unknown>>)

Method	Return Type	Description
`getVersion()`	`number`	Get current version (for useSyncExternalStore)
`getValues()`	`Values`	Get current form values
`getValue(name)`	`ValueAtPath<Values, P>`	Get value at specific field path
`setValue(name, value)`	`void`	Set value at specific field path
`getError(name)`	`string \| undefined`	Get error for specific field
`setError(name, error)`	`void`	Set error for specific field
`getTouched(name)`	`boolean`	Get touched state for specific field
`setTouched(name, touched)`	`void`	Set touched state for specific field
`getFieldState(name)`	`FieldState<ValueAtPath<Values, P>>`	Get complete field state
`subscribe(name, callback)`	`Unsubscribe`	Subscribe to field changes Returns unsubscribe function
`subscribeToStore(callback)`	`() => void`	Subscribe to any store change (for form-level re-renders)
`startValidation(name)`	`AbortController`	Start async validation for a field
`endValidation(name)`	`void`	End async validation for a field
`cancelValidation(name)`	`void`	Cancel pending validation for a field
`isFieldValidating(name)`	`boolean`	Check if a specific field is validating
`isValidating()`	`boolean`	Check if any field is validating
`getValidatingFields()`	`string[]`	Get all fields currently validating
`reset(newInitialValues)`	`void`	Reset form to initial values
`getErrors()`	`Partial<Record<Path<Values>, string>>`	Get all errors
`getTouchedFields()`	`Partial<Record<Path<Values>, boolean>>`	Get all touched fields
`isDirty()`	`boolean`	Check if form is dirty (any field changed)
`isValid()`	`boolean`	Check if form is valid (no errors)

Unlimited AccessInstall as many Pool packages as you need.

Fund Real WorkEvery install you run sends revenue directly to the developer who built it.

Taxes calculated at checkout based on your location.

Insights

93/100Excellent

Version

1.0.0

Published

Repository

github.com(opens in new tab)

Website

github.com(opens in new tab)

LicenseMIT

Size599.44 KB

Files37

Node version>= 18

TypeScriptYes