Migrating from 0.x

Helpers

The returned helpers have changed.

setField('email', 'zaphod@beeblebrox.com')

should now be

setFields('email', 'zaphod@beeblebrox.com')
setField('email' , 'zaphod@beeblebrox.com')

should now be

setFields('email', 'zaphod@beeblebrox.com', true)
setError('email', 'Not an email')

should now be

setErrors('email', 'Not an email')
setWarning('password', 'Not secure')

should now be

setWarnings('password', 'Not secure')
setTouched('email')

should now be

setTouched('email', true)
setTouched('tag', 1)

should now be

setTouched('tag[1]', true)

These functions now can do more than before. Be sure to check the documentation on them.

<script>
  import { createForm } from 'felte';

  // ...

  const { getField } = createForm({ /* ... */ });
  const email = getField('email');
</script>

should now be

<script>
  import { getValue, createForm } from 'felte';

  // ...

  const { data } = createForm({ /* ... */ });
  const email = getValue($data, 'email');
</script>

Reporter Svelte

@felte/reporter-svelte exports the reporter as reporter now instead of svelteReporter in order to maintain consistency with other packages.

import { svelteReporter } from '@felte/reporter-svelte';

should now be

import { reporter } from '@felte/reporter-svelte';

TypeScript

Some adjusting of your types might be needed due to the following changes:

Configuration

data-felte-unset-on-remove

Felte no longer keeps the value of a removed field in your stores by default. And the attribute used to indicate you want this to happen, data-felte-unset-on-remove, has been removed. Instead we now have an attribute data-felte-keep-on-remove that does the opposite.

This was done since we felt it was more intuitive for Felte to always represent the visible state of the form by default, and it keeps it consistent to how a browser would submit a form by default: if a control is not on the DOM, there's no value to submit. Allowing to override this behaviour if explicitly defined.

If you want to keep the same behaviour as before:

Dynamic forms

On v0.x, if you had an array of fields with this data:

const data = {
  multipleFields: [
    'value 1',
    'value 2',
    'value 3',
  ],
};

And removed the field with a value of value 2, the resulting data store would look like this:

const data = {
  multipleFields: [
    'value 1',
    null,
    'value 3',
  ],
};

This is no longer the case. Felte now will splice the array, making the resulting data store look like:

const data = {
  multipleFields: [
    'value 1',
    'value 3',
  ],
};

Felte will also properly keep track of the errors, warnings and touched stores internally.

Originally we thought it would be a good idea to make the index a unique identifier for a field, hence setting values to null instead of removing it completely. This conflicted with how most people expected this to work, and with how most people attempted to create array of fields in Felte.

Proxies

Programatically setting the value of an input component using its value prop/attribute directly does not trigger any kind of events that Felte can catch. In order to make this more seamless we originally added a proxy to the inputs of forms tracked by Felte. This ended up causing many race conditions and issues that were difficult to debug (and some we did not manage to solve). To ease maintainability, we've decided to remove this.

The recommended way to programatically change the value of a field is now to use the setFields helper, which will update both the data store and input's value.

Extending

We've removed the addWarnValidator function that was previously passed to extender functions. Instead, now the addValidator function receives an object with options as a second argument. This gives a smaller and more unified API, as well as opening to add more options in the future.

If you have an extender using addWarnValidator, you must update it by calling addValidator instead with the following options:

addValidator(yourValidationFunction, { level: 'warning' });

Fieldsets

We've removed the feature of adding a name attribute to a fieldset element. While the fieldset element does support this attribute, browser's ignore it completely when submitting forms with JS disabled (and when constructing FormData). In order to keep a consistent behaviour, we're enforcing dot notation for nested forms from now on.

If you were using this feature, you should update your forms by removing the name attribute from your fieldset elements and using dot notation on your inputs. For example, instead of this:

<fieldset name="account">
  <input name="email" />
</fieldset>

you should do this:

<fieldset>
  <input name="account.email" />
</fieldset>

data-felte-index

This was removed for similar reasons to the outlined above. Specifically since we now allow to submit forms using a FormData or urlencoded content type. To be able to support all these options, we now require for all inputs to use dot notation for this use-case as well.

If you were using this feature, you should update your forms by removing the data-felte-index attribute and adding it to your input's name using dot notation. For example, instead of this:

<input data-felte-index="1" name="friend" />

you should do this:

<input name="friend.1" />

Validators

Validator packages no longer extend Felte's configuration, but accept a configuration object directly by being called as a function. This allows to handle multiple schemas if needed. You should check the updated documentation. But in short, using zod as an example, you should change this:

createForm({
  extend: validator,
  validateSchema: schema,
})

To this:

createForm({
  extend: validator({ schema }),
})

@felte/validator-superstruct now exports a validator function instead of a createValidator function.

Errors and warnings

In order to mantain an always consistent shape, the errors and warnings store now will always contain null or an array of strings if there are errors, even if your validation strategy returns single strings as validation messages.

data.set

Previously, setting directly to the data store either by using $data = or data.set would touch the changed fields. This is no longer the case and using the setFields helper is recommended in order to touch and change a field at the same time. If you want this behaviour, this:

$data.email = 'zaphod@beeblebrox.com';

Should be changed to this:

setFields('email', 'zaphod@beeblebrox.com', true);