Skip to content

Commit

Permalink
docs: added file input binding note closes #3522 (#3523)
Browse files Browse the repository at this point in the history
  • Loading branch information
logaretm committed Oct 11, 2021
1 parent 2fee4ac commit 034f0c7
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 4 deletions.
16 changes: 15 additions & 1 deletion docs/content/api/field.md
Expand Up @@ -79,7 +79,21 @@ The `as` prop is very easy to use but also limited as you cannot render a group
</Field>
```

The most crucial part of rendering fields with `v-slot` is that you **must bind the `field` object to your input element/input**, the `field` object contains all the attributes and listeners required for the field to be validated, this is done automatically if you are using the `as` prop.
The most crucial part of rendering fields with `v-slot` is that you **bind the `field` object to your input element/input**, the `field` object contains all the common attributes and listeners required for the field to be validated, this is done automatically if you are using the `as` prop.

<doc-tip title="File Inputs and Custom Components" type="warn">

When rendering File inputs and custom components, binding the `field` object may not be a good idea in these cases as generally you need to pick the suitable attributes that you should bind. In the case of `input[type="file"]` you could do something like this:

```vue
<Field name="file" v-slot="{ handleChange, handleBlur }">
<input type="file" @change="handleChange" @blur="handleBlur" />
</Field>
```

This is because the file input doesn't work with two-way binding since you cannot really force pick a file from a user's device. Custom components may emit different events and may have additional requirements for two-way binding to work. You can check the [UI Libraries](/examples/ui-libraries) section for a few examples on how to do that.

</doc-tip>

When using `v-slot` on the `Field` component you no longer have to provide an `as` prop and then it will become a renderless component.

Expand Down
14 changes: 11 additions & 3 deletions docs/content/guide/components/validation.md
Expand Up @@ -363,11 +363,19 @@ You can also specify if a `handleChange` call should trigger validation or not b

When applying `v-bind="field"` to a Vue component, be careful that the listeners will both be applied for Vue and native DOM events, meaning you might trigger validation unintentionally.

It is recommended that you listen to the proper events when using `v-bind` with custom components, the following sample uses `modelValue` events.
An example of that could be `input[type="file"]` inputs, because you cannot bind the `value` attribute to a file instance which means two-way binding won't work there. In that case, only listing to handful of events makes more sense:

```vue
<Field v-slot="{ handleChange, field }">
<CustomInput :modelValue="field.value" @update:modelValue="handleChange" />
<Field name="file" v-slot="{ handleChange, handleBlur }">
<input type="file" @change="handleChange" @blur="handleBlur" />
</Field>
```

For custom components, it is recommended that you listen to the proper events when using `v-bind` with custom components, the following sample uses `modelValue` events.

```vue
<Field v-slot="{ handleChange, value }">
<CustomInput :modelValue="value" @update:modelValue="handleChange" />
</Field>
```

Expand Down

0 comments on commit 034f0c7

Please sign in to comment.