Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vitorluizc/vue-form-container
👜 A Provider Component that encapsulate your forms and handle their states and validations.
https://github.com/vitorluizc/vue-form-container
javascript vue vue-component vue-form vue-form-validation vue-validate vue-validation vue-validator
Last synced: 5 days ago
JSON representation
👜 A Provider Component that encapsulate your forms and handle their states and validations.
- Host: GitHub
- URL: https://github.com/vitorluizc/vue-form-container
- Owner: VitorLuizC
- License: mit
- Created: 2018-09-28T19:08:33.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2019-03-20T23:30:33.000Z (over 5 years ago)
- Last Synced: 2024-04-27T15:20:44.082Z (7 months ago)
- Topics: javascript, vue, vue-component, vue-form, vue-form-validation, vue-validate, vue-validation, vue-validator
- Language: Vue
- Homepage:
- Size: 102 KB
- Stars: 24
- Watchers: 6
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vue-form-container
[](https://bundlephobia.com/result?p=vue-form-container)
[](https://bundlephobia.com/result?p=vue-form-container)
[](https://github.com/VitorLuizC/vue-form-container/blob/master/LICENSE)
[](https://app.fossa.io/projects/git%2Bgithub.com%2FVitorLuizC%2Fvue-form-container?ref=badge_shield)
A _Provider Component_ that encapsulate your forms and handle their states and validations. Under the hood it uses [`valite`](https://VitorLuizC/valite), a light and concise validator engine that works on asynchrony. The idea of having a component handling the states and validations of the forms I took from [`formik`](https://github.com/jaredpalmer/formik) and [`vue-final-form`](https://github.com/egoist/vue-final-form).
## Installation
This library is published in the NPM registry and can be installed using any compatible package manager.
```sh
npm install --save vue-form-container
# Use the command below if you're using Yarn.
yarn add vue-form-container
```
## Getting Started
Wrap your form, or wrapper element, with the `FormContainer` component passing the initial state of the fields and a scheme with the validations. Use `slot-scope` to receive the `FormContainer` scope with fields, errors, and so on.
```vue
Name
{{ errors.name }}
```
> `FormContainer` is a renderless component, so it can receive just a single element as slot.
You can change the form field states and perform their validations using `update` functions or by changing the state of the` fields` object, which is a Proxy.
> Due to platform limitations, fields (properties) need to be defined in **`schema`** or **`initial`**. If you don't want to initialize the value of a field, use `undefined` for it in **`initial`** or an empty list of validations in **`schema`**.
>
> **It is extremely important that the field exists on at least one of the objects.**
>
> ```vue
>
>
>
>
> ```
To use the `FormContainer` validations, fields and errors outside the template you should use a `ref` as in the example:
```vue
...
Sign In
export default {
methods: {
async onSubmit () {
// A FormContainer instance to handle fields, validate methods and other stuff.
const form = this.$refs.form;
await form.validateForm();
if (!form.isValid)
return;
console.log('fields', form.fields);
}
}
};
```
## API
### `FormContainer` props
Name | Type | Description
--------|-------------------|-------------
schema | `ValidatorSchema` | Schema of validators for form fields.
initial | `Object` | Initial state of form fields.
> #### About `ValidatorSchema` type
>
> `ValidatorSchema` is an object whose key is the name of the field and the value is a collection of validations. Validations are just functions that receive the value of the field and return` true` if it is valid and a `string` with the error message if it is invalid, these functions can also be asynchronous by returning a Promise that returns the same values (`true` or `string` with the error message).
>
> ```typescript
> type Validator = (value: any) => true | string | Promise;
>
> type ValidatorSchema = { [field: string]: Validator[]; };
>
> ...
>
> const schema: ValidatorSchema = {
> name: [
> (name) => !!name.trim() || 'Name is required.',
>
> async (name) => {
> const isRepeated = await services.isRepeatedName(name);
> return !isRepeated || 'Name is repeated.';
> }
> ]
> };
> ```
### `FormContainer` properties and methods (also received by slot-scope)
Name | Type | Description
--------------|---------------------------------------|:------------
isValid | `boolean` | Indicates if form fields are valid.
isLoading | `boolean` | Indicates if there's a validation running.
errors | `MessageSchema` | Error scheme of form fields.
fields | `Proxy<{ [field: string]: any }>` | Proxy with form fields. It uses getters to get the state of the field and setters to update it.
update | `(field: string, value: any) => void` | Updates the state of the `field` using the `value`.
validateField | `(field: string) => Promise` | Executes the schema validations for the `field` field.
validateForm | `() => Promise` | Executes the validations on all fields specified in the schema.
> #### About `MessageSchema` type
>
> `MessageSchema` is a reflection of the scheme used to define the validations and contains the error messages (or `null`) for the fields.
>
> ```typescript
> type Message = string | null;
>
> type MessageSchema = { [field: string]: Message; };
>
> ...
>
> const errors: MessageSchema = {
> name: 'Use first and last name.',
> email: 'E-Mail is required.',
> phone: null, // No error message, because validators have returned true.
> };
> ```
## Example
```vue
Name
{{ errors.name }}
E-Mail
{{ errors.email }}
Sign Up
import FormContainer from 'vue-form-container';
import * as services from './services';
// FormContainer schema to validate fields.
const schema = {
name: [
(name) => !!name.trim() || 'Name is required.'
],
email: [
(email) => !!email.trim() || 'E-Mail is required.',
(email) => /^.+@.+\..+$/.test(email) || 'E-Mail is invalid.',
async (email) => {
const isRepeated = await services.isRepeatedEMail(email);
return isRepeated || 'E-Mail is already registered.'
}
]
};
export default {
components: { FormContainer },
data () {
return {
schema,
// FormContainer fields initial state.
initial: { name: '', email: '' }
};
},
methods: {
async onSubmit () {
await this.$refs.form.validateForm();
if (!this.$refs.form.isValid)
return;
console.log('submit fields', this.$refs.form.fields);
}
}
};
```
## License
Released under [MIT License](./LICENSE).
[](https://app.fossa.io/projects/git%2Bgithub.com%2FVitorLuizC%2Fvue-form-container?ref=badge_large)