Apollo-form
[](https://badge.fury.io/js/apollo-form)
[](https://www.npmjs.com/package/apollo-form)
[](https://bundlephobia.com/result?p=apollo-form)
[](https://codecov.io/gh/muzikanto/apollo-form/branch/master)
[](https://david-dm.org/apollo-form)
[](https://badgen.net/npm/types/apollo-form)
[](https://github.com/muzikanto/apollo-form/blob/master/LICENSE)
- [Introduction](#introduction)
- [Installation](#installation)
- [Demo](#demo)
- [Examples](#examples)
- [Full form](#full-form)
- [Create field](#create-field)
- [Create array field](#create-array-field)
- [Create file field](#create-file-field)
- [Submit btn](#create-submit-button)
- [Reset btn](#create-reset-button)
- [Loader](#show-loader)
- [Error message](#show-error-message)
- [API](#api)
- [Form api](#form-api)
- [Field](#field-api)
- [License](#license)
## Introduction
Advanced form state, optimized fields rendering, form validation, file picker and more.
## Installation
```sh
npm i apollo-form
# or
yarn add apollo-form
```
## Demo
Show [code](./examples) of stories
[Demo sign in](https://muzikanto.github.io/apollo-form?path=/story/components--sign-in)
[Demo todo list](https://muzikanto.github.io/apollo-form?path=/story/components--todo-list)
[Demo with confirm](https://muzikanto.github.io/apollo-form?path=/story/components--with-confirm)
## Examples
### Full form
```typescript jsx
interface CreatePlanFormValues {
title: string;
price: number;
features: Array<{ title: string }>;
}
const validationSchema = Yup.object().shape({
title: Yup.string().required(),
price: Yup.number()
.required()
.min(0),
features: Yup.array().of(
Yup.object().shape({
title: Yup.string().required(),
}),
),
});
const initialState = {
title: '',
price: 0,
features: [],
};
function CreatePlanForm() {
return (
name='CreatePlanForm'
enableReinitialize
initialState={initialState}
validationSchema={validationSchema}
onSubmit={async ({ values }, form) => {
try {
await createPlanMutation({ variables: values });
form.reset();
} catch (e) {
form.responseError(e.message);
}
}}
>
{({ field }) => }
{({ field }) => }
name='features'>
{({ field }) => {
return (
<>
{field.value.map((el, i) => {
return (
);
})}
);
}}
{({ error }) => {error}}
{({ loading }) => (
Loading...
)}
{({ disabled }) => (
)}
{({ disabled }) => (
)}
);
}
```
### create field
```typescript jsx
function FormTextField(props: { name: string; validate?: FieldValidator }) {
const field = useField(props);
return ;
}
// or
function FormTextField(props: { name: string; validate?: FieldValidator }) {
return (
name={props.name} validate={props.validate}>
{({ field }) => {
const showError = Boolean(!field.focused && field.touched && field.error);
return (
field.setFieldValue(e.target.value)}
onFocus={() => field.setFieldFocused()}
onBlur={() => field.setFieldTouched(true)}
helperText={showError ? field.error : undefined}
error={showError}
/>
);
}}
);
}
```
### create array field
```typescript jsx
function FormTextFieldArray(props: { name: string; validate: FieldValidator }) {
return (
name={props.name} validate={props.validate}>
{({ field }) => {
return (
<>
{field.value.map((el, i) => {
return (
);
})}
);
}}
);
}
```
### create file field
```typescript jsx
function FieldImage(props: Omit) {
return (
{({ field, onClick }) => {
const [img, setImg] = React.useState(null);
React.useEffect(() => {
if (field.value) {
fileToBase64(field.value).then(r => setImg(r));
}
}, [field.value]);
return (
<>
{field.value ? (
<>
{img && (
<>
)}
) : (
)}
);
}}
);
}
```
### create submit button
```typescript jsx
function FormSubmit() {
return (
{({ isValid, isSubmitted, loading, existsChanges }) => (
)}
);
}
```
### create reset button
```typescript jsx
function FormSubmit() {
return (
{({ disabled }) => (
)}
);
}
```
### show error message
```typescript jsx
function FirstError(props: { name: string; ignoreTouched?: boolean }) {
return (
(
password-err: ({error})
)}
/>
);
}
```
### show loader
```typescript jsx
function CustomLoader() {
return (
{loading ? 'loading...' : 'loaded'}} />
);
}
```
### create query
```typescript jsx
const myFormQuery = makeApolloFormQuery('my-form');
function useMyFormState() {
return useQuery(myFormQuery);
}
function Form() {
return (
);
}
```
## Api
### Form api
| Name | Type | Required | Description |
| ------------------ | ------------ | -------- | --------------------------------------------------------------------- |
| name | string | yes | graphql client value name, like this `query Form { ${name} @client }` |
| initialState | object | yes | Initial form state |
| initialErrors | FormErrors | no | Initial errors |
| initialTouches | FormTouches | no | Initial touched fields |
| validationSchema | ObjectSchema | no | Yup validation schema |
| validate | Function | no | Custom form validation, function returned errors state |
| resetOnSubmit | boolean | no | Reset form with `initialState` after submit |
| validateOnMount | boolean | no | Validate form on mount |
| enableReinitialize | boolean | no | Reset form with new `initialState` |
| onInit | Function | no | Function for save form reference |
| onSubmit | Function | no | Async function for handle form submit |
| onChange | Function | no | Handle state changes (called only if values changed) |
| saveOnUnmount | boolean | no | Save form state in apollo global state |
| resetOnUnmount | boolean | no | Reset form with `initialState` after unmount form |
### Field api
| Name | Type | Required | Description |
| -------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
| name | string | yes | key of state object |
| validate | Function | no | Function for validate value, return err(string) or undefined |
| children | Function | yes | Function for render, return object of "value", "error", "touched", "focused" and change actions |
## License
[MIT](LICENSE)