Skip to content

Latest commit

 

History

History
146 lines (106 loc) · 5.47 KB

README.md

File metadata and controls

146 lines (106 loc) · 5.47 KB
Raw

Loveform

The Vue form assembly tool that won't break your heart 💔

NPM - Version Linters

Loveform is a tool that helps you build validated forms in Vue 3 without the need to handle the whole validation process yourself. This means that you no longer need to write a submit function with a huge if - else if - else chain of conditionals and a whole bunch of error variables. Just import the component you need to use, write a validation function and voilà! Your form is production ready!

Why Loveform?

When building forms, you can choose between using no library at all, using one of the libraries that include form validation handling as a secondary feature (like Vuetify) or using Loveform.

If you decide to use no library at all, you will soon find yourself with a ton of variables holding errors for different inputs, large validations that include tons of if statements and a huge template to tie it all together. Soon enough, you will start writing your own form assembly solution (just as I did), wasting valuable time that could be better used writing code that will actually improve your business/project.

If you decide to use a library that includes form validation handling as a secondary feature (like Vuetify), you will probably have a Very hard time customizing how your forms look like. These libraries almost always include default styling and other features that you probably don't want nor need.

If you decide to use Loveform, you will have the power to write fully validatable forms without having to worry about the validation chain, while being able to fully style your components however you desire 😈.

The complete documentation is available on the official website.

Installation

Install using npm! (or your favourite package manager)

# Using npm
npm install loveform

# Using yarn
yarn add loveform

Please note that Loveform will only work with Vue 3.

Basic Usage

The basic principle is simple: write a form as you would write an ordinary form with no validations, add some validations to the fields you want to validate and then forget about validations and focus on the rest of your application. Here's an example of an (unstyled) validated form:

<script setup lang="ts">
import { ref } from 'vue';
import axios from 'axios';
import { LForm, LInput } from 'loveform';

const email = ref('');
const password = ref('');

const emailValidations = [
  (content: string) => !!content.trim() || 'The \'email\' field is required',
  (content: string) => content.includes('@') || 'Invalid email',
];
const passwordValidations = [
  (content: string) => content.length >= 6 || 'The password needs at least 6 characters',
  (content: string) => !content.includes('&') || 'The password can\'t include the \'&\' character',
];

const submit = async () => {
  // This will only run if the validations pass
  await axios.post('https://backend.you/signup', {
    email: email.value,
    password: password.value,
  });
};
</script>

<template>
  <LForm @submit="submit">
    <LInput
      v-model="email"
      :validations="emailValidations"
    />
    <LInput
      v-model="password"
      :validations="passwordValidations"
    />
    <button type="submit">Submit!</button>
  </LForm>
</template>

Each validation corresponds to a function that receives the value in the input and returns true (if the value of the input is correct) or an error string. Each validation will be run sequentially from the first validation of the array to the last one, and the first validation to fail will be displayed as the error.

Available Components

The available components are listed below:

  • LForm: The form wrapper that validates inputs when trying to submit.
  • LInput: A validatable input component.
  • LTextarea: A validatable textarea component.
  • LCheckbox: A checkbox type input component that plays nicely with the LCheckboxGroup component.
  • LCheckboxGroup: A validatable group of LCheckbox components.

Development

Testing locally

To test locally, first link the library:

npm link

Then cd into the dev folder and copy the LPlayground.template.vue into a LPlayground.vue file:

cd dev
cp src/LPlayground.template.vue src/LPlayground.vue

Now, edit the LPlayground.vue file risk free to try the components you're working on:

nano src/LPlayground.vue  # or your favorite editor

Finally, run npm install and start the playground server!

npm install
npm run dev

You can see the development server running at http://localhost:3000.

Resources