This is more of a short note about some experiments when working with web components that I’m publishing as a reference for future me (or other people that experience the same issue).

I’ve been experimenting with web components in order to build a wrapper for Felte that can easily be used with vanilla JS. One of Felte’s features is the ability to use custom field components that are not based on the browser’s native inputs (input, textarea, select). The example I show is a div with an attribute [contenteditable=“true”]. While testing this experiment I found some weird behaviour coming from Firefox: while I could perfectly click each field and type of it, if I tried to use the form only using the keyboard (tabbing to each field) the focus moved but trying to type would always result in the text being added to the first field I focused.

Another confusing behaviour is that, even if you can type on the element when clicking on the element itself, the care is not displayed at all. So there’s no visual cue indicating the user that the element itself is editable. Currently, there’s an open issue on bugzilla that seems to be exactly this.

This behaviour is, of course, unacceptable. Specially since forms (and web applications in general) should be accessible to keyboard users. In order for the demo I was working on to function correctly I went to look for an immediate solution. After some research I found that the solution that works more consistently for me is to not add [contenteditable] to the fields on render and, instead, add event listeners that dynamically add the attribute on focus and remove it on blur:

function handleFocus(e) {
  e.target.setAttribute('contenteditable', '');
}

function handleBlur(e) {
  e.target.removeAttribute('contenteditable');
}

// We query the shadowRoot of the element that contains
// our `contenteditable` fields
element.shadowRoot
  .querySelectorAll('div[role="textbox"]')
  .forEach((el) => {
    el.addEventListener('focusin', handleFocus);
    el.addEventListener('focusout', handleBlur);
  });

Or better yet, in order to make it more easy to reuse, make a custom element that behaves like this:

function handleFocus(e) {
  e.target.setAttribute('contenteditable', '');
}

function handleBlur(e) {
  e.target.removeAttribute('contenteditable');
}

export class MyField extends HTMLElement {
  constructor() {
    super();
    // Make the element focusable
    this.setAttribute('tabindex', '0');
    // Assign a role for assistive technologies
    this.setAttribute('role', 'textbox');
    // Some default styles
    this.style.display = 'block';
    this.style.cursor = 'text';
  }

  connectedCallback() {
    this.addEventListener('focusin', handleFocus);
    this.addEventListener('focusout', handleBlur);
  }

  disconnectedCallback() {
    this.removeEventListener('focusin', handleFocus);
    this.removeEventListener('focusout', handleBlur);
  }
}

customElements.define('my-field', MyField);

This way you can use <my-field></my-field> as a [contenteditable] “div”!

Keep in mind that this article only worries about making focus work correctly on a [contenteditable] element. There's more things that you should consider when doing something like this which would depend on your use-case.

While this is fine and I could have perfectly moved all my tests to use said assertion style, I like the descriptive way Jest tests look like. As a quick way to maintain certain similarity I reached for ChaiJS, an assertion library that is mainly used with mocha. Chai offers expect like assertions that can arguably be more descriptive than Jest’s. Instead of writing expect(…).toBe(true), you’d write expect(…).to.be.true. For the most part I managed to do a search and replace for this.

This setup works really good! But there’s some minor details: The assertion errors thrown by Chai are slightly different than those expected by uvu., so sometimes I’d get messages or extra details that are not so relevant to the test itself. Another issue is that I’d receive diffs comparing undefined to undefined when an assertion failed. As a proper developer with too much free time, I went ahead and decided to experiment with writing my own assertion library built on top of uvu’s assertions that I called uvu-expect. Here’s more or less how I did it.

The “expect” function

The main thing our assertion library needs is an expect function that should receive the value you’re planning to validate.

export function expect(value) {
  // run your validations here
}

If we wanted to keep a similar API to Jest, this could return an object with functions.

export function expect(value) {
  return {
    toBe(expected) {
      if (expected !== value) {
        throw new Error('Expected values to be strictly equal');
      }
    },
  };
}

But I actually really enjoyed Chai’s syntax. So I decided to use proxies to achieve something similar. We could start by allowing to chain arbitrary words after our expect call. I decided not to restrict the possible “chain” words to simplify development.

Proxy is a JavaScript feature that allows you to "wrap" an object in order to intercept and modify its functionality. In our case we will use it to modify the behaviour when accessing our object's properties.

export function expect(value) {
  const proxy = new Proxy(
    // The target we are adding the proxy on. For now it's empty.
    {},
    {
      get() {
        // Any property access returns the proxy once again.
        return proxy;
      },
    }
  );
  return proxy;
}

