@vkhalikov/svelte-easy-form
v0.1.1
Published
A simple, easy to use form state and validation handler for Svelte
Downloads
5
Maintainers
Readme
Svelte Easy Form
A simple, easy to use form state and validation handler for Svelte.
Table of Content
Installation
npm install @vkhalikov/svelte-easy-form
Live Example
Live example with different options is available here.
Basic usage
- 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.
- Use it in your markup
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.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 asvelte
store, therefore you can access it with a$
prefix.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 asvelte
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
inSchema
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 tofalse
.
onSubmit
An event handler that does 2 things:
- Validate all values for which validators were provided.
- 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
- If a
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:
Fork the repo
Clone the fork
Create a branch -
git checkout -b {prefix}/new-feature
Prefixes:
feat
for features,fix
for fixesMake your changes and commit
git commit -a - m "short description"
Push changes
git push origin {prefix}/new-feature
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