⌨️ Q3 UI Forms
Builders
Most use cases can be taken care of using our builder components. These components handle your state, validation and marshalling workflows for you, allowing you to focus on capturing user input safely and quickly. When more customization is required, you can still import our field components and hooks directly.
Form
The Form
component renders a basic HTML form element with
a few decorations like onSubmit
, onReset
, a submit
button and validation. It also sets up a MUI Grid
for
formatting. See Wrapper
for more information.
Next
The Next
component renders a submit button, controlled by
the form's master validation and submission state. In other
words, it will disable on load or error automatically.
Example
import { Builders } from 'q3-ui-forms';
export const AsCustom () => (
<Builders.Form>
<Builders.Next>
{(nextProps) => {
// forward all props somewhere else
return null;
}}
</Builders.Next>
</Builders.Form>
);
export const AsDefault () => (
<Builders.Form>
<Builders.Next submit />
</Builders.Form>
);
API
Name | Description | Type |
---|---|---|
submit |
Include if this should submit the parent form | Boolean |
children |
Used to forward all state props into a custom element | Function |
label |
Replace the default button label | String |
onClick |
Used for non-submit buttons that still need to be state-aware | Function |
Wrapper
The Wrapper
HOC should not be called directly. Instead,
use either Form
or MultiStep
. This simply forwards state
functions and values into each.
Example
import { Builders } from 'q3-ui-forms';
const incrementOne = v => v * 1.5;
const incrementTwo = v => v * 2.5;
export const WithProps () => (
<Builders.Form
initialValues={{ foo: 1, bar: 1 }}
// will drop "bar" from state
keep={['foo']}
marshal={{
foo: [
incrementOne,
incrementTwo,
]
}}
onSubmit={(values) => {
// values.foo will output 3.75
// noop
}}
>
<Builders.Field type="number" name="foo" />
</Builders.Form>
);
Api
Name | Description | Type |
---|---|---|
keep |
Drops every key from initialValues that doesn't match an item of this array |
Array |
marshal |
Mutates internal field values pre-submit using a series of compounding functions | Function |
Helpers
handleFormData
The handleFormData
curries the onSubmit
handler to
process attachments for you. Rather than receiving the raw
data object, you'll get a FormData instance that can be sent
directly to your API.
Example
import React from 'react';
import { Builders, helpers } from 'q3-ui-forms';
export default ({ onSubmit }) => (
<Builders.Form
onSubmit={helpers.handleFormData(onSubmit)}
>
<Builders.Field type="file" name="example" />
</Builders.Form>
);