Form

Form-library-agnostic form wrapper that connects DocyField components to any state management library.

iOSAndroid

Preview Form on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-form

DocyForm is a form-library-agnostic wrapper that connects DocyField* components to any form state management library via the adapter pattern. You implement a FormAdapter interface for your chosen library (react-hook-form, TanStack Form, etc.), and DocyForm handles the wiring.

Usage

With react-hook-form

import { DocyForm, DocyFormField } from '@/components/docyrus-native/form';
import { DocyFieldText } from '@/components/docyrus-native/form-fields/docy-field-text';
import { DocyFieldEmail } from '@/components/docyrus-native/form-fields/docy-field-email';

// Create adapter from your form library
const adapter = createReactHookFormAdapter({
  defaultValues: { name: '', email: '' },
  onSubmit: (data) => console.log(data),
});

<DocyForm adapter={adapter}>
  {({ handleSubmit }) => (
    <>
      <DocyFormField name="name">
        <DocyFieldText name="name" label="Full Name" />
      </DocyFormField>

      <DocyFormField name="email">
        <DocyFieldEmail name="email" label="Email" />
      </DocyFormField>

      <Button onPress={handleSubmit}>Submit</Button>
    </>
  )}
</DocyForm>

Compound Fields

For fields that manage multiple form values (e.g. DocyFieldMoney needs both amount and currency):

<DocyFormField name="price" compoundFields={{ currency: 'price_currency' }}>
  <DocyFieldMoney name="price" label="Price" />
</DocyFormField>

API Reference

DocyForm

Prop	Type	Default	Description
`adapter`	`FormAdapter<T>`	—	Required. Form library adapter
`children`	`ReactNode \| (methods) => ReactNode`	—	Form content. Render-prop provides `handleSubmit` and `reset`
`className`	`string`	—	Container style

DocyFormField

Prop	Type	Default	Description
`name`	`string`	—	Required. Field name in the form
`children`	`ReactElement`	—	Required. DocyField component to connect
`validations`	`DocyFieldValidationRule[]`	—	Additional validation rules
`defaultValue`	`unknown`	—	Default value for this field
`compoundFields`	`Record<string, string>`	—	Maps prop names to additional form field names

FormAdapter Interface

Implement this interface to plug in your form library:

Method	Signature	Description
`FormWrapper`	`(props: { children: ReactNode }) => ReactElement`	Wraps children with library-specific provider
`getValue`	`(name: string) => unknown`	Get current field value
`setValue`	`(name: string, value: unknown) => void`	Set field value programmatically
`getError`	`(name: string) => string \| undefined`	Get field error message
`getFieldProps`	`(name: string) => FormAdapterFieldProps`	Get props for a field (value, onChange, onBlur, error)
`handleSubmit`	`() => void \| Promise<void>`	Run validation and submit
`reset`	`(values?: Partial<T>) => void`	Reset form to defaults
`getValues`	`() => T`	Get all current form values

Hooks

Hook	Returns	Description
`useFormAdapter<T>()`	`FormAdapter<T>`	Access the form adapter from within DocyForm
`useSimpleFormAdapter<T>(options)`	`FormAdapter<T>`	Local-state adapter (no form library)

`useSimpleFormAdapter` options

Option	Type	Default	Description
`defaultValues`	`T`	required	Initial values
`onSubmit`	`(values: T) => void \| Promise<void>`	—	Called by `handleSubmit` once validation passes
`validations`	`Partial<Record<keyof T, string[]>>`	—	Validation tokens per field (`required`, `minLength:N`, `maxLength:N`, `pattern:RE`, `min:N`, `max:N`), enforced on submit with the shared token parser. Errors surface through `getError` / `getFieldProps().error` and clear when the field changes
`labels`	`Partial<Record<keyof T, string>>`	field name	Labels used in validation messages

For schema-driven forms (layout sections, computed fields, actions) use useDynamicFormView instead.

Components

Component	Description
`DocyForm`	Form wrapper with adapter context
`DocyFormField`	Connects a DocyField component to the form adapter

Type Exports

Type	Description
`DocyFormProps`	Props for DocyForm component
`DocyFormFieldProps`	Props for DocyFormField component
`FormAdapter`	Form library adapter interface
`FormAdapterFieldProps`	Field props returned by adapter (`{ name, value, onChange, onBlur, error }`)