expect().this.does.nothing.but.also.does.not.crash;

Next we will allow for any of these chain words to be functions.

export function expect(value) {
  const proxy = new Proxy(
    {},
    {
      get(_, outerProp) {
        // Instead of returning the initial proxy, we return
        // a new proxy that wraps a function.
        return new Proxy(() => proxy, {
          get(_, innerProp) {
            // If the function does not get called, and a property gets
            // accessed directly, we access the same property
            // from our original proxy.
            return proxy[innerProp];
          },
        });
      },
    }
  );
  return proxy;
}

expect().this.does.nothing().but.also.does.not.crash();

With this we already got the base for our syntax. We now need to be able to add some meaning to certain properties. For example, we might want to make expect(…).to.be.null to check whether a value is null or not.

Adding meaning to our properties

We could perfectly check the name of the property being accessed and use that to run validations. For example, if we wanted to add a validation for checking if a value is null:

// For brevity, we're not going to use the code that handles functions.
// Only property access
export function expect(value) {
  const proxy = new Proxy(
    {},
    {
      get(_, prop) {
        // `prop` is the name of the propery being
        // accessed.
        switch (prop) {
          case 'null':
            if (value !== null) {
              throw new Error('Expected value to be null');
            }
            break;
        }
        return proxy;
      },
    }
  );
  return proxy;
}

expect(null).to.be.null;
try {
  expect('not null').to.be.null;
} catch (err) {
  console.log(err.message); // => "Expected value to be null"
}

This can make our expect function hard to maintain, and adding more properties would not be so trivial. In order to make this more maintainable (and extensible) we’re going to handle this a bit differently.

Defining properties

Instead of proxying an empty object, we will proxy an object that contains the properties we want to have meaning.

const properties = {
  // ...
};

export function expect(value) {
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      // `target` is our `properties` object
      console.log(target);
      return new Proxy(() => proxy, {
        get(_, innerProp) {
          return proxy[innerProp];
        },
      });
    },
  });
  return proxy;
}

I decided to define each property as an object that contains two functions: onAccess to be executed on property access, and onCall to be executed when calling the property as a function. For example, our property for null could look like:

const isNull = {
  onAccess(actual) {
    if (actual !== null) {
      throw new Error('Expected value to be null');
    }
  },
};

We can also define a property to check if two values are strictly equal:

const isEqual = {
  onCall(actual, expected) {
    if (actual !== expected) {
      throw new Error('Expected values to be strictly equal');
    }
  },
};

Then we can modify our expect function to call them when they’re accessed:

// We add the previously defined properties to
// our `properties` object
const properties = {
  null: isNull,
  equal: isEqual,
};

export function expect(value) {
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      const property = target[outerProp];
        // We execute the `onAccess` handler when one is found
      property?.onAccess?.(value);
      return new Proxy(
        (...args) => {
            // We execute the `onCall` handler when one is found
          property?.onCall?.(value, ...args);
          return proxy;
        },
        {
          get(_, innerProp) {
            return proxy[innerProp];
          },
        }
      );
    },
  });
  return proxy;
}

expect(null).to.be.null;
expect('a').to.equal('a');

We suddenly have a really basic assertion library! And it can be easily extended by adding properties to our properties object!

There’s one thing we’re still not able to do with our current implementation: negate assertions. We need a way to modify the behaviour of future assertions.

Negating assertions

In order to be able to achieve this, we need a way to communicate to our properties that the current assertions is being negated. For this we’re going to change a bit how we define our properties. Instead of expecting the actual value being validated as first argument, we’re going to receive a context object that will contain our actual value and a new negated property that will be a boolean indicating if the assertion is being negated. Our new properties for equal and null will then look like this:

const isNull = {
  onAccess(context) {
    if (!context.negated && context.actual !== null) {
      throw new Error('Expected value to be null');
    }
    if (context.negated && context.actual === null) {
      throw new Error('Expected value not to be null');
    }
  },
};

const isEqual = {
  onCall(context, expected) {
    if (!context.negated && context.actual !== expected) {
      throw new Error('Expected values to be strictly equal');
    }
    if (context.negated && context.actual === expected) {
      throw new Error('Expected values not to be strictly equal');
    }
  },
};

And we can add a new property to negate our assertions:

const isNot = {
  onAccess(context) {
    // We set `negated` to true so future assertions
    // will have knowledge of it.
    context.negated = true;
  },
};

Then our expect function will call each handler with a context object instead of the actual value:

const properties = {
  null: isNull,
  equal: isEqual,
  not: isNot,
};

