easy-mobx-form
Easy form building library based on mobx-react
Installing
yarn add easy-modx-form
or
npm install easy-modx-form
Components
Form
Main form component. Setups contexts for the inner elements (such as inputs, buttons and other components).
parameters:
- store (FormStore) - form store instance
- initialValues - object with initial values or Promise which will resolve such object
- submit (SubmitCallback) - submit callback
- validate? (ValidateCallback) - validate callback
- forceValidation? (boolean = false) - force validation right after initializing form
- availability? (AvailabilityCallback) - availability callback. Returns the list of fields which should be disabled
- forceAvailability? (boolean = false) - force availability callback
Form validation works along with per-field validation but have higher priority. Form validation could be asynchronous.
Form examples
import React from "react";
import ReactDOM from "react-dom";
import { Form, createFormStore, Submit, FieldText } from "eazy-modx-form";
const form = createFormStore();
const App: React.FC = () => (
<Form
store={form}
initialValues={initializationFn}
submit={submitFn}
validate={validationFn}
>
<FieldText name="name" />
<Submit>Submit</Submit>
</Form>
);
ReactDOM.render(
App,
document.getElementById("external-module-root")
)FieldText
Basic text field component.
parameters:
- name (string) - name of the form element
- validate (FieldValidator) - synchronous field validation function
- className? (string) - className string value which will be added to input element
...
<Form store={form}>
...
<FormText
name="name"
/>
...
</Form>
...FieldTextArea
Basic textarea field component.
parameters: Same as for FieldText
FieldCheck
Basic checkbox field component.
parameters: Same as for FieldText
FieldRadio
Basic radio field component.
parameters: Same as for FieldText
- value (number | string) - value of the radio element
Field
General component for build your own custom field components
parameters:
- name (string) - name of the form element
- component: FieldRenderer;
- validate? (FieldValidator) - synchronous field validation function
- data? (object) -
objectwhich will be passed into field renderer component
Example (Twitter Bootstrap based form element)
import React from "react";
import { Field } from "easy-mobx-form";
type TBTextFieldData = {
placeholder?: string;
};
const TBTextFieldRenderer: FieldRenderer<TBTextFieldData> = (props) => {
const {
value,
error,
onChange,
disabled,
pristine,
forceError,
initializing,
name,
} = props;
const handleChange = (e: React.SyntheticEvent<HTMLInputElement>) => {
onChange(e.currentTarget.value);
};
return (
<>
<input
type="text"
name={name}
onChange={handleChange}
className="form-control"
value={value || ""}
disabled={disabled || initializing}
/>
{
error && (forceError || !pristine)
? <small class="form-text text-muted">{error}</small>
: null
}
</>
);
}
export const TBTextField: React.FC<BaseFieldComponent & {
data?: TBTextFieldData;
// custom properties
label: string;
}> = (props) => {
return (
<div class="form-group">
<label>{props.label}</label>
<Field
component={TBTextFieldRenderer}
name={props.name}
validate={props.validate}
data={props.data}
/>
</div>
);
};Submit
Submit button
parameters:
- type ("button" | "submit") - type of the button
- name? (string) - name of the field. will be used for saving button value on submit
- value? (string) - if name is set, than this value will be saved in form values on click
- className? (string) - className for the
buttonelement
import React from "react";
import { Form, Submit } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Submit name="submit" value="update" className="btn btn-default">Update</Submit>
<Submit name="submit" value="delete" className="btn btn-danger">Delete</Submit>
</Form>
);Reset
Reset button. Restore form values to the initial
parameters:
- className? (string)
import React from "react";
import { Form, Reset } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Reset className="btn btn-default">Reset</Submit>
</Form>
);Errors
Component for rendering the list of validation errors
parameters:
- wrapperComponent? (React.FC) - component which should be rendered around the items
- itemComponent? (React.FC<{ name: string; message: string }>) - component for decorating error message
import React from "react";
import { Form, Errors } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Errors />
</Form>
);By default will renders simple list of errors:
<ul>
<li>fieldName1: Error message 1</li>
<li>fieldName2: Error message 2</li>
</ul>Error
Component for rendering single error message (returned by validation)
parameters:
- name (string) - name of the field
- component? (React.FC) - error message decorator component
Initialized
Wrapper component which children will be rendered only when form is initialized. Opposite to Initializing
import React from "react";
import { Form, Initialized } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Initialized>
some form components
</Initialized>
</Form>
);Initializing
Wrapper component which children will be rendered when form is initializing (i.e. loading data). Opposite to Initialized
import React from "react";
import { Form, Initializing } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Initializing>
<SomeLoaderComponent />
</Initializing>
</Form>
);Submitting
Component which children will be rendered while form is submitting.
import React from "react";
import { Form, Submitting } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Submitting>
Submitting...
</Submitting>
</Form>
);SubmitSuccessMessage
Helper component for rendering successful submit results.
properties:
- component? (SubmitSuccessComponent) - submit message renderer
import React from "react";
import { Form, SubmitSuccessComponent } from "eazy-modx-form";
type SubmitResult = {
message: string;
id: number;
};
const SubmitSucessRenderer: SubmitSuccessComponent<SubmitResult> = (props) => (
<div className="alert alert-success">
Success [{props.result.id}]: {props.result.message}
</div>
)
const App: React.FC = () => (
<Form store={form}>
<SubmitSuccessMessage
component={SubmitSucessRenderer}
/>
</Form>
);SubmitErrorMessage
Helper component for rendering submitting errors
properties:
- component? (SubmitErrorComponent) - error message renderer
import React from "react";
import { Form, SubmitErrorMessage } from "eazy-modx-form";
type SubmittingError = {
message: string;
};
const SubmitErrorRenderer: SubmitErrorComponent<SubmittingError> = (props) => (
<div className="alert alert-error">
Error: {props.result.message}
</div>
)
const App: React.FC = () => (
<Form store={form}>
<SubmitErrorComponent
component={SubmitErrorRenderer}
/>
</Form>
);Validating
Renders its children while form is validation (i.e. when async validation is implemented)
import React from "react";
import { Form, Validating } from "eazy-modx-form";
const App: React.FC = () => (
<Form store={form}>
<Validating>
Wait please...
</Submitting>
</Form>
);Values
Component for in-place accessing to the form values
import React from "react";
import { Form, Values, createFormStore, Submit } from "eazy-modx-form";
type FormValues = {
firstName: string;
lastName: string;
};
const form = createFormStore<FormValues>();
const initialValues = {
firstName: "John",
lastName: "Wick",
};
const App: React.FC = () => (
<Form
store={form}
initialValues={initialValues}
>
<Values>
{(values: FormValues) => (
<div>
<div>First name: {values.firstName}</div>
<div>Last name: {values.lastName}</div>
</div>
)}
</Values>
<div>
<FormText name="firstName" />
<FormText name="lastName" />
</div>
<Submit>Submit</Submit>
</Form>
);
