@react-hero/form
A full-featured form component.
Installation
npm install @react-hero/form --save
# or
yarn add @react-hero/form
Basic Usage
Simply create a FormStore
and pass into Form
component. value
and onChange
of form controls (such as input
) are unnecessary.
import { Form, FormStore } from '@react-hero/form'
class App extends React.Component {
constructor(props) {
super(props)
this.store = new FormStore()
}
onSubmit = (e) => {
e.preventDefault()
const values = this.store.get()
console.log(values)
}
render() {
return (
<Form store={this.store}>
<Form.Field label='Name' name='name'>
<input type='text' />
</Form.Field>
<Form.Field label=''>
<button onClick={this.onSubmit}>Submit</button>
</Form.Field>
</Form>
)
}
}
Simple Field
Form.Item
is a simplified version of Form.Field
, without any extra nodes.
<Form store={this.store}>
<Form.Item name='username'>
<input type='text' />
</Form.Item>
<Form.Item name='password'>
<input type='password' />
</Form.Item>
</Form>
will renders into:
<form>
<input type="text" />
<input type="password" />
</form>
Default Values
To set default values, you can pass an object as the first parameter. Use reset()
to restore defaults at any time.
const store = new FormStore({ name: 'Harry' })
// ...
store.reset()
Form Validation
The second parameter is used to pass the form rules. Each function should return a boolean
or string
value:
- Returning
true
means check successfully. - Returning
false
orstring
means check failed, and the string result is the error message.
Using store.validate()
to check entire form, and returns a tuple with error message and form values. Or directly gets form values by store.get()
without validation.
const rules = {
name: (!!val && !!val.trim()) || 'Name is required'
}
const store = new FormStore({}, rules)
// ...
const [error, values] = store.validate()
APIs
Form Props
-
className
Form element class name,optional
. -
store
Form store,required
. -
inline
Inline layout for fields, default tofalse
. -
compact
Hides error message, default tofalse
. -
required
Displays star mark, does not include validation, default tofalse
. -
labelWidth
Customized label width,optional
. -
gutter
Customized distance between label and control,optional
. -
errorClassName
Adds customized class name when field has error message,optional
. -
onSubmit
Submit callback,optional
.
Form Field Props
-
className
Field element class name,optional
. -
label
Field label,optional
. -
name
Field name,optional
. -
valueProp
Value prop name of child component, default to'value'
. -
valueGetter
The way to parse value from change event,optional
. -
suffix
Suffix nodes,optional
.
Form Item Props
-
className
Field element class name,optional
. -
name
Field name,optional
. -
valueProp
Value prop name of child component, default to'value'
. -
valueGetter
The way to parse value from change event,optional
.
FormStore Methods
-
new FormStore(defaultValues?, rules?)
Creates form store. -
store.get()
Returns entire form values. -
store.get(name)
Returns field value by name. -
store.set()
Sets entire form values. -
store.set(name, value)
Sets field value by name. -
store.set(name, value, false)
Sets field value by name without validating. -
store.reset()
Resets form with default values. -
store.validate()
Validates entire form and returns error message and values. -
store.validate(name)
Validates field value by name and returns error message and value. -
store.error()
Returns the all error messages. -
store.error(index)
Returns the nth error message. -
store.error(name)
Returns error message by name. -
store.error(name, message)
Sets error message by name. -
store.subscribe(listener)
Adds listener and returns unsubscribe callback.
Hooks
-
useFormStore(defaultValues?, rules?)
Creates form store with hooks. -
useFormChange(store, onChange)
Add form listener with hooks. -
useFieldChange(store, onChange)
Add field listener with hooks.