API reference

Schema

Schema is used to describe form structure and validation. API consist of Schema, List and Property node types, each of those can contain metadata properties.

Common schema properties

All three node types share the same set of properties:

label
used to render <label> element
hint
used as a part of <label> element, usually contain detailed explanations of what input expected into the corresponding form element.
component
used to specify which form component to use to render a corresponding form element.
defaultValue
used as a default value for a form element.
validate
a function which validates transformed input value. Should return true in case of success and false in case of failure.

ReactForms.schema.Property

Property schema nodes are used to describe values such as strings, numbers, dates, …:

<Property />

In addition to common schema properties, Property supports the following ones:

input
specifies input component to use, if not provided then <input type="text" /> will be used instead.
type

Used to transform value representation from DOM domain to application domain and vice-versa. For example date type transforms Date objects into strings of YYYY-MM-DD format and vice-versa.

There are built-in types are available: string, number, date and array which can be referenced by its string name: <Property type="date" />.

Custom types can be made by defining an object with methods serialize(value) and deserialize(value).

required
Used as a shortcut for a validator which validates if a key is present inside an object (e.g. is not null).

ReactForms.schema.Schema

Nodes of type Schema are used to describe plain JavaScript objects (JSON objects). Children of the schema node describe keys of the object. Each child should have name property to define what key it describes:

<Schema>
  <Property name="a" />
  <Property name="b" />
</Schema>

The example above describe objects of shape {"a": …, "b": …}.

ReactForms.schema.List

List schema nodes are used to describe arrays. They can have only a single child which describes the schema of the elements of an array:

<List>
  <Property type="number" />
</List>

The example above describes the array of numbers [1, 2, 4, …].

In addition to common schema properties, List supports the following ones:

nonEmpty
Used as a shortcut for a validator which validates an array only if it has at least one element.

Functions

ReactForms.schema.isProperty(schema)
Check if schema node has type Property.
ReactForms.schema.isSchema(schema)
Check if schema node has type Schema.
ReactForms.schema.isList(schema)
Check if schema node has type List.

Components

ReactForms.Form

A component which represents an entire form: holds form value and validation state.

props

schema
Schema to use.
defaultValue
Value which is used to set default value of the form. This only used for first render of the component.
externalValidation
Validation structure which represents some external validation (like validation from a server side).
component
Component to render form as. By default <form /> component is used.
onChange(value, update)
Callback which fires on every change which results in a valid form value. value is a deserialized form value (according to schema) and update is an object with path (array which points to an updated field) and schema (schema node of an updated field) attributes.
onUpdate(value, isValid, update)
Callback which fires on every change. value is a deserialized form value (according to schema), isValid is a flag if form is in valid state after an update and update is an object with path (array which points to an updated field) and schema (schema node of an updated field) attributes.

methods

value()
Return form value object.

ReactForms.Field

A component which represents a single form field which contains a rendered input component along with <label /> element. This component is used to represent schema nodes of type Property.

ReactForms.Fieldset

A component which represents a fieldset. This component is used to represent schema nodes of type Schema.

ReactForms.RepeatingFieldset

A component which represents a list of fields/fieldsets. This component is used to represent schema nodes of type List.

ReactForms.FormFor

A “proxy” component which decides what component to render based on a current schema node it receives from a current form context.

Mixins

Each of the form components has the corresponding mixin which is used in an implementation. This allows to define custom form components without much boilerplate.

ReactForms.FormMixin

methods

value()
Return form value object.

ReactForms.FieldMixin

methods

value()
Return field value object.

ReactForms.FieldsetMixin

methods

value()
Return fieldset value object.

ReactForms.RepeatingFieldsetMixin

methods

value()
Return repeating fieldset value object.

Validation

ReactForms.validation.validate(schema, value)
Validate value against schema and return validation object which can be checked with isSuccess or isFailure function for validness.
ReactForms.validation.isSuccess(validation)
Return true is validation successful.
ReactForms.validation.isFailure(validation)
Return true is validation failed.

Input components

ReactForms.input.CheckboxGroup

Should be used for schema nodes with type array:

<Property type="array" input={<CheckboxGroup options={[...]} />} />