An insect-based module for creating controlled web forms for React.

• Easy to write; easy to read
• Pre-packed with front-end formatters and validators
• Auto-injects styles (override without using !important)
• Easy to customize
• Mirrors HTML syntax

currently in alpha — use with caution

This package requires that your project uses React

Controlled form elements as React components

See Live Demo

Installation

React Formian is distributed via npm, with styles distributed on UNPKG

npm install react react-formian

Usage

import React from 'react';
import ReactDOM from 'react-dom';
import Formian from 'react-formian';

const submitHandler = function(formData) {
	console.log('hello world', formData)
}

ReactDOM.renderComponent(
  <Formian.Form onSubmit={submitHandler}>
  	<h1>My Form Title</h1>
	<Formian.Name />
	<Formian.Email />
	<Formian.Checkbox
		name="agree"
		labelText="Aren't ants amazing?"
		required={false}
	/>
	<Formian.Submit />
	<p>My legal text</p>
  </Formian.Form>,
  document.getElementById('main')
)

Styles

Styles for Formian elements are dynamically injected. Prevent their injection and write your own, simply by adding customStyles={true} to your Formian.Form element.

You can also pre-require Formain's styles by adding a stylesheet link to your HTML document and pointing the href to https://unpkg.com/react-formian@[your version]/build/style.css, and then setting customStyles to true, as above.

Each container is wrapped in an identical manner, with a div that has a class of input-container as well as the input type and subtype.

Props

Props in brackets ([ ]) are optional

Formian.Form Component API

All form input elements are children of Formian.Form. You can also put anything else you might need in as a child, as Formian.Form only manipulates form inputs.

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |onSubmit |function|undefined|Required: function that will utilize one argument: formData | |[className]|string|""|Set a CSS class for custom styles | |[submitOnChange]|boolean|false|Runs the onSubmit function after every change, with a two second timeout. Use for auto-saving the form. | |[customStyles]|boolean|false|Used to prevent Formain's native styles from being injected on the page |

Common Child Component API

Formian elements are intended to mirror native HTML elements as closely as possible, just with a lot of useful built-in structure and accessibility properties (e.g. tabindex for mouse-less navigation). The hope is you will be able to trust that Formian has fully extended and utilized HTML's native functionality so these docs may feel (mostly) redundant.

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |name |string|undefined|Required: Key name for the formData object (some child types have a default for ease of use but it’s recommended to declare names manually) | |[className]|string|""|Set a CSS class for custom styles | |[labelText]|string|name|Label or Legend text | |[required]|boolean|true|Submit button is disabled until all required fields have a valid input | |[formatter]|function|undefined|Custom formatter function; manipulates the field value during every onChange event |

Formian.Text Component API

Shared by Formian.Email, Formian.Number, Formian.Password, Formian.Tel and Formian.TextArea

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |[defaultValue]|string|""|Value that the form element should initially render with | |[placeholder]|string|""|Placeholder text | |[errorText]|string or false|"Please enter a valid input"|Invalid input error message text (does not render if false) | |[validator]|function|undefined|Custom validator function; returns a boolean that asserts an acceptable input. If required is set to false, the validator will not run |

Common fields like Email, Text, Tel, etc ... are designed to be as easy to use as possible and (assuming no customization needs) require nothing besides being called as a child of Formian.Form. However, for the sake of readability, it's advised you always declare a name manually in your JSX, so coders can easily associate an input with its corresponding key in the formData object.

Formian.Checkbox Component API

Shared by Formian.OnOff, a stylized Checkbox

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |[defaultValue]|boolean|false|Value that the form element should initially render with | |[children]|react components|undefined|Component to be placed inline with the checkbox; supersedes labelText | |[errorText]|string or false|"Please check to agree"|Invalid input error message text (if false, does not render) | |[icon]|URL string or React Component|'\u2714'|Custom checkmark icon | |[tinyInt]|boolean|false|Field returns 1 or 0 instead of true or false |

Formian.Radio Component API

While you are likely used to declaring Radio buttons one-by-one (like a series of Checkboxes), Formian.Radio creates all radio elements together, wrapped in a Fieldset. This means they're declared in your JSX very similarly to a Select, and should tip you off to always ask the question: should this input be a Radio, or a Select?

For lengthier text, options for bigger buttons or a vertical layout is in the works.

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |options|array of strings|undefined|Required: Array of values for this key | |[defaultValue]|integer|0|Value as an index of the options array with which the form element should initially render |

Formian.Select Component API

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |options|array of strings|undefined|Required: Array of values for this key | |[defaultValue]|integer|0|Value as an index of the options array with which the form element should initially render | |[placeholder]|string|""|Placeholder text | |[errorText]|string|Please select an option|Invalid input error message text |

Formian.Range Component API

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |[defaultValue]|integer|0|Value the slider will initially render on | |[min]|integer|0|Minimum value for this Range | |[max]|integer|100|Maximum value for this Range | |[step]|integer|1|Step at which the Range increments or decrements |

Formian.Submit Component API

Triggers your onSubmit function. This button is grayed out until all required fields have a valid value, and onSubmit is not called. If Submit is clicked when this is not true, all erroneous form inputs will be highlighted, and display their error text, until they're focused.

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |[labelText]|string|""|Text displayed on the button; supersedes value | |[value]|string|Submit|Text displayed on the button |

Formian.Reset Component API

Resets all your fields to their default state. This button is grayed out and unclickable until the form is not in a default state. This button is a great addition to all kinds of user settings interfaces.

|Prop |Type |Default |Description | |-----------|:------:|:---------:|-------------------------------------------- | |[labelText]|string|""|Text displayed on the button; supersedes value | |[value]|string|Restore Defaults|Text displayed on the button |

Coming soon

Formian.Dataset, Formian.Date, rerender optimizations, easily customized colors, animated placeholders, and so much more are on the horizon