Form

v.7.1.10

Installation

yarn
pnpm
npm

yarn add @mercell/form-react

pnpm add @mercell/form-react

npm install --save @mercell/form-react

The Form has necessary peerDependencies, please make sure that you have them in your project

"@carbon/icons-react": "^10.49.0",
"@mercell/button-react": "^5.0.0",
"@mercell/checkbox-react": "^5.0.1",
"@mercell/cpv-selector-react": "^3.0.1",
"@mercell/date-picker-react": "^7.0.4",
"@mercell/dropdown-react": "^2.0.3",
"@mercell/field-error-react": "^6.0.0",
"@mercell/file-list-react": "^5.0.0",
"@mercell/file-uploader-react": "^4.0.0",
"@mercell/icon-button-react": "^undefined",
"@mercell/input-react": "^3.0.1",
"@mercell/modal-react": "^2.0.1",
"@mercell/nuts-selector-react": "^2.0.3",
"@mercell/radio-button-react": "^5.0.3",
"@mercell/tailwind": "^6.0.1",
"@mercell/textarea-react": "^2.0.1",
"classnames": "^2.3.1",
"date-fns": "^2.28.0",
"lodash": "^4.17.21",
"react": "^17.0.2" 

First render

Reusable form solution is based on Javascript objects/records which are similar to JSON schema solution.

As an example of simple render of text field, you need provide the schema which will match our FormSchema type.

