FileField

Form & Input
stable

File upload input with three display modes (list, chips, counter), an optional drag-and-drop dropzone, file size validation, progress tracking and per-item download/remove actions.

Aperçu

Rendu de l’aperçu en cours…

default

Rendu de l’aperçu en cours…

dropzone

Rendu de l’aperçu en cours…

chips

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

Anatomy of OrigamFileFieldSchematic of the FileField component with 5 numbered internal parts. OrigamInput → OrigamField (label, prepend/append, clearable) __dragndrop / file list (display mode: list | chips | counter) 1 2
Anatomy of <origam-file-field>. The root ① extends OrigamInput → OrigamField (label, icons, clearable). Below the field ②, the display zone renders in one of three modes: list (card stack), chips (closable chips row), or counter ("{n} files").
1.origam-file-field
Root element. Extends OrigamInput which itself renders an OrigamField with label, prepend/append zones, and clearable.
2.origam-file-field__dragndrop
Drag-and-drop wrapper rendered when dropzone/dragndrop=true. Houses the
3.origam-file-field__dropzone
4.origam-file-field__list
Vertical list of OrigamFileFieldListItem cards shown below the field in list display mode.
5.origam-file-field__dropzone-icon / __dropzone-title / __dropzone-subtitle
Inner dropzone content zones: upload icon, primary title text, and secondary subtitle text.

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

chips
boolean
false
Renders each selected file as a closable chip (shortcut for display="chips").
counter
boolean
false
Shows a file count badge and total size hint in the field.
counterSizeString
string
counterString
string
placeholder
string
Placeholder text shown in the field when no file is selected.
persistentPlaceholder
boolean
persistentCounter
boolean
multiple
boolean
false
Allows selecting multiple files at once.
showSize
false
Shows file sizes beside filenames. Pass 1000 for SI (kB) or 1024 for binary (KiB).
modelValue
v-model binding. Accepts a single File, an array of File objects, or null/undefined when empty.
chipProps
IChipProps
maxFileSize
number
Maximum allowed file size in bytes. Files exceeding this emit the error:max-size event.
dragndrop
boolean
false
Alias for dropzone. Kept for backward compatibility.
dragndropIcon
string
'mdi-cloud-upload-outline'
Icon displayed in the dropzone upload area.
browseText
string
Label for the click-to-browse link inside the dropzone.
fileIcon
string
'mdi-file-outline'
Icon used as the generic file glyph on list and DnD items.
removeIcon
string
'mdi-close'
Icon for the remove/clear action on each file item.
downloadIcon
string
'mdi-download'
Icon for the download action on each file item (visible when downloadable=true).
downloadable
boolean
false
Shows a download action button on each file item.
progress
Array<number>
Upload progress for each file (0–100). Drives the progress bar on DragNDrop items and list items.
dropzoneTitle
string
Primary text shown inside the dropzone (e.g. "Drag & drop files here").
dropzoneSubtitle
string
Secondary text shown below the dropzone title (e.g. "or click to browse").
maxFileSizeErrorString
string
Custom error message displayed when a file exceeds maxFileSize.
display
'list'
How multi-file selection is rendered: 'list' (default card stack) | 'chips' (each file as a closable chip) | 'counter' (single "{n} files" summary).
dropzone
boolean
false
Renders the field as a large outlined drag-and-drop zone instead of an inline input. Accepts native drag events and falls back to click-to-browse.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
color
Active border and label colour.
density
'default'
Field density.
centerAffix
boolean
dirty
boolean
disabled
boolean
false
Disables the field. Prevents file selection and drag events.
error
string | boolean
inline
boolean
label
string
Floating label text.
prefix
string
suffix
string
persistentClear
boolean
singleLine
boolean
required
boolean
loading
TControlLoadingValue
tag
string
loadingText
string
bgColor
TColor
appendInnerAvatar
string
appendInnerIcon
TIcon
prependInnerAvatar
string
prependInnerIcon
TIcon
clearIcon
TIcon
clearable
boolean
prependInnerAriaLabel
string
appendInnerAriaLabel
string
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
focused
boolean
text
string
floating
boolean
name
string
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | number | string
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
rounded
boolean | number | string | TRounded | null | undefined
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight
letterSpacing
TLetterSpacing
active
boolean | IStateEffectConfig
activeClass
string
variant
'outlined'
Visual style: outlined | underlined | filled | solo | plain.
elevation
TElevation
size
TSize | number
hideDetails
boolean | string
hideSpinButtons
boolean
hint
string
persistentHint
boolean
messages
Array<string> | string
height
number | string
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
direction
TDirection
errorMessages
Array<string> | string
maxErrors
number | string
readonly
boolean
false
Makes the field non-interactive without changing its visual state.
rules
Array<any>
validateOn
TValidateOn
validationValue
any
appendAvatar
string
appendIcon
TIcon
prependAvatar
string
prependIcon
TIcon
prependAriaLabel
string
appendAriaLabel
string