export function expect(value) {
  // Our context object
  const context = {
    actual: value,
    negated: false,
  };
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      const property = target[outerProp];
      property?.onAccess?.(context);
      return new Proxy(
        (...args) => {
          property?.onCall?.(context, ...args);
          return proxy;
        },
        {
          get(_, innerProp) {
            return proxy[innerProp];
          },
        }
      );
    },
  });
  return proxy;
}

expect('a').to.not.equal('b');

This technique can be used to communicate more details about our assertions to future assertions.

Do not throw normal Errors

To make examples simpler, we throw normal errors (throw new Error(…)). Since this is to be used with a test runner, it’d be better to throw something like Node’s built-in AssertionError or, in the case of uvu, its own Assertion error. These would give way more information when assertions fail. And it can be picked by Node or test runners to show prettier messages and diffs!

Conclusion

This is a simplified explanation of how I made uvu-expect. uvu-expect has way more features and validations such as:

• .resolves and .rejects to assert on promises
• Possibility to create plugins for it using an extend function. This is how I also created a plugin for it called uvu-expect-dom which offers similar validations to @testing-library/jest-dom.
• Assertions on mock functions (compatible with sinonjs and tinyspy).

I aimed for it to have at least the features I used of Jest’s expect. You can read more about its features on its README! I documented everything about it there. Even how to create your own plugins for it.

It was a really fun side-project to build and explain. And it’s been working really well with our tests on Felte.

Felte is an extensible form management library for Svelte, Solid and (as of today) React. The main characteristic of it is that it does not require any sort of Field or Form components to work. In its most basic form it only requires you to provide it your HTML form element so it can subscribe to your user’s interaction with your form.

I originally started working on Felte wanting a form library for Svelte that would not make it complex to style my input components. As I worked more on it, it began growing into a much more flexible package that allowed you to validate your form using your preferred validation library and display your validation messages as you preferred. After the release of version 1.0.0 of SolidJS, I released a version for it as well that shares most of its internals with the original Felte package. And now, more than a year after the first commit, version 1.0.0 has been released alongside a new version for React! This includes many improvements in the core API, new features and a more consistent API between all three versions.

Usage

All three versions of Felte have a very similar API, and a similar concept: you call a function to set up your form. Then you give Felte a reference to your HTML form element. The variations in its API come mostly from how each framework handles reactivity. For example, with Svelte, Felte returns stores that contain your data which you can access by prefixing the stores with $. With Solid and React it returns functions that will let you subscribe to all of your form’s data or specific values of it.

On its most basic form, you only need to use form, a property returned from Felte that will let it subscribe to all interactions that happen in your form.

Here’s a basic example of how each version looks like:

Svelte

The package for Svelte is available on npm as felte.

<script>
  import { createForm } from 'felte'

  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })
</script>

<!-- `form` is an action -->
<form use:form>
  <input type=text name=email>
  <input type=password name=password>
  <button type=submit>Sign In</button>
</form>

Solid

The package for Solid is available on npm as @felte/solid.

import { createForm } from '@felte/solid';

function Form() {
  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })

    // `form` is an action
  return (
    <form use:form>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <button type="submit">Sign In</button>
    </form>
  );
}

React

The package for React is available on npm as @felte/react.

import { useForm } from '@felte/react';

function Form() {
  const { form } = useForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })

    // `form` is a ref
  return (
    <form ref={form}>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <button type="submit">Sign In</button>
    </form>
  );
}

New features

Version 1 comes with a lot of improvements and features:

• Debounced validation is now supported. Previously we only supported asynchronous validation, but offered no way to debounce them. This meant using Felte’s validation for calls to an API would not be recommended unless you debounced it yourself, or did them only on submission.
• Asynchronous and debounced validations might apply to only a few fields. Showing loaders for the field’s that are validating is a nice feature to have for your users. This is why Felte now offer’s a way to check if validations are currently running via the new isValidating store. And a way to check which is the last field your users interact with using the new interacted store.
• Using custom form controls was not so straightforward. Requiring to use helper functions to update your stores. Felte now exports a new function: createField (useField for React) to be used with custom fields where you can’t directly provide a name, or with fields that don’t use native HTML controls at all (such as a contenteditable elements). It helps you make your custom fields “discoverable” to Felte.
• Better support for field arrays with new helper functions to handle them: addField, unsetField, moveField and swapFields.
• You no longer always need to have an onSubmit handler. If no onSubmit is declared, Felte will submit your values as either application/x-www-form-urlencoded or multipart/form-data using the action, method and enctype attributes of your <form> element.