import {
    FormWrapper,
    FormSchema,
} from '@mercell/form-react';
import {
    Button
} from '@mercell/button-react';

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const simpleSchema = {
    myField: {
        type: 'text',
    },
};
render (
    <FormWrapper
        schema={simpleSchema}
        onSubmit={onSubmit}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const simpleSchema = {
    myField: {
        type: 'text',
    },
};
render (
    <FormWrapper
        schema={simpleSchema}
        onSubmit={onSubmit}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

Result

Form properties and label

You can provide main label and any formProperties based on JSX.IntrinsicElements[form] type to the form.

import {
    FormWrapper,
    FormSchema,
} from '@mercell/form-react';
import {
    Button
} from '@mercell/button-react';

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema = {
    myField: {
        type: 'text',
    },
};
render (
    <FormWrapper
        schema={schema}
        formLabel='My form label'
        formProperties={{ className: 'm-40' }} // e.g. we can pass tailwind class and put margin on whole form
        onSubmit={onSubmit}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema = {
    myField: {
        type: 'text',
    },
};
render (
    <FormWrapper
        schema={schema}
        formLabel='My form label'
        formProperties={{ className: 'm-40' }} // e.g. we can pass tailwind class and put margin on whole form
        onSubmit={onSubmit}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

Result

Form with initial value

Initial values are crucial for already saved forms. The most important principle is you have to match the schema structure with values structure.

import {
    FormWrapper,
    FormSchema,
} from '@mercell/form-react';
import {
    Button
} from '@mercell/button-react';

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
    myField: {
        type: 'text',
    },
    anotherField: {
        type: 'checkbox',
        optionsList: () => [
            { label: 'Pizza', value: 'pizza' },
            { label: 'Burger', value: 'burger' }
            ]
    }
};
render (
    <FormWrapper
        schema={schema}
        onSubmit={onSubmit}
        initialValue={{ anotherField: ['pizza'], myField: 'Text example lorem ipsum' }}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
    myField: {
        type: 'text',
    },
    anotherField: {
        type: 'checkbox',
        optionsList: () => [
            { label: 'Pizza', value: 'pizza' },
            { label: 'Burger', value: 'burger' }
            ]
    }
};
render (
    <FormWrapper
        schema={schema}
        onSubmit={onSubmit}
        initialValue={{ anotherField: ['pizza'], myField: 'Text example lorem ipsum' }}
    >
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    </FormWrapper>
)

Result

childrenRender vs Children

To provide more information back to the developers of what is going on with the form during render action we created a gate to access specific values/flags.

Since React Final Form is subscription based form solution, here you can find information to which form state params you can subscribe.

By default each form subscribe to those information:

submitting: true,
pristine: true,
hasValidationErrors: true,
submitFailed: true,
submitErrors: true,
submitSucceeded: true,

but you can easily overwrite or add your own setup.

In all previous examples we were using normal children property where our Button was rendered and each submit happened as it should. However this time we will use childrenRender property to show you the access to the subscribed information of the form.

When you open console, you will see information after the form was rendered, and also after you click submit.

import {
    FormWrapper,
    FormSchema,
} from '@mercell/form-react';
import {
    Button
} from '@mercell/button-react';

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
 myField: {
        type: 'text',
    },
};
const childrenRender = ({
    submitting,
    pristine,
    hasValidationErrors,
    submitFailed,
    submitErrors,
    submitSucceeded,
}) => {
    console.log('childrenRender', {
        submitting,
         pristine,
         hasValidationErrors,
         submitFailed,
         submitErrors,
         submitSucceeded
    });
    return (
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    )
}
render (
    <FormWrapper
        schema={schema}
        onSubmit={onSubmit}
        childrenRender={childrenRender}
    />
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
 myField: {
        type: 'text',
    },
};
const childrenRender = ({
    submitting,
    pristine,
    hasValidationErrors,
    submitFailed,
    submitErrors,
    submitSucceeded,
}) => {
    console.log('childrenRender', {
        submitting,
         pristine,
         hasValidationErrors,
         submitFailed,
         submitErrors,
         submitSucceeded
    });
    return (
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    )
}
render (
    <FormWrapper
        schema={schema}
        onSubmit={onSubmit}
        childrenRender={childrenRender}
    />
)

Result

In the example below we will also track values. After each type in text field you will see new entry in console.log.

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
 myField: {
        type: 'text',
    },
};
const childrenRender = ({
    submitting,
    pristine,
    hasValidationErrors,
    submitFailed,
    submitErrors,
    submitSucceeded,
    values
}) => {
    console.log('childrenRender', {
        values
        submitting,
        pristine,
        hasValidationErrors,
        submitFailed,
        submitErrors,
        submitSucceeded
    });
    return (
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    )
}
render (
    <FormWrapper
        schema={schema}
        subscription={{ values: true }}
        onSubmit={onSubmit}
        childrenRender={childrenRender}
    />
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
 myField: {
        type: 'text',
    },
};
const childrenRender = ({
    submitting,
    pristine,
    hasValidationErrors,
    submitFailed,
    submitErrors,
    submitSucceeded,
    values
}) => {
    console.log('childrenRender', {
        values
        submitting,
        pristine,
        hasValidationErrors,
        submitFailed,
        submitErrors,
        submitSucceeded
    });
    return (
        <Button type='submit' scheme='primary'>
            Submit
        </Button>
    )
}
render (
    <FormWrapper
        schema={schema}
        subscription={{ values: true }}
        onSubmit={onSubmit}
        childrenRender={childrenRender}
    />
)

Result

AutoSave, Conditional render, Validations

All topics are documented in the utils section.

AutoSave information
Conditional render information
Validations information

Read only render method

This property is necessary to setup all possible readOnly type fields. What is really important to understand is that this method will be invoked on every occasion whenever you would like to render just a text regarding the values provided in form in specific fields.

As an example we will have 3 fields, one text, one checkbox, one select. And each of them we will 'convert' to the readOnly.

import {
    FormWrapper,
    FormSchema,
} from '@mercell/form-react';
import {
    Button
} from '@mercell/button-react';

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
    myField: {
        type: 'text',
    },
    anotherField: {
        type: 'checkbox',
        optionsList: () => [
            { label: 'Action movie', value: 'action' },
            { label: 'Thriller movie', value: 'thriller' }
        ]
    },
    thirdField: {
        type: 'select',
        optionsList: () => [
            { label: 'Pizza', value: 'pizza' }
            { label: 'Burger', value: 'burger' }
        ]
    }
};
const readOnlySchema: FormSchema = {
    myField: {
        type: 'readOnly',
    },
    anotherField: {
        type: 'readOnly',
        fieldOrigin: 'checkbox'
    },
    thirdField: {
        type: 'readOnly',
        fieldOrigin: 'select'
    }
};
render (
    <>
        <FormWrapper
            schema={schema}
            onSubmit={onSubmit}
            initialValue={{ myField: 'Test text', anotherField: ['action'], thirdField: 'pizza'}}
        >
            <Button type='submit' scheme='primary'>
                Submit
            </Button>
        </FormWrapper>
        <FormWrapper
            formLabel='Form with ReadOnly'
            formProperties={{ className: 'mt-4' }}
            schema={readOnlySchema}
            onSubmit={onSubmit}
            initialValue={{ myField: 'Test text', anotherField: ['action'], thirdField: 'pizza'}}
            readOnlyFieldRender={(readOnlyContent, name, restReadOnlyProperties, fieldOrigin, elementProperties) => <h2>{readOnlyContent}</h2>}
        />
    </>
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const schema: FormSchema = {
    myField: {
        type: 'text',
    },
    anotherField: {
        type: 'checkbox',
        optionsList: () => [
            { label: 'Action movie', value: 'action' },
            { label: 'Thriller movie', value: 'thriller' }
        ]
    },
    thirdField: {
        type: 'select',
        optionsList: () => [
            { label: 'Pizza', value: 'pizza' }
            { label: 'Burger', value: 'burger' }
        ]
    }
};
const readOnlySchema: FormSchema = {
    myField: {
        type: 'readOnly',
    },
    anotherField: {
        type: 'readOnly',
        fieldOrigin: 'checkbox'
    },
    thirdField: {
        type: 'readOnly',
        fieldOrigin: 'select'
    }
};
render (
    <>
        <FormWrapper
            schema={schema}
            onSubmit={onSubmit}
            initialValue={{ myField: 'Test text', anotherField: ['action'], thirdField: 'pizza'}}
        >
            <Button type='submit' scheme='primary'>
                Submit
            </Button>
        </FormWrapper>
        <FormWrapper
            formLabel='Form with ReadOnly'
            formProperties={{ className: 'mt-4' }}
            schema={readOnlySchema}
            onSubmit={onSubmit}
            initialValue={{ myField: 'Test text', anotherField: ['action'], thirdField: 'pizza'}}
            readOnlyFieldRender={(readOnlyContent, name, restReadOnlyProperties, fieldOrigin, elementProperties) => <h2>{readOnlyContent}</h2>}
        />
    </>
)

Result

There is also a possibility to use readOnly type with value passed directly in schema, if e.g. you don't have the value saved in initialValue property,

Live Editor

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const readOnlySchema: FormSchema = {
    myField: {
        type: 'readOnly',
        readOnlyContent: 'Test text'
    },
    anotherField: {
        type: 'readOnly',
        fieldOrigin: 'checkbox'
        readOnlyContent: 'Checkbox default value'
    },
    thirdField: {
        type: 'readOnly',
        fieldOrigin: 'select',
        readOnlyContent: 'Select default value'
    }
};
render (
    <FormWrapper
        formLabel='Form with ReadOnly'
        formProperties={{ className: 'mt-4' }}
        schema={readOnlySchema}
        onSubmit={onSubmit}
        readOnlyFieldRender={(readOnlyContent, name, restReadOnlyProperties, fieldOrigin, elementProperties) => <h2>{readOnlyContent}</h2>}
    />
)

// You can play with code, with HTML tags and text as much as you want!
async function onSubmit(values, form, callback) {
    await(300);
    alert(JSON.stringify(values));
}
const readOnlySchema: FormSchema = {
    myField: {
        type: 'readOnly',
        readOnlyContent: 'Test text'
    },
    anotherField: {
        type: 'readOnly',
        fieldOrigin: 'checkbox'
        readOnlyContent: 'Checkbox default value'
    },
    thirdField: {
        type: 'readOnly',
        fieldOrigin: 'select',
        readOnlyContent: 'Select default value'
    }
};
render (
    <FormWrapper
        formLabel='Form with ReadOnly'
        formProperties={{ className: 'mt-4' }}
        schema={readOnlySchema}
        onSubmit={onSubmit}
        readOnlyFieldRender={(readOnlyContent, name, restReadOnlyProperties, fieldOrigin, elementProperties) => <h2>{readOnlyContent}</h2>}
    />
)

Result

Types, definitions, etc.

FormTypeProps

export type FormTypeProps = {
   schema: FormSchema;
   formProperties?: JSX.IntrinsicElements['form'];
   formLabel?: ReactNode;
   initialValue?: Record<string, any>;
   onAutoSave?: (formValues: Record<string, any>) => void;
   autoSaveThrottleDelay?: number;
   childrenRender?: (
       props: FormState<any> & FormApi & Partial<FormProps>;
   ) => ReactNode;
   showErrorsOnInitialRender?: boolean;
   validationCallback?: (
       fieldValue: any,
       validationSchema: AnySchema
   ) => string;
   readOnlyFieldRender: (
       readOnlyContent: any,
       name: string,
       restReadOnlyProperties: ReadOnlyFieldStructure,
       fieldOrigin?: FieldOrigin,
       elementProperties?: DetailedHTMLProps<
           HTMLAttributes<HTMLElement>,
           HTMLElement
       >
   ) => ReactNode;
} & FormProps

FormProps are properties allowed by React Final Form

AnySchema is property allowed by yup library

Form

Installation​

The Form has necessary peerDependencies, please make sure that you have them in your project

First render​

Form properties and label​

Form with initial value​

childrenRender vs Children​

AutoSave, Conditional render, Validations​

Read only render method​

Types, definitions, etc.​

Installation

First render

Form properties and label

Form with initial value

childrenRender vs Children

AutoSave, Conditional render, Validations

Read only render method

Types, definitions, etc.