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.

Why?

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)

Related Projects

• 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.

Contribute

Thanks for being willing to contribute!

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

We are following the Conventional Commits convention.

Develop

• npm start: Starts a snowpack dev server using src/__preview__
• npm test: Run test suite including linting
• npm run build: Generate bundles

NPM Statistics

License

svelte-formup is open source software licensed as MIT.