Breaking changes

This being a major version release, there are some breaking changes. If you were previously using Felte v0.x, you can check the migration guide for Svelte, or the migration guide for Solid.

Read more

I’ve gone back to update my original introductory posts about Felte, as well as added a new one about React to the series. You can check them out here:

• Felte: an extensible form library for Svelte
• Felte: an extensible form library for Solid
• Felte: an extensible form library for React

Final words

I’ve put a lot of work on this project, and I’m really grateful to the contributors that helped Felte grow as much as it did! I hope that this release can be useful to all of you!

In this post I am going to write about Felte, a form management library for React I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with React. The other two are oriented towards Felte’s integration with Svelte and Solid.

Features

As mentioned above, Felte aims to make the basics of form reactivity as easy to handle as possible, while still allowing for more complex behaviours via configuration and extensibility. Its main features are:

• Single action to make your form reactive.
• Use HTML5 native elements to create your form. (Only the name attribute is necessary).
• Minimal re-renders. None if you don't need your form's data in your component.
• Provides stores and helper functions to handle more complex use cases.
• No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
• Handles addition and removal of form controls during runtime.
• Official solutions for error reporting using reporter packages.
• Supports validation with yup, zod, superstruct and vest.
• Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

import { useForm } from '@felte/react';

export function Form() {
  const { form } = useForm({
    onSubmit: (values) => {
      // ...
    },
  });

  return (
    <form ref={form}>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <input type="submit" value="Sign in" />
    </form>
  );
}

We set up the form by calling useForm with our submit handler. This function returns, among other utilities, an action that can be used on your form element. Now Felte will track all inputs with a name attribute. When submitting your form, the latest values in your inputs will be passed to your onSubmit function as an object. For our previous example, the shape of values will be:

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in an observable that contains your form data in the same shape as the values you'd receive on your onSubmit. This observable is handled by Felte and its value can be obtained by calling the function data returned from useForm; no need to handle observables by yourself! We'll refer to these functions as accessors from now on. When this accessor is called without any arguments (data()), it returns all of the form's data as an object. This also "subscribes" your component to every change on your form, triggering a re-render everytime a value changes. An argument can be passed as first argument to select a specific field, either a selector function or a string path. By using an argument, your component will only "subscribe" to changes made to the specific value you've selected.

For example, this would log your user’s email to the console as they type it:

// Within a component
const { form, data } = useForm({ /* ... */ });

// Passing a function as first argument
console.log(data(($data) => $data.email));

// Passing a string as first argument
console.log(data('email'));

Accessors are NOT hooks, this means they can be called from wherever you need them in your code.

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. useForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data as it changes, and it expects you to return an object with the same shape, containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on an accessor that is returned from useForm as errors:

const { form, errors } = useForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

console.log(errors(($errors) => $errors.email));

More complex validation requirements might require third party validation libraries. Felte offers first party integrations with some popular validation libraries through its extensibility features. These integrations are offered as separate packages. I will write write more about this in the next section regarding extensibility, but you can read more about these packages in our official documentation.

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on useForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about some of the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

We are currently maintaining four packages to integrate Felte with some popular validation libraries: yup, zod, superstruct and most recently vest. Here we will use yup as an example, but you can read more about the rest here.

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of useForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = useForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly using the errors accessor returned by useForm. Messages won’t be available on this accessor until the related field is interacted with.

import { useForm } from '@felte/react';

function Form() {
  const { form, errors } = useForm({ /* ... */ });

  return (
    <form ref={form}>
      <label htmlFor="email">Email:</label>
      <input name="email" type="email" id="email" />
      {!!errors('email') && (
        <span>{errors('email')}</span>
      )}
      <button>Submit</button>
    </form>
  );
}

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

But you might not like that specific syntax to handle your validation messages. Felte currently also has four accompanying packages that offer different alternatives on how to display your validation messages:

• Using a React component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors accessor around.
• Modifying the DOM directly by adding and removing DOM elements.
• Using Tippy.js to display your messages in a tooltip.
• Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to cover the first package. But you can read more about the rest in the documentation.

Using a React component to get your validation messages can be done with the package @felte/reporter-react. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-react

# yarn
yarn add @felte/reporter-react

Then you’ll need to import both the reporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

import { reporter, ValidationMessage } from '@felte/reporter-react';
import { useForm } from '@felte/react';

