[{"attributes":{"section":"Getting started","id":"getting-started"},"body":"## Getting started\n\nFelte is a JavaScript library that tries to help you ease the management of forms, form validation and the reporting of validation errors. To use its basic functionalities you'll only need the base `felte` package from npm.\n\n```sh\nnpm i -S felte\n\n# Or if you use yarn\n\nyarn add felte\n```\n\nThen, inside of the Svelte component where you have your form, import the `createForm` function and call it with a configuration object containing an `onSubmit` function. The `createForm` function returns an action that you can use in any form. This is all you need to make your form reactive.\n\n```html\n\n\n\n```\n\nFelte does not export any components like `Form`, `Field` or anything like that, but you do need to make felte aware of your inputs by assigning a **name** to them.\n\nFelte also offers [validation handling](/docs/svelte/validation) and [error reporting](/docs/svelte/reporters) but this is all you need for the most basic, validation-less form.\n","bodyBegin":5,"frontmatter":"section: Getting started"},{"attributes":{"section":"Validation","subsections":[{"id":"server-errors","name":"Server errors"},{"id":"error-handling","name":"Error handling"},{"id":"multiple-validations","name":"Multiple validations"},{"id":"warnings","name":"Warnings"}],"id":"validation"},"body":"## Validation\n\nThe `createForm` function can also accept a validation function. It's a function that accepts the current form values and needs to return an object with the same shape, but instead of the property values it can have a string or array of strings containing the validation messages.\n\n```javascript\nconst { form } = createForm({\n // ...\n validate: (values) => {\n const errors = {}\n if (!values.email || !/^[^@ \\t\\r\\n]+@[^@ \\t\\r\\n]+\\.[^@ \\t\\r\\n]+/.test(values.email)) {\n errors.email = 'Must be a valid email';\n }\n if (!values.password) errors.password = [\n 'Must not be empty',\n 'Must be over 8 characters',\n ];\n if (values.password && values.password.length < 8) {\n errors.password = ['Must be over 8 characters'];\n }\n return errors;\n },\n // ...\n});\n```\n\nIt shouldn't be a hard task to use a third party library, as long as you transform their result into something that Felte understands.\n\n> Note that the `validate` function **can be asynchronous**.\n\nFelte will validate whichever field it considers as `touched` as you fill the form, and it will validate all fields (and set them as `touched`) when submitting it.\n\n### Server errors\n\nYou can add an `onError` function to the `createForm` configuration that will be called if the `onSubmit` function throws an error. It will be called with the value thrown from the `onSubmit` function. You can use the `onError` function to shape your server errors into the same shape that the `validate` function expects and return them from the same function for them to be handled.\n\n```javascript\nconst { form } = createForm({\n // ...\n // Assuming your server already returns them with the appropriate shape.\n // Might not be the case for most cases.\n onError: (errors) => errors,\n // ...\n});\n```\n\n### Error handling\n\n`createForm` returns also its `errors` and `touched` fields as stores.\n\n```html\n\n\n

\n  \n  {JSON.stringify($errors, null, 2)}\n

\n\n

\n  {JSON.stringify($touched, null, 2)}\n

\n```\n\nYou can read more above them in the [stores](/docs/svelte/stores) section.\n\nYou don't need to manually handle this errors. Felte provides four official packages to handle your errors for you, either using Tippy, directly mutating the DOM, providing a Svelte component or using the browser's built-in constraint validation API. You can read more about this in the [reporters](/docs/svelte/reporters) section.\n\n### Multiple validations\n\nThe `validate` property of the configuration object can also be an array of validation functions. The resulting errors from running each validation function will be merged into a single object. If a single property was assigned two or more errors from the validation functions, the property will be an array of strings. This might not be useful for common scenarios, but it will come useful when using any of our [validator packages](/docs/svelte/validators).\n\n### Warnings\n\nSometimes you may want to display certain validation messages that _do not_ prevent the form from submitting, such as a password security message. Felte provides a store called `warnings` for this, and such warnings can be added to the store by using the `warn` property on `createForm`'s configuration.\n\n```javascript\nconst { form } = createForm({\n // ...\n warn: (values) => {\n const warnings = {}\n if (values.password && values.password.length < 8) {\n warnings.password = 'Your password could be more secure';\n }\n return warnings;\n },\n // ...\n});\n```\n\nThe `warn` function works exactly the same as the `validate` function. With the same features and constraints. Multiple warn functions can be passed as an array, and the shape of `warnings` can contain either a string or an array of strings.\n","bodyBegin":10,"frontmatter":"section: Validation\nsubsections:\n - Server errors\n - Error handling\n - Multiple validations\n - Warnings"},{"attributes":{"section":"Validators","subsections":[{"id":"using-yup","name":"Using Yup"},{"id":"using-zod","name":"Using Zod"},{"id":"using-superstruct","name":"Using Superstruct"},{"id":"using-vest","name":"Using Vest"}],"id":"validators"},"body":"## Validators\n\nIf you use third party libraries for validation you might have found yourself needing to transform the output from said validation library to the form library you're using (unless the form library supports it natively or provides its own built-in alternative). In order to not reinvent the wheel, and to make life easier for you, we provide some official `validators` which are, basically, adapters for popular validation libraries.\n\nIf a validation library you use is not supported, feel free to [open an issue](https://github.com/pablo-abc/felte/issues), we would like to support the most used ones! You may also [build your own validation package](/docs/svelte/extending-felte).\n\n### Using Yup\n\n[Yup](https://github.com/jquense/yup) is a really popular validation library. For this reason we've created [`@felte/validator-yup`](https://github.com/pablo-abc/felte/tree/main/packages/validator-yup). An official package to handle validation with Yup. To use it you'll need both `@felte/validator-yup` and `yup`.\n\n```sh\nnpm install --save @felte/validator-yup yup\n\n# Or, if you use yarn\n\nyarn add @felte/validator-yup yup\n```\n\nIts usage would look something like:\n\n```javascript\nimport { validator } from '@felte/validator-yup';\nimport * as yup from 'yup';\n\nconst schema = yup.object({\n email: yup.string().email().required(),\n password: yup.string().required(),\n});\n\nconst { form } = createForm({\n // ...\n extend: validator, // OR `extend: [validator],`\n validateSchema: schema,\n // ...\n});\n```\n\n#### Warnings\n\nOptionally, you can also add a schema that will validate for warnings in your data. Warnings are any validation messages that should not prevent your form for submitting. You can add the schema that will be using for setting this values to the `warnSchema` property on the configuration:\n\n```javascript\nimport { validator } from '@felte/validator-yup';\nimport * as yup from 'yup';\n\nconst validateSchema = yup.object({\n email: yup.string().email().required(),\n password: yup.string().required(),\n});\n\n// We only warn if the user has already started typing a value\nconst warnSchema = yup.object({\n password: yup\n .string()\n .test('is-secure', 'password is not secure', (value) =>\n value ? value.length > 8 : true\n ),\n});\n\nconst { form } = createForm({\n // ...\n extend: validator, // or `extend: [validator],`\n validateSchema,\n warnSchema,\n // ...\n});\n```\n\n#### Typescript\n\nFor typechecking add the exported type `ValidatorConfig` as a second argument to `createForm` generic.\n\n```typescript\nimport type { ValidatorConfig } from '@felte/validator-yup';\n\nimport * as yup from 'yup';\n\nconst schema = yup.object({\n email: yup.string().email().required(),\n password: yup.string().required(),\n});\n\nconst { form } = createForm, ValidatorConfig>(/* ... */);\n```\n\n### Using Zod\n\n[Zod](https://github.com/colinhacks/zod) is a \"TypeScript-first schema declaration and validation library\", alternative to Yup with a similar API. We've also created [`@felte/validator-zod`](https://github.com/pablo-abc/felte/tree/main/packages/validator-zod) as an official package to handle validation with Zod. To use it you'll need both `@felte/validator-zod` and `zod` installed.\n\n```sh\nnpm install --save @felte/validator-zod zod\n\n# Or, if you use yarn\n\nyarn add @felte/validator-zod zod\n```\n\nIts usage would look something like:\n\n```javascript\nimport { validator } from '@felte/validator-zod';\nimport * as zod from 'zod';\n\nconst schema = zod.object({\n email: zod.string().email().nonempty(),\n password: zod.string().nonempty(),\n});\n\nconst { form } = createForm({\n // ...\n extend: validator, // OR `extend: [validator],`\n validateSchema: schema,\n // ...\n});\n```\n\n#### Warnings\n\nOptionally, you can also add a schema that will validate for warnings in your data. Warnings are any validation messages that should not prevent your form for submitting. You can add the schema that will be using for setting this values to the `warnSchema` property on the configuration:\n\n```javascript\nimport { validator } from '@felte/validator-zod';\nimport { z } from 'zod';\n\nconst schema = z.object({\n email: z.string().email().nonempty(),\n password: z.string().nonempty(),\n});\n\n// We only warn if the user has started typing a value\nconst warnSchema = zod.object({\n password: zod\n .string()\n .refine((value) => (value ? value.length > 8 : true), {\n message: 'Password is not secure',\n }),\n});\n\nconst { form } = createForm({\n // ...\n extend: validator, // or `extend: [validator],`\n validateSchema: schema,\n warnSchema,\n // ...\n});\n```\n\n#### Typescript\n\nFor typechecking add the exported type `ValidatorConfig` as a second argument to `createForm` generic.\n\n```typescript\nimport type { ValidatorConfig } from '@felte/validator-zod';\nimport { z } from 'zod';\n\nconst schema = z.object({\n email: z.string().email().nonempty(),\n password: z.string().nonempty(),\n});\n\nconst { form } = createForm, ValidatorConfig>(/* ... */);\n```\n\n### Using Superstruct\n\n[Superstruct](https://docs.superstructjs.org) is another popular validation library that follows a more _functional_ style. We've created [`@felte/validator-superstruct`](https://github.com/pablo-abc/felte/tree/main/packages/validator-superstruct) as an official package to handle validation with Superstruct. To use it you'll need both `@felte/validator-superstruct` and `superstruct` installed.\n\n```sh\nnpm install --save @felte/validator-superstruct superstruct\n\n# Or, if you use yarn\n\nyarn add @felte/validator-superstruct superstruct\n```\n\nIts usage would look something like:\n\n```javascript\nimport { createValidator } from '@felte/validator-superstruct';\nimport { object, string, size } from 'superstruct';\n\nconst struct = object({\n email: size(string(), 1, Infinity),\n password: size(string(), 1, Infinity),\n});\n\nconst { form } = createForm({\n // ...\n extend: createValidator(), // or `extend: [createValidator()],`\n validateStruct: struct,\n // ...\n});\n```\n\nThe first argument of `createValidator` is a function that will receive each [`failure`](https://docs.superstructjs.org/api-reference/errors) from Superstruct, you can check the failure there and return an appropriate custom error message.\n\n```javascript\nimport { createValidator } from '@felte/validator-superstruct';\n\nconst validator = createValidator((value) =>\n value.type === 'string' ? 'Must not be empty' : 'Not valid'\n);\n```\n\n#### Warnings\n\nOptionally, you can also add a struct that will validate for warnings in your data. Warnings are any validation messages that should not prevent your form for submitting. You can add the struct that will be using for setting this values to the `warnStruct` property on the configuration:\n\n```javascript\nimport { createValidator } from '@felte/validator-superstruct';\nimport { object, string, size, optional } from 'superstruct';\n\nconst validateStruct = object({\n email: size(string(), 1, Infinity),\n password: size(string(), 1, Infinity),\n});\n\n// We only show the warning if the user has started to type a value\nconst Secure = refine(string(), 'secure', (value) =>\n value ? value.length > 8 : true\n);\n\nconst warnStruct = object({\n password: Secure,\n});\n\nconst { form } = createForm({\n // ...\n extend: createValidator(), // or `extend: [createValidator()],`\n validateStruct,\n warnStruct,\n // ...\n});\n```\n\n#### Typescript\n\nFor typechecking add the exported type `ValidatorConfig` as a second argument to `createForm` generic.\n\n```typescript\nimport type { ValidatorConfig } from '@felte/validator-superstruct';\nimport type { Infer } from 'superstruct';\n\nconst struct = object({\n email: size(string(), 1, Infinity),\n password: size(string(), 1, Infinity),\n});\n\nconst { form } = createForm, ValidatorConfig>(/* ... */);\n```\n\n### Using Vest\n\n[Vest](https://github.com/ealush/vest) is a validations library for JS apps that derives its syntax from modern JS unit testing frameworks such as Mocha or Jest. We've also created [`@felte/validator-vest`](https://github.com/pablo-abc/felte/tree/main/packages/validator-vest) as an official package to handle validation with Vest. To use it you'll need both `@felte/validator-vest` and `vest` installed.\n\n```sh\nnpm install --save @felte/validator-vest vest\n\n# Or, if you use yarn\n\nyarn add @felte/validator-vest vest\n```\n\nIts usage would look something like:\n\n```javascript\nimport { validator } from '@felte/validator-vest';\nimport { create, enforce, test } from 'vest';\n\nconst suite = create('form', (data) => {\n test('email', 'Email is required', () => {\n enforce(data.email).isNotEmpty();\n });\n test('password', 'Password is required', () => {\n enforce(data.password).isNotEmpty();\n });\n});\n\nconst { form } = createForm({\n // ...\n extend: validator, // OR `extend: [validator],`\n validateSuite: suite,\n // ...\n});\n```\n\n#### Warnings\n\nThis validator will update the `warnings` store with the messages returned from any test marked with `warn()`:\n\n```javascript\nimport { validateSuite } from '@felte/validator-vest';\nimport { create, enforce, test, warn } from 'vest';\n\nconst suite = create('form', (data) => {\n test('email', 'Email is required', () => {\n enforce(data.email).isNotEmpty();\n });\n test('password', 'Password is required', () => {\n enforce(data.password).isNotEmpty();\n });\n\n test('password', 'Password not secure', () => {\n warn();\n // We only warn if the user has already started typing a value\n if (!data.password) return;\n enforce(data.password).longerThanOrEquals(8);\n });\n});\n\nconst { form } = createForm({\n // ...\n validate: validateSuite(suite),\n // ...\n});\n```\n\n#### Typescript\n\nFor typechecking add the exported type `ValidatorConfig` as a second argument to `createForm` generic.\n\n```typescript\nimport { validator, ValidatorConfig } from '@felte/validator-vest';\nimport { create, enforce, test } from 'vest';\n\nconst initialValues = {\n email: '',\n password: '',\n};\n\nconst suite = create('form', (data: typeof initialValues) => {\n test('email', 'Email is required', () => {\n enforce(data.email).isNotEmpty();\n });\n test('password', 'Password is required', () => {\n enforce(data.password).isNotEmpty();\n });\n});\n\nconst { form } = createForm({\n // ...\n initialValues,\n extend: validator, // or `extend: [validator],`\n validateSuite: suite,\n // ...\n});\n```\n","bodyBegin":10,"frontmatter":"section: Validators\nsubsections:\n - Using Yup\n - Using Zod\n - Using Superstruct\n - Using Vest"},{"attributes":{"section":"Transformations","id":"transformations"},"body":"## Transformations\n\nYou may need to transform your data in between it being set in your inputs and it being set in the `data` store. For example for handling numeric values on text inputs or transforming a value to a `Date` instance. Felte allows you to do this by using the `transform` property in `createForm`'s configuration object. It accepts either a function or an array of functions. These functions will receive the values of the form _before_ they're assigned to the `data` store, and returns a new object that will be assigned to the store. This can even allow you to change your values shape in Felte.\n\n```javascript\nconst { form } = createForm({\n //...\n transform: (values) => ({\n ...values,\n shouldBeNumber: parseInt(values.shouldBeNumber, 10),\n }),\n})\n```\n\nThese transformation functions run also when directly setting values to the `data` store (e.g. via `bind:value` or assigning to the `data` store directly).\n\n> **NOTE**: Transformations **must** be syncrhonous.\n","bodyBegin":5,"frontmatter":"section: Transformations"},{"attributes":{"section":"Default data","id":"default-data"},"body":"## Default data\n\nFelte will take as default values whatever is set first in the HTML as a value/checked attribute (if the input is \"controlled\" by Felte).\n\n```html\n\n```\n\nIn this case, Felte will take `default@email.com` as a default value for the \"email\" field.\n\nAn alternative to this would be to use the `initialValues` property of the configuration for `createForm`. This can also be useful if the form element is not controlled by Felte and you're binding directly to the `data` store.\n\n```javascript\nconst { form } = createForm({\n /* ... */\n initialValues: {\n account: {\n email: 'default@email.dev',\n },\n },\n /* ... */\n});\n```\n","bodyBegin":5,"frontmatter":"section: Default data"},{"attributes":{"section":"Nested forms","id":"nested-forms"},"body":"## Nested forms\n\nYou can do much more complex form shapes by using \"nested\" forms, this can be done easily by setting your component name to one using a notation like `\"account.email\"`.\n\n```html\n\n```\n\nThis form would end up creating a `data` store with this shape:\n\n```javascript\n{\n account: {\n email: '',\n password: '',\n },\n profile: {\n firstName: '',\n lastName: '',\n },\n}\n```\n\nAnother, arguably, more organized way to do this would be by using the HTML `fieldset` tag.\n\n```html\n\n```\n\nThis form would create a `data` store with the same shape as above.\n\nNames may also contain an `index` (e.g. `\"email[0]\"`) to indicate that the value should be set in that specific index of an array. This is useful when handling multiple values or generating inputs from an array. This works in both a `fieldset` element and controls.\n\n```html\n\n```\n\nIf for any reason you want to keep the name without the index, you may also set the index using the `data-felte-index` property. This works for `input`, `textarea` and `fieldset` as well.\n\n```html\n\n```\n\n> **NOTE**: This attribute will be troublesome when using `radio` inputs since they do need to have a different `name` per group.\n","bodyBegin":5,"frontmatter":"section: Nested forms"},{"attributes":{"section":"Dynamic forms","id":"dynamic-forms"},"body":"## Dynamic forms\n\nFelte watches for any added or removed form controls in your form, updating the `data`, `errors` and `touched` stores accordingly.\n\n```html\n\n\n

\n \n \n {#if hasBio}\n

\n  {/if}\n</form>\n```\n\nIf you check the `hasBio` checkbox, the `textarea` will be added to the DOM and Felte will automatically update its stores with the appropriate values without changing anything else.\n\nBy default, if you remove an input from the form Felte will not clear the value of the `data` store. If you want this behaviour, you can add the `data-felte-unset-on-remove` attribute to your input.\n\n```html\n<textarea name=\"bio\" data-felte-unset-on-remove />\n```\n\nThis attribute can be added to any form control or `fieldset` tag. If you set this attribute on a `fieldset` but you've specified a `data-felte-unset-on-remove=\"false\"` attribute on an input within it, Felte will not remove that specific value from the stores.\n\n```html\n<fieldset name=\"profile\" data-felte-unset-on-remove>\n  \n  <input name=\"name\" data-felte-unset-on-remove=\"false\">\n  \n  <textarea name=\"bio\" />\n</fieldset>\n```\n","bodyBegin":5,"frontmatter":"section: Dynamic forms"},{"attributes":{"section":"Stores","subsections":[{"id":"data","name":"data"},{"id":"errors","name":"errors"},{"id":"warnings","name":"warnings"},{"id":"touched","name":"touched"},{"id":"isvalid","name":"isValid"},{"id":"issubmitting","name":"isSubmitting"},{"id":"isdirty","name":"isDirty"}],"id":"stores"},"body":"## Stores\n\nFelte's `createForm` returns the stores it uses to handle your form. These stores are `data`, `errors` and `touched`.\n\n### data\n\nA writable store that contains the form's values. Depending on the field type, the values can be either a `string`, an array of `string`s, a `number`, a `boolean`, a `File`, an array of `File`s or `undefined` if no value has been set.\n\n### errors\n\nA writable store that contains the validation errors in the form. It will have the same shape as `data` but containing either a `string` or an array of `string`s with each validation message per field.\n\n### warnings\n\nA store that contains warnings on the form fields set by the `warn` function. Unlike the `errors` store, this store will have validation messages immediately and not only when a field is touched.\n\n### touched\n\nA writable store with the same shape as `data` but containing `boolean`s as values, defining if the field has been touched or not.\n\n### isValid\n\nA readable store containing a single boolean that tells if the form is valid or not.\n\n### isSubmitting\n\nA readable store containing a single boolean that tells if the form is submitting or not.\n\n### isDirty\n\nA writable store containing a single boolean that tells if the form is dirty or not.\n","bodyBegin":13,"frontmatter":"section: Stores\nsubsections:\n  - data\n  - errors\n  - warnings\n  - touched\n  - isValid\n  - isSubmitting\n  - isDirty"},{"attributes":{"section":"Helper functions","subsections":[{"id":"setfield","name":"setField"},{"id":"getfield","name":"getField"},{"id":"setfields","name":"setFields"},{"id":"settouched","name":"setTouched"},{"id":"seterror","name":"setError"},{"id":"validate","name":"validate"},{"id":"reset","name":"reset"},{"id":"setinitialvalues","name":"setInitialValues"},{"id":"createsubmithandler","name":"createSubmitHandler"}],"id":"helper-functions"},"body":"## Helper functions\n\nThe `createForm` function also returns some additional helpers that can help with some more complex use cases.\n\n### setField\n\nA function that accepts a `string` path for the `data` store, the value to be set and an optional boolean argument defining if this operation should _touch_ the field (defaults to `true`).\n\n### getField\n\nA function that accepts a `string` path for the `data` store. It will return the value contained in said path.\n\n### setFields\n\nA function that accepts an object with the same shape as your data, it will set this data to your `data` store as well as to every field of the form.\n\n### setTouched\n\nA function that accepts a `string` path for the `touched` store that sets a field to `touched`.\n\n### setError\n\nA function that accepts a `string` path for the `errors` store that sets an error.\n\n### validate\n\nA function that forces Felte to validate all inputs, touches all of them and updates the `errors` store. It has no arguments.\n\n### reset\n\nA function that resets all inputs and the `data` store to its original values. It has no arguments.\n\n### setInitialValues\n\nA helper function that sets the initialValues Felte handles internally. If called after initialization of the form, these values will be used when calling `reset`.\n\n### createSubmitHandler\n\nA function that creates a submit handler with overriden `onSubmit`, `onError` and/or `validate` functions. If nothing is passed as a first argument, or if any of the three accepted properties is undefined, it will use the values from the `createForm` configuration object as a default.\n\n```html\n<script>\n  const { form, createSubmitHandler } = createForm({\n    onSubmit: (values) => console.log('Default onSubmit'),\n  });\n\n  const altOnSubmit = createSubmitHandler({\n    onSubmit: (values) => console.log('Alternative onSubmit'),\n    validate: (values) => /* ... */,\n    onError: (errors) => /* ... */,\n  });\n</script>\n\n<form use:form>\n  <input type=\"email\" name=\"email\">\n  <input type=\"password\" name=\"password\">\n  <button type=\"submit\">Call default submit handler</button>\n  <button type=\"submit\" on:click={altOnSubmit}>Call alternative submit handler</button>\n</form>\n```\n\n> **NOTE**: The returned submit handler **can** be used outside of the `<form>` tag or be called programatically.\n","bodyBegin":15,"frontmatter":"section: Helper functions\nsubsections:\n  - setField\n  - getField\n  - setFields\n  - setTouched\n  - setError\n  - validate\n  - reset\n  - setInitialValues\n  - createSubmitHandler"},{"attributes":{"section":"Reporters","subsections":[{"id":"using-a-svelte-component","name":"Using a Svelte component"},{"id":"using-the-dom","name":"Using the DOM"},{"id":"using-tippy-js","name":"Using Tippy.js"},{"id":"using-the-constraint-validation-api","name":"Using the constraint validation API"}],"id":"reporters"},"body":"## Reporters\n\nFelte offers an easy _plugin-like_ way of reporting your errors by using what we call `reporters`. Making use of Felte's extensibility, their job is to handle errors for you. The degree to which they do that depends on how each reporter is build. For example they can report your errors using a tooltip, or modifying the DOM itself to add your validation messages. You may use any of the official packages we provide, or [you can build your own](/docs/svelte/extending-felte).\n\n### Using a Svelte component\n\nThe `@felte/reporter-svelte` package will fill like a more traditional way to handle your validation messages.\n\n```sh\n# npm\nnpm i -S @felte/reporter-svelte\n\n# yarn\nyarn add @felte/reporter-svelte\n```\n\nIf you're using **[Sapper](https://sapper.svelte.dev)** you might want to add it as a dev dependency.\n\n```sh\n# npm\nnpm i -D @felte/reporter-svelte\n\n# yarn\nyarn add -D @felte/reporter-svelte\n```\n\nIt exports a `svelteReporter` function and a `ValidationMessage` component. Pass the `svelteReporter` function to the `extend` option of `createForm` and add the `ValidationMessage` component wherever you want your validation messages to be displayed.\n\nThe `ValidationMessage` component needs a `for` prop set with the **name** of the input it corresponds to, the error messages will be passed to you via the `messages` slot prop. The default slot will be rendered when there are errors, and the `placeholder` slot when there aren't any. The `placeholder` slot is optional and if not used, you'll need to handle any falsy values for `messages` yourself.\n\n```html\n<script>\n  import { svelteReporter, ValidationMessage } from '@felte/reporter-svelte';\n  import { createForm } from 'felte';\n\n  const { form } = createForm({\n      // ...\n      extend: svelteReporter,\n      // ...\n    },\n  })\n</script>\n\n<form use:form>\n  <input id=\"email\" type=\"text\" name=\"email\">\n  <ValidationMessage for=\"email\" let:messages={message}>\n    \n    \n    <span>{message}</span>\n    <span slot=\"placeholder\">Please type a valid email.</span>\n  </ValidationMessage>\n  <input type=\"password\" name=\"password\">\n  <ValidationMessage for=\"password\" let:messages={message}>\n    <span>{message || ''}</span>\n  </ValidationMessage>\n  <input type=\"submit\" value=\"Sign in\">\n</form>\n```\n\n### Using the DOM\n\nThe `@felte/reporter-dom` is similar to the `@felte/reporter-svelte` package, but it modifies the dom directly for you.\n\n```sh\n# npm\nnpm i -S @felte/reporter-dom\n\n# yarn\nyarn add @felte/reporter-dom\n```\n\nThe default export is a function you can pass options to that describe the behaviour. The current options are:\n\n```typescript\ninterface DomReporterOptions {\n  listType?: 'ul' | 'ol';\n  single?: boolean;\n}\n```\n\n- `single` tells the reporter to display only a single message with a `span` element. If false, displays the messages in a list. Default: `false`.\n- `listType` defines the element to be used for the list. Default: `ul`.\n\nAdd it to the `extend` property of Felte's `createForm` configuration object.\n\n```javascript\nimport reporterDom from '@felte/reporter-dom';\n\nconst { form } = createForm({\n  // ...\n  extend: reporterDom(),\n  // ...\n});\n```\n\nIn order to show the errors for a field, you'll need to add a container for each of these elements. For example\n\n```html\n<label for=\"email\">Email:</label>\n<input name=\"email\" aria-describedby=\"email-validation\">\n<div id=\"email-validation\" data-felte-reporter-dom-for=\"email\" aria-live=\"polite\" />\n```\n\nYou can choose individually if you want to show errors as a `span` or a list with the attributes `data-felte-reporter-dom-as-single` and `data-felte-reporter-dom-as-list` respectively.\n\n\n#### Styling\n\nThis reporter will add the error messages inside of your container element.\n\nIf the `single` option is `true`, then it will add a single message in a `span` element with the attribute `data-felte-reporter-dom-single-message`. You can style this with the CSS selector `[data-felte-reporter-dom-single-message]`.\n\nIf `single` is `false` the it will add a single list (using the element defined in `listType`) with the attribute `data-felte-reporter-dom-list`. The list will containe a `li` element per message, each with the attribute `data-felte-reporter-dom-list-message`. You can style them using a similar CSS selector as described above.\n\n### Using Tippy.js\n\nThe `@felte/reporter-tippy` package leverages **[Tippy.js](https://atomiks.github.io/tippyjs/)** to report your validation messages. You will also need to install Tippy.js as a separate dependency to use it.\n\n```sh\n# npm\nnpm i -S @felte/reporter-tippy tippy.js\n\n# yarn\nyarn add @felte/reporter-tippy tippy.js\n```\n\nYou may also want to add Tippy's CSS somewhere in your project.\n\n```javascript\nimport 'tippy.js/dist/tippy.css';\n```\n\nIn order to use it, you'll need to import it in your component and add it to the `extend` option of `createForm`.\n\n```javascript\nimport reporter from '@felte/reporter-tippy';\nimport { createForm } from 'felte';\n\nconst { form } = createForm({\n  // ...\n  extend: reporter(),\n  // ...\n});\n```\n\nAnd that's it! Your validation messages will be shown by Tippy without any more work.\n\nFor a more complex use case, you can pass [options](https://atomiks.github.io/tippyjs/v6/all-props/) to Tippy when calling the reporter like so:\n\n```javascript\nreporter({\n  tippyProps: {/* tippy options */},\n})\n```\n\nYou can also pass a `setContent` function that will receive the current validation messages for the field and its path. Here you can modify your validation messages, which can come in useful if you want to display HTML content inside of Tippy. The `messages` argument will either by an array of strings (it can be more than one message depending on your validation strategy) or undefined. The `path` argument will be a string with the full path of your field (e.g. `email`, `account.email`, etc).\n\n```javascript\nreporter({\n  setContent: (messages, path) => {\n    return messages?.map(message => `<p>${message}</p>`);\n  },\n  tippyProps: {\n    allowHTML: true,\n  },\n})\n```\n\nYou may also pass options to a specific Tippy instance using the `tippyPropsMap` property. It expects an object with the same shape as your data:\n\n```javascript\nreporter({\n  tippyPropsMap: {\n    account: {\n      email: {\n        allowHTML: true,\n        /* other tippy props */\n      },\n    },\n  },\n})\n```\n\nYou may also opt-out of this package reporting your errors for a specific field by adding `data-felte-reporter-tippy-ignore` to the input:\n\n```html\n<input name=\"email\" data-felte-reporter-tippy-ignore>\n```\n\nIf you're using a custom control not managed by Felte, you can still make use of `@felte/reporter-tippy`. For this you can use two data attributes:\n\n- `data-felte-reporter-tippy-for`: tells this package to use the element with this attribute as a control for the specified field.\n- `data-felte-reporter-tippy-trigger-for`: tells this package to use the element(s) with this attribute as a trigger to show Tippy for the specified field.\n\nThe custom control will always be a trigger for tippy, the second argument is useful if you want to trigger Tippy with another element such as a label to mimic this package's default behaviour.\n\n```html\n<span id=\"email-label\" data-felte-reporter-tippy-trigger-for=\"email\">Email:</span>\n<div contenteditable data-felte-reporter-tippy-for=\"email\" aria-labelledby=\"email-label\" tabindex=\"0\" />\n```\n\nIf you need to show your Tippy in a different position, you may use the `data-felte-reporter-tippy-position-for` attribute. This would be useful if you're using a custom control that does use a valid HTML input behind the scenes but hides it:\n\n```html\n\n<div data-felte-reporter-tippy-position-for=\"email\" />\n\n<input name=\"email\" type=\"email\">\n```\n\n### Using the constraint validation API\n\nThe `@felte/reporter-cvapi` package leverages the browser's [constraint validation API](https://developer.mozilla.org/en-US/docs/Web/API/Constraint_validation) to report errors.\n\n```sh\n# npm\nnpm i -S @felte/reporter-cvapi\n\n# yarn\nyarn add @felte/reporter-cvapi\n```\n\nIn order to use it, add it to the `extend` property of Felte's `createForm` configuration object.\n\n```javascript\nimport { createForm } from 'felte';\nimport reporter from '@felte/reporter-cvapi';\n\nconst { form } = createForm({\n  // ...\n  extend: reporter,\n  // ...\n});\n```\n\nAnd that's it!\n\n> **NOTE**: This might not be recommended since it might not be friendly for mobile users.\n","bodyBegin":10,"frontmatter":"section: Reporters\nsubsections:\n  - Using a Svelte component\n  - Using the DOM\n  - Using Tippy.js\n  - Using the constraint validation API"},{"attributes":{"section":"Custom form controls","id":"custom-form-controls"},"body":"## Custom form controls\n\nIf for some reason you're not using an HTML5 input, select or textarea element as an input, you can always bind to the `data` store in order to let Felte manage your custom controls.\n\n```html\n<script>\n  import { createForm } from 'felte';\n\n  const { form, data } = createForm({ /* ... */ });\n</script>\n\n<form use:form>\n  <SomeCustomControl bind:value={$data.customControlName} />\n</form>\n```\n\nYou may also use any of the returned [helpers from `createForm`](/docs/svelte/helper-functions) for this as well.\n\n```html\n<script>\n  import { createForm } from 'felte';\n\n  const { form, setField } = createForm({ /* ... */ });\n\n  function handleChange(event) {\n    setField('customControlName', event.detail.value);\n  }\n</script>\n\n<form use:form>\n  <SomeCustomControl on:customChangeEvent=\"{handleChange}\" />\n</form>\n```\n\n> **NOTE**: If your custom form control uses an `input` or other native form control behind the scenes, you may dispatch an `input` or `change` event from it when the value of it changes (if your control does not do this already). Felte listens to `change` events for `<input type=\"checkbox\">`, `<input type=\"radio\">`, `<select>` and `<input type=\"file\">` elements; and for `input` events on any other type of `input`.\n","bodyBegin":5,"frontmatter":"section: Custom form controls"},{"attributes":{"section":"Multi page forms","id":"multi-page-forms"},"body":"## Multi page forms\n\n[Where possible, long forms should be divided into multiple smaller forms that constitute a series of logical steps or stages](https://www.w3.org/WAI/tutorials/forms/multi-page/). If you were building something like this on a traditional server-side rendered site, the most logical thing to do would be to have a separate, distinct form for each step. The submit action of each step would do something with the current data and go to the next step. If you want to keep your forms in a way that would make them work without JS, this is the way you will need to do it with Felte as well. Here we will outline a possible solution on how to handle this that might serve as inspiration for your own solution.\n\n### Structure of each page\n\nEach page can be made the same as how you would do a single page form, with a few additions:\n\n- We need a way to communicate to the parent that the current form has been submitted.\n- We need a way to communicate to the parent that the user wants to go to the previous page.\n- We need a way to set initial values for the current page to display the most up to date information of our forms when navigating our pages.\n\nThe easiest way to do this would be to pass our initial values and handlers as props, but you may use custom events or context for this. As an example, we will use props in this case:\n\n```html\n<script>\n  import { createForm } from 'felte';\n\n  export let initialValues;\n  export let onSubmit;\n  export let onBack;\n\n  const { form, data } = createForm({ onSubmit });\n</script>\n\n<form use:form>\n  <input name=\"firstName\">\n  <input name=\"lastName\">\n  <input name=\"aboutMe\">\n  <button type=\"button\" on:click=\"{() => onBack($data)}\">\n    Previous page\n  </button>\n  <button type=\"submit\">Next page</button>\n</form>\n```\n\n### Parent component\n\nOur parent component's purpose will be to handle the state of all of our pages, to keep track of the current page we're in and to handle when the user submits a form or goes back to a previous page.\n\n```html\n<script>\n  // We import our page components (similar to the one above).\n  import Page1 from './Page1.svelte';\n  import Page2 from './Page2.svelte';\n\n  const pages = [Page1, Page2];\n\n  // The current page of our form.\n  let page = 0;\n\n  // The state of all of our pages\n  let pagesState = [];\n\n  // Our handlers\n  function onSubmit(values) {\n    if (page === pages.length - 1) {\n      // On our final page we POST our data somewhere\n      return fetch('https://example.com/', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify(pagesState),\n      }).then(response => {\n        // We handle the response\n      });\n    } else {\n      // If we're not on the last page, store our data and increase a step\n      pagesState[page] = values;\n      pagesState = pagesState; // Triggering update\n      page +=1;\n    }\n  }\n\n  function onBack(values) {\n    if (page === 0) return;\n    pagesState[page] = values;\n    pagesState = pagesState; // Triggering update\n    page -= 1;\n  }\n</script>\n\n\n<svelte:component\n  this={pages[page]}\n  {onSubmit}\n  {onBack}\n  initialValues={pagesState[page]}\n  />\n```\n\n> We have made a functional example of this on [Svelte's REPL](https://svelte.dev/repl/8eb738732cf74edd86f680c53e6ba253?version=3.44.2).\n","bodyBegin":5,"frontmatter":"section: Multi page forms"},{"attributes":{"section":"Accessibility","id":"accessibility"},"body":"## Accessibility\n\nFelte's main package only cares about handling the reactivity of your form. In this sense, you should be the one taking into consideration the accessibility of it, like the correct use of labels, proper color contrast, focus management, etc.\n\nThat said, the `reporter` packages do have some accessibility considerations built-in:\n\n- **`@felte/reporter-tippy`** sets `aria-invalid` for each invalid field and announces to screen readers whenever a tooltip appears and whenever it changes by setting an `aria-live` attribute to the tooltip instance itself. Tippy itself also adds an `aria-describedby` attribute to your input. If there are errors on submit, it'll focus the first invalid element of your form.\n- **`@felte/reporter-dom`** sets `aria-invalid` for each invalid field and announces to screen readers whenever an error message is displayed on your container by setting an `aria-live` attribute to them. It also focuses the first invalid input if therer are errors on submit.\n- **`@felte/reporter-cvapi`** while not recommended due to its non-friendly behaviour for mobile users, it is accessible by default since it uses the browser's built-in validation mechanism.\n- **`@felte/reporter-svelte`** sets `aria-invalid` for each invalid field, but doesn't provide anything else like the previous packages since the display of the error message is up to you, so you should consider using `aria-live` appropriately.\n","bodyBegin":5,"frontmatter":"section: Accessibility"},{"attributes":{"section":"Extending Felte","id":"extending-felte"},"body":"## Extending Felte\n\n> **NOTE**: This API is not set in stone yet. It is open for change on feedback or future needs.\n>\n> If you're a package author and this API is missing any feature, please do [open an issue](https://github.com/pablo-abc/felte/issues) or [make a pull request](https://github.com/pablo-abc/felte/pulls).\n\nYou might have noticed that both `reporters` and `validators` make use of the `extend` property in the configuration for `createForm`. This is because both of these make use of Felte's extensibility. We will call any package that extends Felte an `extender` from now.\n\nAn `extender` is a simple function that gets called when `createForm` is called, when the `form` action is called and whenever the form changes.\n\n```javascript\nfunction extender({\n  form,\n  controls,\n  data,\n  errors,\n  touched,\n  config,\n}) {\n  // ...\n  return {\n    destroy() {\n      // ...\n    },\n    onSubmitError(errors) {\n      // ...\n    },\n  }\n}\n```\n\n- `form` refers to the [HTMLFormElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement) of the form you're handling. The first time the extender is called, this will be `undefined`. Whenever the `form` action is called (and on any subsequent call) this will contain the appropriate element.\n- `controls` refer to the the form controls of the form that are handled by Felte. The first time the extender is called, this will be `undefined`. Whenever the `form` action is called (and on any subsequent call) this will contain the appropriate elements.\n- `data` is the same `data` store that `createForm` returns.\n- `errors` is the same `errors` store that `createForm` returns.\n- `touched` is the same `touched` store that `createForm` returns.\n- `config` is the configuration object passed by the user to `createForm`.\n\nIf you're subscribing to any store, or adding any event listeners in the extender, you will want to unsubscribe and/or remove any event listeners in the `destroy` function that you can return from the extender. If you're not using any events or subscribing to any store, you don't need to set this.\n\nIf you want to perform an action whenever there are errors on a `submit` event (e.g. server validation), you can handle them in the `onSubmitError` function. This will receive the current values contained in the `errors` store.\n\nYou may check [Felte's repo](https://github.com/pablo-abc/felte) and go over any validator or reporter source code. You'll find they're quite simple.\n\n> **NOTE**: If you check the `validator` packages you'll notice that you **can** change the signature of the configuration object for `createForm` in order for it to be used by your extender.\n","bodyBegin":5,"frontmatter":"section: Extending Felte"},{"attributes":{"section":"Configuration reference","id":"configuration-reference"},"body":"## Configuration reference\n\nFelte's `createForm` function accepts a configuration object with the following properties:\n\n- **onSubmit**: a function that receives as a first argument the submitted data, and as a second argument a `context` object with the following properties:\n  - **form**: the native HTML form element.\n  - **controls**: the form's native HTML controls.\n  - **config**: the current configuration of the form.\n- **validate**: a validation function (or array of functions) that receives the data to validate and returns an `errors` object, or `undefined` if the data is valid. The validation functions may be asynchronous. See [Validation](/docs/svelte/validation).\n- **warn**: a validation function (or array of functions) that receives the data to validate and returns an object with the same shape as `data`, but with warning messages or `undefined` as values. It can be an array of functions whose validation errors will be merged. See [Validation](/docs/svelte/validation#warnings).\n- **transform**: a transformation function (or array of functions) that receives the data coming from your form and returns a `data` object. See [Transformations](/docs/svelte/transformations).\n- **onError**: a function that receives any unhandled errors thrown in the `onSubmit` function. Useful for handling [server errors](/docs/svelte/validation#server-errors).\n- **extend**: an extender or array of extenders. Currently these are either [validators](/docs/svelte/validators) or [reporters](/docs/svelte/reporters). Note that extenders may add/change this same configuration object. Check their documentation when adding one.\n\n> Every property is optional, except `onSubmit`.\n","bodyBegin":5,"frontmatter":"section: Configuration reference"}]</article></body></html>