@rn-form/form v3.0.1

Click here to Example

API

Form or Form.ScrollView Support scroll to the first error field

type Form = {
  form?: FormInstance;
  colon?: boolean;
  initialValues?: {[key: string]: any};
  labelAlign?: 'left' | 'right';
  name?: string;
  preserve?: boolean;
  requiredMark?: boolean | string;
  requiredMarkStyle?: TextStyle;
  requiredMarkPosition?: 'before' | 'after';
  validateMessages?: ValidateMessages;
  validateTrigger?: 'onChange' | 'onBlur';
  onValuesChange?: (values: {[key: string]: any}) => void;
  errorStyle?: TextStyle;
  ignoreWarning?: boolean
};

• form <FormInstance> Click to here

Form control instance created by Form.useForm() with Hooks
or Form.create(Component) with Class Component.
Automatically created when not provided

• colon <Boolean>

Configure the default value of colon for Form.Item.
Indicates whether the colon after the label is displayed
(only effective when prop layout is horizontal)

• initialValues {[key: string]: any}

Default Values by form

• labelAlign <'left' | 'right'>

The text align of label of all items

• name <String>

Form name. Will be the prefix of Field id

• preserve <Boolean>

Keep field value even when field removed

• requiredMark <Boolean | String>

Required mark style. Can use required mark or optional mark.
You can not config to single Form.Item since this is a Form level config

• requiredMarkStyle <TextStyle>

Custom mark styleSheet

• requiredMarkPosition <'before' | 'after'>

- Default: before

Config position required mark or optional mark

• validateMessages <ValidateMessages>

Validation prompt template

const validateMessages = {
  required: '${name} is required',
  whitespace: '${name} cannot be empty',
  len: '${name} must be exactly ${len} characters',
  min: '${name} must be less than ${min}',
  max: '${name} cannot be greater than ${max}',
  pattern: '${name} does not match pattern ${pattern}',
  enum: '${name} must be one of ${enum}',
};

• validateTrigger <'onChange' | 'onBlur'>

- Default: onChange

Config field validate trigger

• onValuesChange (values: {[key: string]: any}) => void

Trigger when value updated

• errorStyle <TextStyle>

Configure the label message error form

• ignoreWarning <boolean>

Remove all warnings from Form

Form.Item

! Must be inside the Form

type FormItem = {
  colon?: boolean;
  getValueProps?: (value: any) => any;
  hidden?: boolean;
  initialValue?: any;
  labelAlign?: 'left' | 'right';
  validateFirst?: boolean;
  valuePropName?: 'number' | 'string' | 'checked';
  children: React.ReactNode |
  (
    handle: {
      onChangeValue: (value: any) => any;
      onBlur: () => any;
      value?: any;
      error?: string;
    }
  ) => JSX.Element | Promise<JSX.Element>
  style?: ViewStyle | ViewStyle[];
  errorStyle?: TextStyle;
  labelStyle?: TextStyle;
  preserve?: boolean;
  name: string;
  label?: string;
  rules?: Rule[];
  required?: boolean;
  validateTrigger?: 'onChange' | 'onBlur';
  allowAddItemWhenChangeName?: boolean;
  keepValueWhenChangeName?: boolean;
};

• name <String> * Required

Field name

• label <String>

Label text

• initialValue <any>

Config sub default value. Form initialValues get higher priority when conflict

• required <Boolean>

Display required style. It will be generated by the validation rule

• validateFirst <Boolean >

Whether stop validate on first rule of error for this field.
Will parallel validate when parallel cofigured

• validateTrigger <'onChange' | 'onBlur'>

Default: onChange

When to validate the value of children node

• rules <Rule[]>

type Rule = {
  required?: boolean; //Display required style. It will be generated by the validation rule
  enum?: any[]; //Match enum value. You need to set type to enum to enable this
  len?: number; //Length of string
  max?: number; // max of number
  min?: number; // min of number
  message?: string; //Error message. Will auto generate by template if not provided
  pattern?: RegExp; //Regex pattern
  transform?: (value: any) => any; //Transform value to the rule before validation
  validateTrigger?: 'onChange' | 'onBlur';
  validator?: (
    rule: Rule & {name: string},
    value: any,
    callback: (errorMessage?: string) => void,
  ) => Promise<void | Error>; //Customize validation rule. Accept Promise as return. See example
  whitespace?: boolean; //Failed if only has whitespace
};

//Rules for field validation.
import React, {Component} from 'react';
import Form, {Input} from '@form-rn/form';