function Form() {
  const { form } = useForm({
      // ...
      extend: reporter, // or [reporter]
      // ...
    },
  })

 // We assume a single string will be passed as a validation message
 // This can be an array of strings depending on your validation strategy
  return (
    <form ref={form}>
      <input id="email" type="text" name="email" />
      <ValidationMessage for="email">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="password" name="password" />
      <ValidationMessage for="password">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="submit" value="Sign in" />
    </form>
  );
}

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

I hope this served as a good introduction to Felte, and that it is interesting enough for you to give it a try. Felte is already on a stable state and used by some people. I am also open to help and suggestions so feel free to open an issue or make a pull request on GitHub.

In this post I am going to write about Felte, a form management library for Solid I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with Solid. The other two are oriented towards Felte’s integration with Svelte and React.

Features

As mentioned above, Felte aims to make the basics of form reactivity as easy to handle as possible, while still allowing for more complex behaviours via configuration and extensibility. Its main features are:

• Single action to make your form reactive.
• Use HTML5 native elements to create your form. (Only the name attribute is necessary).
• Provides stores and helper functions to handle more complex use cases.
• No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
• Handles addition and removal of form controls during runtime.
• Official solutions for error reporting using reporter packages.
• Supports validation with yup, zod, superstruct and vest.
• Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

import { createForm } from '@felte/solid';

export function Form() {
  const { form } = createForm({
    onSubmit: (values) => {
      // ...
    },
  });

  return (
    <form use:form>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <input type="submit" value="Sign in" />
    </form>
  );
}

We set up the form by calling createForm with our submit handler. This function returns, among other utilities, an action that can be used on your form element. Now Felte will track all inputs with a name attribute. When submitting your form, the latest values in your inputs will be passed to your onSubmit function as an object. For our previous example, the shape of values will be:

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in a signal that contains your form data in the same shape as the values you'd receive on your onSubmit. This signal is wrapped, allowing some extra functionality, and is returned by createForm as function called data. We'll refer to these functions as accessors from now on. When this accessor is called without any arguments (data()), it behaves like a regular signal that returns all of the form's data as an object. An argument can be passed as first argument to select a specific field, either a selector function or a string path.

For example, this would log your user’s email to the console as they type it:

// Within a component
const { form, data } = createForm({ /* ... */ });

createEffect(() => {
  // Passing a function as first argument
  console.log(data(($data) => $data.email));

  // Passing a string as first argument
  console.log(data('email'));
});

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. createForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data as it changes, and it expects you to return an object with the same shape, containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on an accessor that is returned from createForm as errors:

const { form, errors } = createForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

createEffect(() => {
  console.log(errors(($errors) => $errors.email));
});

More complex validation requirements might require third party validation libraries. Felte offers first party integrations with some popular validation libraries through its extensibility features. These integrations are offered as separate packages. I will write write more about this in the next section regarding extensibility, but you can read more about these packages in our official documentation.

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on createForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about some of the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

We are currently maintaining four packages to integrate Felte with some popular validation libraries: yup, zod, superstruct and most recently vest. Here we will use yup as an example, but you can read more about the rest here.

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of createForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = createForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly using the errors accessor returned by createForm. Messages won’t be available on this accessor until the related field is interacted with.

import { Show } from 'solid-js';
import { createForm } from '@felte/solid';

function Form() {
  const { form, errors } = createForm({ /* ... */ });

  return (
    <form use:form>
      <label for="email">Email:</label>
      <input name="email" type="email" id="email" />
      <Show when={errors('email')}>
        <span>{errors('email')}</span>
      </Show>
      <button>Submit</button>
    </form>
  );
}

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

But you might not like that specific syntax to handle your validation messages. Felte currently also has four accompanying packages that offer different alternatives on how to display your validation messages:

• Using a Solid component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors accessor around.
• Modifying the DOM directly by adding and removing DOM elements.
• Using Tippy.js to display your messages in a tooltip.
• Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to cover the first package. But you can read more about the rest in the documentation.

Using a Solid component to get your validation messages can be done with the package @felte/reporter-solid. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-solid

# yarn
yarn add @felte/reporter-solid

Then you’ll need to import both the reporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

import { reporter, ValidationMessage } from '@felte/reporter-solid';
import { createForm } from '@felte/solid';

function Form() {
  const { form } = createForm({
      // ...
      extend: reporter, // or [reporter]
      // ...
    },
  })

 // We assume a single string will be passed as a validation message
 // This can be an array of strings depending on your validation strategy
  return (
    <form use:form>
      <input id="email" type="text" name="email" />
      <ValidationMessage for="email">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="password" name="password" />
      <ValidationMessage for="password">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="submit" value="Sign in" />
    </form>
  );
}

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

