Migrating from 0.x felte or @felte/solid

Since this package will be released already at 1.0.0 (the exposed API is now consistent with the rest of wrappers), this section would only make sense if you've tried Felte coming from Solid or Svelte and expect a similar API to the one previously used on those wrappers. If you're coming directly to this package, you can safely ignore this and use the documentation as reference.

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.

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:

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

To this:

useForm({
  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.