Skip to content

OrigamFileField ​

<OrigamFileField> is a file input that supports single and multiple selection, chip display, drag-and-drop mode, file size display, and download/remove actions.

Basic usage ​

vue
<template>
    <OrigamFileField v-model="files" label="Upload" />
</template>

<script setup>
import { ref } from 'vue'
const files = ref(null)
</script>

Multiple files and chips ​

vue
<template>
    <OrigamFileField v-model="files" multiple chips show-size />
</template>
PropTypeDefaultDescription
multiplebooleanfalseAllow multiple file selection
chipsbooleanfalseDisplay files as chips
showSizeTFileSizefalseShow file size next to name (false hides it, true picks an auto unit, 1000/1024 force SI/IEC)
chipPropsIChipPropsundefinedProps merged onto each chip's own defaults (closable derived from disabled/readonly, color) — e.g. { pill: true } renders pill-shaped chips; keys in chipProps override the internal defaults

Drag-and-drop mode ​

When dragndrop is set, the field renders as a dropzone instead of a standard field input.

vue
<template>
    <OrigamFileField v-model="files" dragndrop multiple />
</template>
PropTypeDescription
dragndropbooleanEnable drag-and-drop dropzone mode
dragndropIconstringIcon shown in the dropzone
dropzoneTitlestringi18n key for the dropzone title
dropzoneSubtitlestringi18n key for the dropzone subtitle

File actions ​

vue
<template>
    <OrigamFileField v-model="files" downloadable :progress="[50, 100]" />
</template>
PropTypeDescription
downloadablebooleanShow a download button per file
progressnumber[]Upload progress (0–100) per file index
fileIconstringIcon for generic files
removeIconstringRemove button icon
downloadIconstringDownload button icon

The download button only renders when downloadable is true, and — unlike the remove button — stays active while readonly (only disabled disables it): removing a file is destructive, downloading it isn't. It always carries a translated, per-file aria-label via origam.file_field.download_aria_label.

Placeholder ​

vue
<template>
    <OrigamFileField v-model="files" placeholder="No file selected" persistent-placeholder />
</template>
PropTypeDescription
placeholderstringText shown in the field when no file is selected
persistentPlaceholderbooleanKeeps the placeholder visible even when the field isn't focused/dirty (forces the active state, same behaviour as OrigamTextField / OrigamTextareaField / OrigamPasswordField)

Validation ​

vue
<template>
    <OrigamFileField v-model="files" :max-file-size="2097152" />
</template>
PropTypeDescription
maxFileSizenumberMax file size in bytes; larger files are rejected
counterbooleanShow file count in the details area
persistentCounterbooleanAlways show the counter

Slots ​

SlotBindingsDescription
prepend—Content before the field
append—Content after the field
field{ id, isDisabled, isDirty, isValid, isReadonly }Full field body override
dropzone{ isDragging, browse }Custom dropzone content
item{ file, index, progress, remove, download }Custom file item (list or dropzone)
chip{ fileNames, totalBytes, totalBytesReadable, props }Custom chip renderer
selection—Custom selection text
loader—Custom loader
counter{ counter, value, max }Custom counter
details—Details row override
messages{ hasMessages, messages }Messages override

Emits ​

EventPayloadDescription
update:modelValueFile | File[] | nullFile selection changed
click:controlMouseEventThe field control was clicked
mousedown:controlMouseEventMousedown on the field control
click:remove{ file, index }Remove button clicked
click:download{ file, index }Download button clicked
drop{ files, event }Files dropped on the dropzone
error:max-size{ files, maxFileSize, message }Files exceeded maxFileSize
click:prependMouseEventPrepend adornment clicked (inherited from OrigamInput)
click:appendMouseEventAppend adornment clicked (inherited from OrigamInput)
click:prependInnerMouseEventInner prepend adornment clicked (inherited from OrigamField)
click:appendInnerMouseEventInner append adornment clicked (inherited from OrigamField)
click:clearMouseEventClear button clicked (inherited from OrigamField)
update:focusedbooleanFocus state changed (own useFocus(props) call)

Composition ​

The drag-and-drop mode uses two sub-components internally:

  • OrigamFileFieldDragNDropItem — renders a single file inside the dropzone
  • OrigamFileFieldListItem — renders a file in the list below the dropzone

Both are exposed via the item slot for full customisation.

Design tokens ​

TokenDescription
--origam-file-field__dropzone---border-widthDropzone border width
--origam-file-field__dropzone---border-styleDropzone border style
--origam-file-field__dropzone---min-heightMinimum dropzone height
--origam-file-field__dropzone--dragging---background-colorBackground when dragging over
--origam-file-field---list-gapGap between file list items