svelte-formup - v0.6.2

svelte-formup

form helpers for svelte

What?

Not standing in the way and keeping everything smooth.

Plug'n'Play. Input elements in, values out.
Works just like a normal form. Except it does all the tedious work for you.
Extendable. Work with native form elements and custom input components out of the box.
Two-Way Binding. svelte-formup is two-way bound by default. Change a value in your object, and it changes in your inputs.
Async Validation. Everything is validated asynchronously for uninterrupted user experience.

sveltes action feature is a unique way to attach custom logic to DOM elements. Combined with its great way of two-way binding and its reactive stores this allows to write very native looking forms with no boilerplate.

Adding yup allows to define a schema for value parsing and validation. Yup schema are extremely expressive and allow modeling complex, interdependent validations, or value transformations.

Styling forms in a consistent way has always been a problem. Everyone has her own opinion about it. svelte-formup allows flexibel error reporting supporting both native and programmatic usage. Invalid form elements are marked supporting several validity state specific css selectors like :invalid. Additionally svelte-formup adds CSS classes (is-error, is-success, is-dirty, is-pristine, is-validating, is-submitting and is-submitted) for further custom styling. These classes maybe added to surrounding fieldsets or form group element depending on the validity state of the contained form elements. On non form elements these classes are set using the has- prefix instead of is-.

Installation
Usage
API
Polyfills
TODO
Related Projects
Support
Contribute
NPM Statistics
License

Installation

npm install svelte-formup

And then import it:

// using es modules
import { formup } from 'svelte-formup'

// common.js
const { formup } = require('svelte-formup')

Alternatively use UNPKG or jsDelivr packages.

Hotlinking from unpkg: (no build tool needed!)

import { formup } from 'https://unpkg.com/svelte-formup?module'

Usage

Native HTML form elements

<script>
  import * as yup from 'yup'

  import { formup } from 'svelte-formup'

  const { values, errors, dirty, validate, validity } = formup({
    schema: yup.object().shape({
      title: yup.string().oneOf(['Mr.', 'Mrs.', 'Mx.']).required(),
      name: yup.string().required(),
      email: yup.string().email().required(),
    }),
    onSubmit(data, context) {
      console.log('onSubmit', { data, context })
    },
  })
</script>

<form use:validate>
  <p use:validity>
    <label for="title">title</label>
    <select id="title" bind:value="{$values.title}">
      <option></option>
      <option>Mr.</option>
      <option>Mrs.</option>
      <option>Mx.</option>
    </select>
  </p>

  <p use:validity>
    <label for="name">name</label>
    <input id="name" bind:value="{$values.name}" type="text" />
  </p>

  <p use:validity>
    <label for="email">email</label>
    <input id="email" bind:value="{$values.email}" type="email" />
  </p>

  <p>
    <button type="submit">Submit</button>
    <button type="reset">reset</button>
  </p>
</form>

Error Messages

svelte-formup does not provide any svelte components. Most projects have their own way of reporting errors. Below is an example component to simplify error handling.

<script>
  import { getFormupContext } from 'svelte-formup'

  export let at

  const { invalid } = getFormupContext()

  let error

  $: error = $invalid.get(at)
</script>

{#if error}
<span class="error" aria-live="polite">
  <slot {error}>{error.message}</slot>
</span>
{/if}

This could be used like (omitting identical code for brevity)

<script>
  import IfError from './if-error.svelte'
</script>

<form use:validate>
  <label for="name">name</label>
  <input id="name" bind:value="{$values.name}" type="email" />
  <IfError at="name" />
</form>

API

svelte-formup exports two functions:

formup(options) is the main entrypoint which creates the form context
getFormupContext() allows to access the form context through the svelte context

Polyfills

Array#flatMap(): Edge >= 79, Safari >= 12
AbortController: Edge >= 16
NodeList#forEach(): Edge >= 16, Safari >=10
async-await: Edge >= 15
Destructuring assignment: Edge >= 14
Object.assign(): Edge >= 12
WeakSet: Edge >= 12
Promise: Edge >= 12
Symbol.for: Edge >= 12
for...of: Edge >= 12

TODO

add css class for each test per node: yup.string().email().required() => email required
what about invalid path (validate and validateAt)
debounce during testing: Timer Mocks
add aria based on schema: ARIA Forms
how to handle disabled fields, skip validation?
a guide how to implement a custom component
focus first error field after submit with error
on focus add css class: maybe a focused store?
provides IfError, Input, Select, Choice components using yup schema values to reduce boilerplate via 'svelte-formup-components'
svelte-society/recipes-mvp recipy: form validation with yup
examples like informed
style guide: form > :global(.valid.dirty)

svelte-jsx - write svelte components using [jsx] to simplify testing
svelte-htm - Hyperscript Tagged Markup for svelte to simplify testing
@testing-library/svelte - helps to test UI components in a user-centric way

Support

This project is free and open-source, so if you think this project can help you or anyone else, you may star it on GitHub. Feel free to open an issue if you have any idea, question, or you've found a bug.