DFormFile

DFormFile - A type-safe wrapper around Bootstrap Vue Next’s BFormFile component. A file picker with a Browse button, the chosen file name, and a drag-and-drop zone, styled like the theme’s text inputs (same height, border, focus ring and crimson invalid state). v-model is a File for a single file, a File[] with multiple (or directory), and null when nothing is chosen (or [] for a cleared multiple model).

Use it instead of hand-building a btn label around a hidden <input type="file">. The Browse button is a real <button>, so it is in the Tab order and opens the picker on Enter or Space.

label-for is required to label it. Give the component an id and pass the same value to DFormGroup’s label-for. Without label-for, DFormGroup renders a <fieldset> with a <legend>, which does not name the button: its accessible name is then just “Browse”. With no visible label, use aria-label.

Live Examples

Props

All props pass through to BFormFile.

Events

Slots

All slots are forwarded with their slot props.

Validation

Pass state to DFormFile itself. false gives the control the crimson invalid border and icon, and shows a sibling DFormInvalidFeedback (and true a sibling DFormValidFeedback), as with DFormInput:

<DFormFile id="contract" v-model="contract" :state="contract ? null : false" />
<DFormInvalidFeedback>Please choose the signed contract.</DFormInvalidFeedback>

A DFormGroup’s state does not reach DFormFile, unlike DFormInput. Bootstrap Vue Next’s BFormFile does not read the group’s state (or its disabled), and the group passes it down through an injection key that bootstrap-vue-next does not export, so the wrapper cannot read it either without depending on a private name. The control’s own state is the one that matters: it colours the control and shows the feedback beside it, including a DFormGroup’s own invalid-feedback (the group renders it after the control). Set the group’s state as well, as in the Invalid State example, only for what the group itself carries: the is-invalid class and aria-invalid on its <fieldset>. disabled does reach the control: a DFormGroup always renders a <fieldset> (label-for only swaps its <legend> for a <label>), so a disabled group disables the Browse button and the native input, the theme greys the control, and dropped files are ignored.

Avoid required on the custom control. It lands on the hidden native input: the browser’s own validation blocks a plain form submit and focuses the invisible input, so the browser’s message is lost. Validate on the server (or in your submit handler) and show the result with state and a feedback message. required works as expected with plain.

Where attributes land

In the custom control, class and style go on the root element, title on the drop zone, and everything else on the hidden native input (tabindex="-1", aria-hidden): name, data-* and listeners such as @focus and @blur. So @focus/@blur do not fire in normal use (the hidden input is out of the Tab order and only the browser’s own required validation focuses it), and aria-describedby on DFormFile does not describe the Browse button. Run blur-style validation on @change or @update:modelValue instead. With plain, every attribute goes on the native input, which is the focusable control.

Methods

Through a template ref: reset() clears the selection, the native input and the model; focus() and blur() act on the Browse button; element is the Browse button (the native input with plain).

Setting v-model to null (or [] with multiple/directory) clears it the same way: the wrapper empties the native input when the model changes to a cleared value, because Bootstrap Vue Next’s BFormFile on its own clears the file name but leaves the files in the hidden native input (and, for [], in the plain input), where a plain form submit (or new FormData(form)) would still send them. It does not emit another update:modelValue.