File

To upload one or multiple files to a remote server.

NOTE

Please note that all uploads performed in this page are mocked (so nothing is uploaded), but that it's totally invisible for the components. They would behave exactly the same with real requests.

How it works

The file input gives you the ability to add files to your forms. You have two ways of uploading them:

Embedded: the files are sent with the rest of the form when it is submitted.
Pre-uploaded: files are uploaded before the form is submitted.

If you want the files to be embedded in the form, just treat the bt-form-file like any other control:

<bt-form-file control="avatar">
    Avatar
</bt-form-file>

If you chose to upload the files before the form is submitted, you must at least define an endpoint to upload the files to:

<bt-form-file control="avatar" url="/upload" method="post">
    Avatar
</bt-form-file>

By default a File object will be stored in the form. You can change that for pre-uploaded files. Please refer to this section for more detail.

All available props are described at the end of the document.

Basic usage

Here is a basic example of a single file upload.

States

Here a demo that illustrates the different states a form file can take:

Multiple files

You can allow multiple files upload by adding the multiple prop:

File type

You can control what type of files can be uploaded via the accept prop:

It accepts one or multiple patterns, separated by ,.

If a pattern starts with a ., it will be tested against the extension of the file name. For example:

<!-- Will only accept files ending with a ".pdf" extension. -->
<bt-form-file accept=".pdf"></bt-form-file>

<!-- Will only accept files ending with a ".png" OR ".jpg" extension. -->
<bt-form-file accept=".png, .jpg"></bt-form-file>

If the pattern doesn't start with a ., it is considered a RegExpopen in new window and is matched against the MIME typeopen in new window of the file. For example:

<!-- Ensure that the MIME type of the file starts with "image/". -->
<bt-form-file accept="image/*"></bt-form-file>

<!-- You can combine both ways. -->
<bt-form-file accept="image/*, .pdf"></bt-form-file>

WARNING

Beware, this way of checking the type of the file does not protect you from malicious users. You should see it more like a friendly feedback for legitimate users that made a mistake (like any client side validation). You should NOT consider the file safe because it has passed the upload checks.

File size

You can also control the size of the files that are uploaded. You have two props for this:

Individual size

To control the size of each uploaded file individually, use the max-individual-size prop. If you allow any number of files to be uploaded, the sum of their size is not constrained.

Total size

Use the max-total-size prop to limit the total size taken by all the files added to the control.

NOTE

Both max-individual-size and max-total-size accept the following inputs:

the size in bytes: max-individual-size="1000" (= 1 kB),
the size as a human friendly string: max-individual-size="1kB" (= 1000 bytes).

If you use the human friendly notation, pay great attention to the format and the case:

1kB means 1 kilobyte, which is equal to 1000 bytes,
1KiB means 1 kibibyte, which is equal to 1024 bytes,
1kb means 1 kilobit, which is equal to 125 bytes (1000 / 8),
1Kib means 1 kibibit, which is equal to 128 bytes (1024 / 8),

B = byte b = bit

Validation

In the examples above, the validation doesn't use the Validation module.

This is because the form validation works on the controls' values. Or the control may only get a value after the upload is done. That's why the file type and size are validated separately, before anything is uploaded.

Other than that, the validation works exactly the same as for any other type of control:

NOTE

Note that the files are only added to the control's value after the upload is done.

You can change this behavior via the ignore-non-uploaded-files prop, see below.

Upload behaviors

By default, files must be uploaded to be added to the control's value, and the upload automatically starts when a file is added to the queue.

You can control these behaviors via the ignore-non-uploaded-files and auto-start props:

Here you can see that the FormControl's value changes immediately, and doesn't require the file to be uploaded beforehand.

NOTE

You could submit the form without uploading the files separately, in which case they would be embedded with the rest of the form's values in the request.

Custom value

By default, a File object is stored in the control's value for each file in the queue. This way, the file can be uploaded with the rest of the form, when submitted.

But, if you upload the file before the form is submitted, you can use the response from the server as value for the file in the form.

To do this, all you need is the server to respond with a value (any value). In the example below we simulate an object response from the server:

Props

