Svelte Easy Form

A simple, easy to use form state and validation handler for Svelte.

Table of Content

• Installation
• Live example
• Basic usage
• API
  • createForm
    • Schema
      • Field
  • Validator
  • Options
    • validateOnInput
    • submitHandler
  • FormModel
    • values and errors
    • onInput
    • onBlur
    • onSubmit
• Contributing
• Current development state

Installation

npm install @vkhalikov/svelte-easy-form

Live Example

Live example with different options is available here.

Basic usage

1. Create a form model with createForm

     import createForm from '@vkhalikov/svelte-easy-form';
      
     // Declare a schema with initial values and validators
     const schema = {
       username: {
         value: 'admin',
         validators: [required('Login is required')],
       },
       password: {
         validators: [required('Password is required')],
       },
     };
   
     const { values, errors, onInput, onSubmit } = createForm(schema);
   

   NOTE: Validators are not included in the package. See validator for details.

2. Use it in your markup
   1. Create a form and pass it a submit handler. It will be called if all values are valid.

       <form on:submit="{onSubmit}" action="https://myformhandler.com" method="post">
       </form>
      

      If you want a custom handler, you can use submitHandler option.
   2. Create inputs.

        <form on:submit="{onSubmit}" action="https://myformhandler.com" method="post">
          <input type="text" name="username" value="{$values.username}" on:input="{onInput}" />
          <input type="password" name="password" value="{$values.password}" on:input="{onInput}" />
        </form>
      

      NOTE: attributes name, value, on:input are required.

      NOTE: values is a svelte store, therefore you can access it with a $ prefix.

   3. Show validation errors.

        <form on:submit="{onSubmit}" action="https://myformhandler.com" method="post">
          <input type="text" name="username" value="{$values.username}" on:input="{onInput}" />
          {#if $errors.username}
             {$errors.username}  // Render it as is
          {/if}
      
          <input type="password" name="password" value="{$values.password}" on:input="{onInput}" />
          <ValidationError error="{$errors.password}" /> // Or create a component
        </form>
      

      NOTE: errors is a svelte store, therefore you can access it with a $ prefix.

API

createForm

type CreateForm = (schema: Schema, options?: Options) => FormModel;

Schema

A schema is an object, that contains Fields which are used to construct a FormModel.

interface Schema {
  [fieldName: string]: Field;
}

Field

interface Field {
  value?: any; // Initial value
  validators?: [Validator];
}

NOTE: If you don't need to set an initial value and validators for a field, you should still define a Field in Schema as an empty object:

const schema = {
  name: {},
}

Validator

Validator is a function that receives a field value and returns a validation error in any form if the value is invalid or null.

type Validator = (value: any) => any;

Options

interface Options {
  validateOnInput?: boolean;
  submitHandler?: SubmitHandler;
}

validateOnInput

Defaults to true

Defines whether the field should be validated immediately after a change. As user types in a symbol for example. If set to false, the field is validated on blur and submit.

submitHandler

Defaults to undefined

type SubmitHandler = (values: Writable, event: Event) => void;

If provided, SubmitHandler will be used instead of a default browser submit handler.

FormModel

A form model that is returned from createForm function.

interface FormModel {
  values: Writable;
  errors: Writable;
  onInput: (e: Event) => void;
  onSubmit: (e: Event) => void;
}

values and errors

A Writable svelte stores, that contain current values and errors, that are accessible via $ prefix.

If you are unfamiliar with svelte stores, see the tutorial.

onInput

An event handler that updates and validates a value.

Should be passed to an input as on:input attribute.

NOTE: A value is not validated on input if the validateOnInput option is set to false.

onSubmit

An event handler that does 2 things:

1. Validate all values for which validators were provided.
2. If all values are valid:
   • If a SubmitHandler is provided, it will be called with the following arguments: (values, originalEvent)
   • Otherwise a default browser submit handler will be called

onSubmit should be passed to a form as on:submit attribute.

Contributing

Any feedback is welcomed. If you want to propose changes follow these steps:

1. Fork the repo

2. Clone the fork

3. Create a branch - git checkout -b {prefix}/new-feature

   Prefixes: feat for features, fix for fixes

4. Make your changes and commit git commit -a - m "short description"

5. Push changes git push origin {prefix}/new-feature

6. Create new Pull Request

   NOTE: Please provide a description to your changes and link an issue if it's a bugfix

Current Development State

The project is in beta, therefore anything might be changed in the future