⌨️ 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>
);