FileUploadField

Component

Props

Usage

id

Sets the id of the field.

 <template>
    <FileUploadField id="field-id" />
</template>
 

• Type: string
• Required: true

label

Sets the label of the field.

 <template>
    <FileUploadField label="Sample label" />
</template>
 

• Type: string

ariaLabel

Sets the accessible name passed to the dropzone area when the visual label is hidden. It is also used as preview image alt fallback.

 <template>
    <FileUploadField
        label=""
        ariaLabel="Upload contract files"
    />
</template>
 

• Type: string

title

Sets the drag and drop area title of the field.

 <template>
    <FileUploadField title="Field title" />
</template>
 

• Type: string

helpText

Sets the help text of the field.

 <template>
    <FileUploadField helpText="Example help text" />
</template>
 

• Type: string

helpTextPosition

Sets the position of the help text relative to the field. It uses the Position enum.

 <template>
    <FileUploadField helpTextPosition="top" helpText="Appears above the field" />
</template>
 

• Type: Position
• Default: Position.BOTTOM

Options

icon

Sets the icon of the drag and drop area.

 <template>
    <FileUploadField icon="mdi:upload" />
</template>
 

• Type: string
• Default: 'mdi:cloud-upload-outline'

buttonText

Sets the button text of the field.

 <template>
    <FileUploadField buttonText="Upload file" />
</template>
 

• Type: string

singleFileTitleText

Sets the dropzone title used when multiple is false.

 <template>
    <FileUploadField singleFileTitleText="Drag and drop a file here" />
</template>
 

• Type: string
• Default: 'Drag and drop a file here'

replaceTitleText

Sets the dropzone title shown when preview mode is active and the field is in replace mode.

 <template>
    <FileUploadField replaceTitleText="Upload a new file to replace current one" />
</template>
 

• Type: string
• Default: 'Upload a new file to replace current one'

singleFileButtonText

Sets the select button text used when multiple is false.

 <template>
    <FileUploadField singleFileButtonText="Select file" />
</template>
 

• Type: string
• Default: 'Select file'

replaceButtonText

Sets the select button text shown when preview mode is active and the field is in replace mode.

 <template>
    <FileUploadField replaceButtonText="Replace file" />
</template>
 

• Type: string
• Default: 'Replace file'

upToText

Sets the "up to" text shown next to the maximum file size.

 <template>
    <FileUploadField upToText="up to" />
</template>
 

• Type: string
• Default: 'up to'

modelValue

Binds the selected files to the field.

 <template>
    <FileUploadField v-model="files" />
</template>

<script setup lang="ts">
const files = ref<File[]>([])
</script>
 

• Type: array
• Default: []

validator

Sets the validator function for the field, which controls its internal validation state.

Since this field expects an array value, the validateArrayField utility should be used to perform required field validation.

 <template>
    <FileUploadField :validator="validateArrayField" />
</template>
 

• Type: function
• Default: null

error (v-model:error)

Defines the error message displayed by the field. This prop is bindable via v-model:error, allowing two-way syncing of the validation state.

 <template>
    <FileUploadField v-model:error="errorMessage" />
</template>
 

• Type: string
• Default: ''

disabled

Sets the disabled state of the field.

 <template>
    <FileUploadField disabled />
</template>
 

• Type: boolean
• Default: false

required

Sets the required state of the field.

 <template>
    <FileUploadField required />
</template>
 

• Type: boolean
• Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the label. Set to false to hide it. The hint text defaults to a global setting that can be overridden project-wide, and can also be overridden per field with the optionalLabel prop.

 <template>
    <FileUploadField label="Attachment" :showOptionalLabel="false" />
</template>
 

• Type: boolean
• Default: true

optionalLabel

Overrides the "(optional)" hint text for this specific field, taking priority over the global default.

 <template>
    <FileUploadField label="Attachment" optionalLabel="(not required)" />
</template>
 

• Type: string

multiple

Sets whether multiple file selection is allowed.

 <template>
    <FileUploadField multiple />
</template>
 

• Type: boolean
• Default: false

accept

Sets the accepted file types for upload. It can be a string or an array of strings.

 <template>
    <FileUploadField accept="image/*" />
</template>
 

• Type: string | string[]
• Default: '*'

maxFileSize

Sets the maximum file size (in MB) allowed for each uploaded file.

 <template>
    <FileUploadField :maxFileSize="5" />
</template>
 

• Type: number
• Default: 5

maxFiles

Sets the maximum number of files that can be uploaded.

 <template>
    <FileUploadField :maxFiles="1" />