I hope this served as a good introduction to Felte, and that it is interesting enough for you to give it a try. Felte is already on a stable state and used by some people. I am also open to help and suggestions so feel free to open an issue or make a pull request on GitHub.

In this post I am going to write about Felte, a form management library for Svelte I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with Svelte. The other two are oriented towards Felte’s integration with Solid and React.

Features

As mentioned above, Felte aims to make the basics of form reactivity as easy to handle as possible, while still allowing for more complex behaviours via configuration and extensibility. Its main features are:

• Single action to make your form reactive.
• Use HTML5 native elements to create your form. (Only the name attribute is necessary).
• Provides stores and helper functions to handle more complex use cases.
• No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
• Handles addition and removal of form controls during runtime.
• Official solutions for error reporting using reporter packages.
• Supports validation with yup, zod, superstruct and vest.
• Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

<script>
  import { createForm } from 'felte'

  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })
</script>

<form use:form>
  <input type=text name=email>
  <input type=password name=password>
  <input type=submit value="Sign in">
</form>

We set up the form by calling createForm with our submit handler. This function returns, among other utilities, an action that can be used on your form element. Now Felte will track all inputs with a name attribute. When submitting your form, the latest values in your inputs will be passed to your onSubmit function as an object. For our previous example, the shape of values will be:

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in a regular writable Svelte store. This store is returned by createForm as data, following the same shape as the values you’d receive on your onSubmit function.

For example, this would log your user’s email to the console as they type it:

const { form, data } = createForm({ /* ... */ });

// We use a reactive statement to log everytime our data store changes.
// We access the value of our store by prefixing it with `$`.
$: console.log($data.email);

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. createForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data store as it changes, and it expects you to return an object with the same shape as your data store containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on a writable store that is returned from createForm as errors:

const { form, errors } = createForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

$: console.log($errors);

More complex validation requirements might require third party validation libraries. Felte offers first party integrations with some popular validation libraries through its extensibility features. These integrations are offered as separate packages. I will write write more about this in the next section regarding extensibility, but you can read more about these packages in our official documentation.

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Or you might find it tedious to display your validation messages using if statements. Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on createForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

We are currently maintaining four packages to integrate Felte with some popular validation libraries: yup, zod, superstruct and most recently vest. Here I will use yup as an example, but you can read more about the rest here.

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of createForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = createForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly accessing the errors store returned by createForm. Messages won’t be available on this store until the related field is interacted with.

<script>
  const { form, errors } = createForm({ /* ... */ });
</script>

<form use:form>
  <label for=email>Email:</label>
  <input name=email id=email type=email>
  {#if $errors.email}
    <span>{$errors.email}</span>
  {/if}
  <button>Submit</button>
</form>

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

But you might not like that specific syntax to handle your validation messages. Felte currently also has four accompanying packages that offer different alternatives on how to display your validation messages:

• Using a Svelte component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors store around.
• Modifying the DOM directly by adding and removing DOM elements.
• Using Tippy.js to display your messages in a tooltip.
• Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to write about the first package. But you can read more about the rest in the documentation.

Using a Svelte component to get your validation messages can be done with the package @felte/reporter-svelte. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-svelte

# yarn
yarn add @felte/reporter-svelte

Then you’ll need to import both the svelteReporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

<script>
  import { svelteReporter, ValidationMessage } from '@felte/reporter-svelte';
  import { createForm } from 'felte';

  const { form } = createForm({
      // ...
      extend: svelteReporter,
      // ...
    },
  })
</script>

<form use:form>
  <input id="email" type="text" name="email">
  <ValidationMessage for="email" let:messages={message}>
    <!-- We assume a single string will be passed as a validation message -->
    <!-- This can be an array of strings depending on your validation strategy -->
    <span>{message}</span>
    <!-- Shown when there's no validation messages -->
    <span slot="placeholder">Please type a valid email.</span>
  </ValidationMessage>
  <input type="password" name="password">
  <ValidationMessage for="password" let:messages={message}>
    <!-- If not slot is used, you'll need to handle empty messages -->
    <span>{message || ''}</span>
  </ValidationMessage>
  <input type="submit" value="Sign in">
</form>

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

I hope this served as a good introduction to Felte, and that it is interesting enough for you to give it a try. Felte is already on a stable state and used by some people. I am also open to help and suggestions so feel free to open an issue or make a pull request on GitHub.