class App extends Component {
  render() {
    return (
      <Form.ScrollView>
        <Form.Item
          required={true}
          validateTrigger="onBlur"
          name="field_name"
          label="Example Children type of JSX.Element"
          initialValue="initialValue"
          rules={[
            {required: true, message: 'Field is required'},
            {
              validator: (rule, value) => {
                if (value) {
                  return Promise.resolve();
                }
                return Promise.reject('Field is required');
              },
              validateTrigger: 'onBlur',
            },
            {
              validator: (rule, value, callback) => {
                if (value) {
                  callback();
                } else {
                  callback('Field is required');
                }
              },
            },
          ]}>
          <Input placeholder="2" />
        </Form.Item>
      </Form.ScrollView>
    );
  }
}

• children <JSX.Element | ({onChangeValue, value, onBlur, error}) => any>

//children was supported type of functional
//onBlur must be required when rules.trigger or validateTrigger is onBlur
import React, {Component} from 'react';
import Form, {Input} from '@form-rn/form';

class App extends Component {
  render() {
    return (
      <Form.ScrollView>
        <Form.Item
          name="children"
          initialValue="12"
          label="Example Children type of function">
          {({onChangeValue, value, onBlur, error}) => {
            console.log(value, onBlur, error);
            return (
              <Input
                placeholder="2"
                onChangeValue={onChangeValue}
                value={value}
                onBlur={onBlur}
                error={error}
              />
            );
          }}
        </Form.Item>
      </Form.ScrollView>
    );
  }
}

• colon <Boolean>

Used with label, whether to display : after label text.

• getValueProps <(value: any) => any>

Additional props with sub component
Convert data onChange

• valuePropName <'number' | 'string' | 'checked'>

Props of children node, for example, the prop of Switch is 'checked'.
This prop is an encapsulation of getValueProps, which will be invalid after customizing getValueProps

• hidden <Boolean>

Whether to hide Form.Item (still collect and validate value)

• labelAlign <'left' | 'right'>

The text align of label

• style <ViewStyle | ViewStyle[]>

Stylesheet Field

• errorStyle <TextStyle>

Configure the label message error form

• labelStyle <TextStyle>

Configure the label stylesheet

• preserve <Boolean>

Keep field value even when field removed

• allowAddItemWhenChangeName <Boolean>

- When the name changes in the props, a new Form Item will be added instead of replacing the name

• keepValueWhenChangeName <Boolean>

- Support props allowAddItem WhenChangeName. If true, it will keep the value for the new name

FormInstance

If you code like below then all the function of FormInstance will return about under an object like {idForm1: values, idForm2: values}

<Form name="idForm1">
  <Form.Item name="field_name" label="Example">
    <Input placeholder="2" />
  </Form.Item>
</Form>
<Form name="idForm2">
  <Form.Item name="field_name2" label="Example2">
    <Input placeholder="2" />
  </Form.Item>
</Form>

• getFieldError (name: string) => Promise<(string | undefined)>

Get the error messages by the field name

• getFieldsError

(names?: string[]) => Promise<{[key: string]: string | undefined}>

Get the error messages by the fields name. Return as an array

• getFieldsValue

(names?: string[], filter?: (meta: { touched: boolean, validating: boolean }) => boolean) => Promise<any>

Get values by a set of field names.
Return according to the corresponding structure.
Default return mounted field value, but you can use getFieldsValue() to get all values

• getFieldValue (name: string) => Promise<any>

Get the value by the field name

• isFieldsTouched (names?: string[], allTouched?: boolean) => Promise<boolean>

Check if fields have been operated.
Check if all fields is touched when allTouched is true

• isFieldTouched (name: string) => Promise<boolean>

Check if a field has been operated

• isFieldValidating (name: string) => Promise<boolean>

Check field if is in validating

• resetFields (fields?: string[]) => Promise<void>

Reset fields to initialValues

• setFields (fields: FieldData[]) => Promise<void>

type FieldData = {
  error?: string; //Error messages
  name: string; //Field name path;
  touched?: boolean; //Whether is operated
  validating?: boolean; //Whether is in validating
  value: any; //Field value
}

Set fields status

• setFieldValue (name: string, value: any) => Promise<any>

Set fields value(Will directly pass to form store.
If you do not want to modify passed object, please clone first)

• setFieldsValue (values: {[key: string]: any}) => Promise<any>

Set fields value(Will directly pass to form store.
If you do not want to modify passed object, please clone first).

• validateFields (names?: string[]) => Promise<ValueValidateField>

type ValueValidateField = {
  values: {
    [key: string]: any;
  };
  errors?: {
    [key: string]: {
      errors: string[];
      layout: LayoutRectangle;
    };
  }[];
};

Validate fields and return errors and values

Input <TextInputProps>

https://reactnative.dev/docs/textinput