</template>
 

• Type: number
• Default: 1

fileUploadErrorMessage

Sets the error message displayed when one or more files fail validation.

 <template>
    <FileUploadField fileUploadErrorMessage="File upload failed" />
</template>
 

• Type: string
• Default: 'The size or format of one ore more files is incorrect.'

showPreview

Sets whether to show a preview of the uploaded file.

 <template>
    <FileUploadField showPreview />
</template>
 

• Type: boolean
• Default: false

previewImageUrl

Sets the URL of the image to be shown in the preview.

 <template>
    <FileUploadField 
        showPreview
        previewImageUrl="https://example.com/image.jpg" 
    />
</template>
 

• Type: string

previewContainerClasses

Sets the CSS classes for the preview container.

 <template>
    <FileUploadField 
        showPreview
        previewContainerClasses="w-[150px] h-[150px]" 
    />
</template>
 

• Type: string
• Default: 'w-[120px] h-[120px] min-w-[120px]'

itemsLayout

Sets how uploaded items are rendered (LIST or GRID).

 <template>
    <FileUploadField itemsLayout="grid" />
</template>
 

• Type: DropzoneLayout
• Default: DropzoneLayout.LIST

state

Sets the visual dropzone state (DEFAULT, INDETERMINATE, SUCCESS, ERROR).

 <template>
    <FileUploadField state="success" />
</template>
 

• Type: DropzoneState
• Default: DropzoneState.DEFAULT

selectFileStrategy

Sets how new files are handled when files already exist (MERGE or REPLACE).

 <template>
    <FileUploadField selectFileStrategy="replace" multiple />
</template>
 

• Type: FileSelectStrategy
• Default: FileSelectStrategy.MERGE

showSelectButton

Controls visibility of the select files button.

 <template>
    <FileUploadField :showSelectButton="false" />
</template>
 

• Type: boolean
• Default: true

showClearAllButton

Controls visibility of the clear all button.

 <template>
    <FileUploadField :showClearAllButton="false" />
</template>
 

• Type: boolean
• Default: true

clearAllButtonText

Sets clear all button text.

 <template>
    <FileUploadField clearAllButtonText="Remove all" />
</template>
 

• Type: string
• Default: 'Clear all'

fileTypeIconMap

Overrides default icon mapping by file type/extension key.

 <template>
    <FileUploadField :fileTypeIconMap="{ pdf: 'mdi:file-pdf-box', geo: 'mdi:map-outline' }" />
</template>
 

• Type: Record<string, string>
• Default: {}

totalProgress

Two-way bound overall upload progress value with v-model:totalProgress. This value is used to update the progress bar shown in the dropzone when useServerUpload is true.

 <template>
    <FileUploadField v-model:totalProgress="totalProgress" />
</template>

<script setup lang="ts">
const totalProgress = ref(0)
</script>
 

• Type: number
• Default: 0

useServerUpload

Enables server-side upload mode.

 <template>
    <FileUploadField
        useServerUpload
        uploadUrl="/api/uploads"
        deleteUrl="/api/uploads"
    />
</template>
 

• Type: boolean
• Default: false

uploadUrl

Server endpoint used to upload files.

 <template>
    <FileUploadField useServerUpload uploadUrl="/api/uploads" />
</template>
 

• Type: string

deleteUrl

Server endpoint used to delete uploaded files.

 <template>
    <FileUploadField useServerUpload deleteUrl="/api/uploads" />
</template>
 

• Type: string

uploadHeaders

Custom headers used for upload and delete requests.

 <template>
    <FileUploadField :uploadHeaders="{ Authorization: 'Bearer token' }" />
</template>
 

• Type: Record<string, string>
• Default: {}

uploadAdditionalData

Additional key-value pairs appended to upload FormData.

 <template>
    <FileUploadField :uploadAdditionalData="{ module: 'documents', public: true }" />
</template>
 

• Type: Record<string, string | Blob | number | boolean>
• Default: {}

uploadWithCredentials

Sends upload requests with credentials.

 <template>
    <FileUploadField useServerUpload uploadWithCredentials />
</template>
 

• Type: boolean
• Default: false

uploadingStatusText

Text used while a file is uploading.

 <template>
    <FileUploadField uploadingStatusText="Uploading file" />
</template>
 

• Type: string
• Default: 'Uploading'

successStatusText

Text used after a successful upload.

 <template>
    <FileUploadField successStatusText="Done" />
</template>
 

• Type: string
• Default: 'Uploaded'