API

Slots

Emplacements de contenu exposés par ce composant.

#counter
Replaces the file count display with custom markup.
#field
Replaces the entire field zone (both dropzone and list) for full customisation.
#dropzone
Replaces the built-in dropzone content (icon + title + subtitle + browse link). isDragging is true during dragover.
#item
Replaces a single file item in list or dropzone mode. Provides the file object, index, progress value and action callbacks.
#chip
Replaces the entire chips summary in chips/counter display mode.
#selection
Replaces the selected file display area (chips row or counter).
#default
Field slot — replaces the default file input + list/chips/counter rendering.
#loader
#label
#floatingLabel
#prefix
#suffix
#prependInner
#appendInner
#clear
#details
#prepend
#append
#messages
#message

API

Emits

Événements émis par ce composant.

@click:control
MouseEvent
Fired when the main field control area is clicked.
@mousedown:control
MouseEvent
@click:remove
{ file: File, index: number }
Fired when the user clicks the remove button on a file item.
@click:download
{ file: File, index: number }
Fired when the user clicks the download button on a file item.
@drop
{ files: Array<File>, event: DragEvent }
Fired when files are dropped onto the dropzone. Includes the raw DragEvent.
@error:max-size
{ files: Array<File>, maxFileSize: number, message: Array<string> }
Fired when one or more dropped/selected files exceed maxFileSize. Includes the list of rejected files and generated error messages.
@update:focused
any
@click:appendInner
MouseEvent
@click:prependInner
MouseEvent
@click:clear
MouseEvent
@update:modelValue
any
Fired when the selected file(s) change.
@click:append
MouseEvent
@click:prepend
MouseEvent

API

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

<T extends object>(props: T, exclude?: string[]) => Partial<T>
Filters and forwards a subset of props.
Ref<string>
Reactive CSS string generated by useStyle.
string
Unique style-sheet ID for this instance.
() => void
Injects the computed style sheet into the document.
() => void
Removes the injected style sheet.
Ref<boolean>
True once the style sheet has been injected.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

Gap between the dropzone wrapper sections (dropzone + list).
Gap between file-field list items.
Default dropzone background colour.
Dropzone dashed border colour and text colour fallback.
Dropzone corner radius.
Minimum height of the empty dropzone area.
Dropzone background during dragover.
Dropzone border colour during dragover.

Inclusion

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Interactions clavier

Interactions clavier
ToucheAction
TabMoves focus to the file input or dropzone label.
Enter / SpaceOpens the native file picker when the dropzone label has focus.

Notes

  • The dropzone is a <label> element pointing to the hidden <input type="file">. Clicking anywhere on the label opens the native file picker.
  • Drag events (dragenter, dragover, dragleave, drop) are handled on the <label>. The --dragging modifier class provides visual feedback during dragover.
  • When disabled=true, the hidden input is disabled and cursor changes to not-allowed. The dropzone opacity drops to 0.6.
  • When error is truthy, the dropzone border changes to the danger semantic colour. The error message (if a string) is displayed inside the dropzone area.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

Source
color
rgba(0, 0, 0, 0)
Default dropzone background.
color
var(--origam-color__border---default)
Dropzone dashed border and text colour.
dimension
var(--origam-radius---md)
Dropzone corner radius (8px).
dimension
140px
Minimum height of the empty dropzone.
color
var(--origam-color__feedback--info---bgSubtle)
Dropzone background during dragover.
color
var(--origam-color__feedback--danger---bg)
Dropzone border in error state.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic file input

vue

Dropzone mode

vue

Chips display

vue

Écosystème

Famille

Composants du même dossier qui partagent les conventions et se composent souvent ensemble.