• error <Boolean>

Preview border error input

• style <ViewStyle>

Stylesheet wrap view Input

• styleInput <TextStyle>

Stylesheet Input

Radio

RadioGroup

Example

//Function Componet
import React from 'react';
import Form, {Input} from '@form-rn/form';
import {Button} from 'react-native';

const App = () => {
  const form = useForm();

  return (
    <Form.ScrollView initialValues={{example: 'example'}}>
      <Form.Item name="example" initialValue="12" label="Example">
        <Input placeholder="2" />
      </Form.Item>
      <Form.Item name="radioGroup" label="Login2" required validateFirst>
        <RadioGroup>
          <Radio value={1} label="radio 1" />
          <Radio value={2} label="radio 2" />
          <Radio value={3} label="radio 3" />
        </RadioGroup>
      </Form.Item>
      <Form.Item name="radio" label="Login2" required validateFirst>
        <Radio label="radio 1" />
      </Form.Item>
      <Button
        title="Get Value"
        onPress={async () => {
          const error = await form.getFieldError();
          const errors = await form.getFieldsError();
          const errorsWithNames = await form.getFieldsError(['example']);
          const values = await form.getFieldsValue();
          const valuesWithNames = await form.getFieldsValue(['example']);
          const valuesWithFilter = await form.getFieldsValue(
            undefined,
            (touched, validating) => touched && validating,
          );
          const value = await form.getFieldValue('example');
          const isToucheds = await form.isFieldsTouched(undefined, true);
          const isTouched = await form.isFieldTouched('example');
          const isValidating = await form.isFieldValidating('example');
          const data = await form.validateFields();
          if (Array.isArray(data)) {
            console.log('data is array', data);
          } else console.log(data);
        }}
      />
      <Button
        title="Control Value"
        onPress={async () => {
          form.resetFields();
          form.resetFields(['example']);
          form.setFields([
            {
              name: 'example',
              value: 'example1',
              touched: true,
              validating: true,
            },
          ]);
          form.setFieldValue('example', 'example1');
          form.setFieldsValue({example: 'example1'});
        }}
      />
    </Form.ScrollView>
  );
};

export default App;


//Class Component
import React from 'react';
import Form, {Input} from '@form-rn/form';
import {Button} from 'react-native';
class App extends Component<{form: FormInstance}> {
  render() {
    const {form} = this.props;
    return (
      <Form.ScrollView initialValues={{example: 'example'}}>
        <Form.Item name="example" initialValue="12" label="Example">
          <Input placeholder="2" />
        </Form.Item>
        <Button
          title="Get Value"
          onPress={async () => {
            const error = await form.getFieldError();
            const errors = await form.getFieldsError();
            const errorsWithNames = await form.getFieldsError(['example']);
            const values = await form.getFieldsValue();
            const valuesWithNames = await form.getFieldsValue(['example']);
            const valuesWithFilter = await form.getFieldsValue(
              undefined,
              (touched, validating) => touched && validating,
            );
            const value = await form.getFieldValue('example');
            const isToucheds = await form.isFieldsTouched(undefined, true);
            const isTouched = await form.isFieldTouched('example');
            const isValidating = await form.isFieldValidating('example');
            const data = await form.validateFields();
            if (Array.isArray(data)) {
              console.log('data is array', data);
            } else console.log(data);
          }}
        />
        <Button
          title="Control Value"
          onPress={async () => {
            form.resetFields();
            form.resetFields(['example']);
            form.setFields([
              {
                name: 'example',
                value: 'example1',
                touched: true,
                validating: true,
              },
            ]);
            form.setFieldValue('example', 'example1');
            form.setFieldsValue({example: 'example1'});
          }}
        />
      </Form.ScrollView>
    );
  }
}

export default Form.create(App);


// multiple Form
import React from 'react';
import Form, {Input} from '@form-rn/form';
import {Button} from 'react-native';
const App = () => {
  const form1 = Form.useForm()
  const form2 = Form.useForm()
  const form3 = Form.useForm()
  return (
    <Form form={form1}>
      <Form.Item name="example" initialValue="12" label="Example">
        <Input placeholder="2" />
      </Form.Item>
    </Form>
    <Form form={form2}>
      <Form.Item name="example" initialValue="12" label="Example">
        <Input placeholder="2" />
      </Form.Item>
      <Form form={form3}>
        <Form.Item name="example" initialValue="12" label="Example">
          <Input placeholder="2" />
        </Form.Item>
      </Form>
    </Form>
    <Button
      title="Control Value"
      onPress={async () => {
        form1.resetFields();
        form2.resetFields();
        form3.resetFields();
      }}
    />
  )
}