react-formian

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