Method	Description	Default
v-model	Bidirectional binding for the value of the control.	`undefined`
value	The original value given by the end-user through the html element.	`undefined`
label	The label of the field. Overridden by the `default` slot.	`null`
placeholder	A placeholder value to show when there is no value selected.	`null`
help	A help text to show to the user. Overridden by the `help` slot.	`null`
floating-label	If `true` the label will float above the control and act as a placeholder is there is none.	`true`
floating-errors	If `true` the errors will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`true`
floating-help	If `true` the help text will appear as an icon on the right side of the input that shows a popover. This value is overridden to `true` internally if the control is in a group to preserve layout integrity.	`false`
required	If `true`, a little asterisk extra is shown, indicating to the user that the field is mandatory.	`false`
disabled	For external control of the `disabled` state of the control.	`false`
busy	For external control of the `busy` state of the control.	`false`
debug	If `true`, show the debug overlay.	`false`
tab-index	HTML tab index (for keyboard navigation).	`0`
autofocus	If `true`, the control will try to gain focus when mounted.	`false`
multiple	`true` to accept multiple files.	`false`
auto-start	`true` to auto start uploads when files are queued.	`false`
ignore-non-uploaded-files	If `true`, files not uploaded through the file component will not be added to the form.	`false`
accept	Validation pattern for file types.	`false`
max-individual-size	Limit the size of individual files.	`false`
max-total-size	Limit the cumulated size of all uploaded files.	`false`
url	Url to call to pre-upload the files.	`null`
endpoint	Endpoint to call to pre-upload the files.	`null`
method	The HTTP method to use when doing the upload request.	`'GET'`
url-params	Parameters to add to the upload request. If a variable with the same name is found in the url (surrounded by `{` `}`), it will replace it. Otherwise, it will be added to the query string (after `?`).	`{}`
headers	Additional headers to add to the upload request.	`{}`
i18n	Allow you to override the internal texts generated by the component. This prop intended to be overridden by a theme.	see type

Slots

Name	Description
default or label	Defines the label of the field. This slot takes priority over the `label` prop. Props: none
help	Defines the help text of the field. This slot takes priority over the `help` prop. Props: none
browse	Overrides the whole browse trigger section of the template. Props: `browse`: the function to call to open the file explorer
browse-text	Keep the the default browse trigger design and only overrides the text. Props: none

Theming

Below the list of all CSS variables and selectors available to customize the appearance of the component. If you're not familiar on how the theming works, please refer to the VueThemes documentation.

Variables

Variable	Default	Comment
fontFamily	`var(--bt-font-family-base)`	-
fontSize	`var(--bt-font-size-base)`	-
fontWeight	`var(--bt-font-weight-normal)`	-
textColor	`var(--bt-text-color-base)`	-
backgroundColor	`var(--bt-color-white)`	-
backgroundDisabledColor	Same as `backgroundColor`	-
borderColor	`var(--bt-color-gray-200)`	-
borderRadius	`var(--bt-border-radius-base)`	-
borderWidth	`var(--bt-border-width-base)`	-
borderStyle	`var(--bt-border-style-base)`	-
borderFocusWidth	Same as `borderWidth`	-
borderFocusColor	`var(--bt-color-primary)`	-
borderErrorWidth	Same as `borderWidth`	-
borderErrorColor	`var(--bt-color-red-500)`	-
borderDisabledColor	`var(--bt-color-gray-200)`	-
placeholderX	`0.8rem`	-
placeholderY	`0.75rem`	-
labelTextColor	`var(--bt-text-color-light)`	-
labelTransitionDuration	`0.2s`	-
helpTextColor	`var(--bt-text-color-light)`	-
helpFontSize	`var(--bt-font-size-sm)`	-
errorTextColor	`var(--bt-color-red-500)`	-
errorFontSize	`var(--bt-font-size-sm)`	-
disabledOpacity	`0.5`	-
addonBackgroundColor	`var(--bt-color-gray-50)`	-
addonTextColor	`var(--bt-text-color-light)`	-
browseBorderColor	`var(--bt-color-gray-150)`	-
doneIconColor	`var(--bt-color-green-500)`	-
itemBorderWidth	`1px`	The border separating two files in the queue.
itemBorderStyle	`dashed`	The border separating two files in the queue.
itemBorderColor	`var(--bt-color-gray-150)`	The border separating two files in the queue.
itemSizeTextColor	`var(--bt-text-color-light)`	-
itemSizeFontSize	`var(--bt-font-size-sm)`	-
itemActionButtonTextColor	`var(--bt-color-primary)`	-
itemActionButtonBackground	`none`	-
itemActionButtonHoverBackground	`var(--bt-color-primary-50)`	-
itemActionButtonFocusBackground	`var(--bt-color-primary-50)`	-
itemActionButtonActiveBackground	`var(--bt-color-primary-100)`	-

Selectors

Name	Comment
root	The root container.
label	The container of the label.
help	The non floating help text container.
inputGroup	A container that only include the form field.
input	The actual form control.
fileItem	Global container of files items in the queue.
fileName	Container of the file name.
fileSize	Container of the file size.
fileIcon	Svg icon of the files items in the queue.
fileButtons	Container of the upload controls.

Examples:

cssSelectors: {
    fileSize: {
        fontSize: '...'
    },
    label: {
        color: '...'
    }
}

# File

# How it works

# Basic usage

# States

# Multiple files

# File type

# File size

# Validation

# Upload behaviors

# Custom value

# Props

# Slots

# Theming

# Variables

# Selectors

File

How it works

Basic usage

States

Multiple files

File type

File size

Validation

Upload behaviors

Custom value

Props

Slots

Theming

Variables

Selectors