errorStatusText

Text used after a failed upload.

 <template>
    <FileUploadField errorStatusText="Try again" />
</template>
 

• Type: string
• Default: 'Upload failed'

pendingStatusText

Text used for files waiting to upload.

 <template>
    <FileUploadField pendingStatusText="Waiting" />
</template>
 

• Type: string
• Default: 'Pending'

retryIcon

Icon used by the retry action button.

 <template>
    <FileUploadField retryIcon="mdi:reload" />
</template>
 

• Type: string
• Default: 'mdi:refresh'

removeIcon

Icon used by the remove action button.

 <template>
    <FileUploadField removeIcon="mdi:trash-can-outline" />
</template>
 

• Type: string
• Default: 'mdi:close'

retryButtonStyleType

Style variant used by the retry action button.

 <template>
    <FileUploadField retryButtonStyleType="neutral-transparent" />
</template>
 

• Type: ButtonStyleType
• Default: ButtonStyleType.NEUTRAL_FILLED

removeButtonStyleType

Style variant used by the remove action button.

 <template>
    <FileUploadField removeButtonStyleType="delete-transparent" />
</template>
 

• Type: ButtonStyleType
• Default: ButtonStyleType.DELETE_FILLED

retryIconClass

Custom class or class list applied to retry icon.

 <template>
    <FileUploadField retryIconClass="text-text-default" />
</template>
 

• Type: string | string[]

removeIconClass

Custom class or class list applied to remove icon.

 <template>
    <FileUploadField :removeIconClass="['text-text-error', 'opacity-90']" />
</template>
 

• Type: string | string[]

retryButtonClass

Custom class applied to retry button wrapper.

 <template>
    <FileUploadField retryButtonClass="rounded-md" />
</template>
 

• Type: string

removeButtonClass

Custom class applied to remove button wrapper.

 <template>
    <FileUploadField removeButtonClass="rounded-md" />
</template>
 

• Type: string

maxItemsContainerHeight

Sets max height in pixels for the list items container before vertical scrolling.

 <template>
    <FileUploadField :maxItemsContainerHeight="280" />
</template>
 

• Type: number

containerClass

Custom class for the root Dropzone container.

 <template>
    <FileUploadField containerClass="bg-background-neutral-subtlest" />
</template>
 

• Type: string

dropzoneClass

Custom class for the drag-and-drop area.

 <template>
    <FileUploadField dropzoneClass="border-border-success" />
</template>
 

• Type: string

titleClass

Custom class for the dropzone title.

 <template>
    <FileUploadField titleClass="text-text-primary" />
</template>
 

• Type: string

descriptionClass

Custom class for the dropzone description.

 <template>
    <FileUploadField descriptionClass="text-text-neutral-subtle" />
</template>
 

• Type: string

iconClass

Custom class or class list for the dropzone icon.

 <template>
    <FileUploadField :iconClass="['text-icon-default', 'opacity-80']" />
</template>
 

• Type: string | string[]

actionsClass

Custom class for the actions container.

 <template>
    <FileUploadField actionsClass="justify-start" />
</template>
 

• Type: string

listClass

Custom class for list layout container.

 <template>
    <FileUploadField listClass="gap-3" />
</template>
 

• Type: string

gridClass

Custom class for grid layout container.

 <template>
    <FileUploadField itemsLayout="grid" gridClass="gap-4" />
</template>
 

• Type: string

fileItemClass

Custom class for each file item card.

 <template>
    <FileUploadField fileItemClass="shadow-xs" />
</template>
 

• Type: string

fileNameClass

Custom class for file name text.

 <template>
    <FileUploadField fileNameClass="text-sm" />
</template>
 

• Type: string

fileMetaClass

Custom class for file metadata text.

 <template>
    <FileUploadField fileMetaClass="text-xs" />
</template>
 

• Type: string

retryAriaLabel

Sets the accessible label for the retry action button on each file item. Useful for i18n.

 <template>
    <FileUploadField retryAriaLabel="Reintentar subida" />
</template>
 

• Type: string
• Default: 'Retry upload'

removeAriaLabel

Sets the accessible label for the remove action button on each file item. Useful for i18n.

 <template>
    <FileUploadField removeAriaLabel="Eliminar archivo" />
</template>
 

• Type: string
• Default: 'Remove file'

transparent

When true, passes transparent to the child Dropzone, removing its state background and showing only the border.

 <template>
    <FileUploadField transparent />
</template>
 

• Type: boolean
• Default: false

Emits