TypeScript

TypeScript and the Type-Safe API

Formitiva provides first-class TypeScript support so your form definitions, custom components, validation handlers and submission handlers are all type-checked. This improves DX with autocomplete, inline documentation and compile-time safety.

What you get

• Strongly-typed FormDefinition and FieldDefinition shapes.
• Typed context hooks (useFormitivaContext) with typed definition, values, errors and helpers.
• Type-safe registration helpers for components, validation handlers and submission handlers.

Type-safe form definition (example)

import type { FormDefinition } from '@formitiva/react';

const contactForm: FormDefinition = {
	name: 'contactForm',
	displayName: 'Contact Form',
	version: '1.0.0',
	properties: [
		{
			type: 'text',
			name: 'fullName',
			displayName: 'Full Name',
			defaultValue: '',
			required: true,
			minLength: 2,
			maxLength: 100,
		},
		{
			type: 'email',
			name: 'email',
			displayName: 'Email Address',
			defaultValue: '',
			required: true,
		}
	]
};

TypeScript will warn you if you use an unknown property on a field or supply the wrong value type.

Registering typed components

import { registerComponent, InputComponentProps } from '@formitiva/react';

const CustomInput: React.FC<InputComponentProps> = ({ field, value, onChange, style, t }) => {
	return (
		<div style={style.container}>
			<label style={style.label}>{t(field.displayName)}</label>
			<input value={value as string} onChange={e => onChange(e.target.value)} style={style.input} />
		</div>
	);
};

registerComponent('custom', CustomInput);

The InputComponentProps type ensures the component receives the expected props (field metadata, current value, change handler, style helpers and translation helper).

Typed context hook

Use useFormitivaContext() to access typed form state and helpers:

import { useFormitivaContext } from '@formitiva/react';

function MyComponent() {
	const { definition, values, errors, setValue, validateField, t } = useFormitivaContext();
	// `definition` is `FormDefinition`
	// `values` and `errors` are typed records keyed by field name
}

Validation handlers (type-safe)

import { registerFieldValidationHandler, ValidationResult } from '@formitiva/react';

registerFieldValidationHandler('phoneValidator', (value: unknown): ValidationResult => {
	const phone = String(value ?? '');
	if (!/^\d{10}$/.test(phone)) {
		return { isValid: false, error: 'validation.invalidPhone' };
	}
	return { isValid: true };
});

Validation handlers return a ValidationResult which can include an error message key (for i18n) — keep messages as keys where possible so the UI can translate them via the app's t() function.

Submission handlers (type-safe)

import { registerSubmissionHandler, FormSubmissionHandler } from '@formitiva/react';

const submitHandler: FormSubmissionHandler = (definition, instanceName, values, t) => {
	// values is typed as Record<string, unknown>
	console.log('submit', { definition, instanceName, values });
	return undefined; // or return an error string
};

registerSubmissionHandler('mySubmit', submitHandler);

Types Provided

• FormitivaContextType — provider context shape (language, t, styles, definitionName).
• FormitivaProviderProps — props accepted by FormitivaProvider.
• DefinitionPropertyField — a property descriptor for ReactaDefinition (name, type, displayName, validation, layout, etc.).
• ReactaDefinition — form definition structure (name, version, displayName, properties[], handlers).
• ReactaInstance — persisted instance shape (name, definition, version, values).
• FormitivaProps — props for the top-level Formitiva component.
• FieldValueType — union of allowed field value types (boolean, number, string, arrays, unit tuple, File, etc.).
• ErrorType — error string or null.
• FieldCustomValidationHandler — single-field validator signature (fieldName, value, t) => string | undefined.
• FieldTypeValidationHandler — single-field validator signature for new type (field, value, t) => string | undefined.
• FormValidationHandler — cross-field validator signature (valuesMap, t) => string[] | undefined.
• FormSubmissionHandler — submission handler signature (definition, instanceName, valuesMap, t) => string[] | Promise<string[] | undefined>.
• InputOnChange<T> — generic input change callback (value: T | string, error: string | null) => void.
• BaseInputProps<TValue, TField> — base props for input components (field, value, onChange, onError).

Extensibility tips

• Extend field types in your app by re-exporting or augmenting the exported FieldDefinition/FormDefinition types so your domain-specific fields stay typed across code.
• Use typed registration helpers so custom components and handlers are checked at compile-time.

Benefits

• Catch errors early during development.
• Improved IDE autocomplete and inline docs.
• Safer refactors and clearer migration paths when upgrading Formitiva.

References

• See the interactive guide: /features/type-safe-api
• Implementation types (export entry): src/types or the package's type exports