FileField
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…
defaultRendu de l’aperçu en cours…
dropzoneRendu de l’aperçu en cours…
chipsStructure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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.
- chipsbooleanfalse
- Renders each selected file as a closable chip (shortcut for display="chips").
- counterbooleanfalse
- Shows a file count badge and total size hint in the field.
- counterSizeStringstring
- counterStringstring
- placeholderstring
- Placeholder text shown in the field when no file is selected.
- persistentPlaceholderboolean
- persistentCounterboolean
- multiplebooleanfalse
- Allows selecting multiple files at once.
- 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.
- chipPropsIChipProps
- maxFileSizenumber
- Maximum allowed file size in bytes. Files exceeding this emit the error:max-size event.
- dragndropbooleanfalse
- Alias for dropzone. Kept for backward compatibility.
- dragndropIconstring'mdi-cloud-upload-outline'
- Icon displayed in the dropzone upload area.
- browseTextstring
- Label for the click-to-browse link inside the dropzone.
- fileIconstring'mdi-file-outline'
- Icon used as the generic file glyph on list and DnD items.
- removeIconstring'mdi-close'
- Icon for the remove/clear action on each file item.
- downloadIconstring'mdi-download'
- Icon for the download action on each file item (visible when downloadable=true).
- downloadablebooleanfalse
- Shows a download action button on each file item.
- progressArray<number>
- Upload progress for each file (0–100). Drives the progress bar on DragNDrop items and list items.
- dropzoneTitlestring
- Primary text shown inside the dropzone (e.g. "Drag & drop files here").
- dropzoneSubtitlestring
- Secondary text shown below the dropzone title (e.g. "or click to browse").
- maxFileSizeErrorStringstring
- Custom error message displayed when a file exceeds maxFileSize.
- How multi-file selection is rendered: 'list' (default card stack) | 'chips' (each file as a closable chip) | 'counter' (single "{n} files" summary).
- dropzonebooleanfalse
- 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.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- color
- Active border and label colour.
- Field density.
- centerAffixboolean
- dirtyboolean
- disabledbooleanfalse
- Disables the field. Prevents file selection and drag events.
- errorstring | boolean
- inlineboolean
- labelstring
- Floating label text.
- prefixstring
- suffixstring
- persistentClearboolean
- singleLineboolean
- requiredboolean
- loadingTControlLoadingValue
- tagstring
- loadingTextstring
- bgColorTColor
- appendInnerAvatarstring
- appendInnerIconTIcon
- prependInnerAvatarstring
- prependInnerIconTIcon
- clearIconTIcon
- clearableboolean
- prependInnerAriaLabelstring
- appendInnerAriaLabelstring
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- focusedboolean
- textstring
- floatingboolean
- namestring
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- roundedboolean | number | string | TRounded | null | undefined
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
- activeboolean | IStateEffectConfig
- activeClassstring
- Visual style: outlined | underlined | filled | solo | plain.
- elevationTElevation
- sizeTSize | number
- hideDetailsboolean | string
- hideSpinButtonsboolean
- hintstring
- persistentHintboolean
- messagesArray<string> | string
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- directionTDirection
- errorMessagesArray<string> | string
- maxErrorsnumber | string
- readonlybooleanfalse
- Makes the field non-interactive without changing its visual state.
- rulesArray<any>
- validateOnTValidateOn
- validationValueany
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
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:controlMouseEvent
- Fired when the main field control area is clicked.
- @mousedown:controlMouseEvent
- @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:focusedany
- @click:appendInnerMouseEvent
- @click:prependInnerMouseEvent
- @click:clearMouseEvent
- @update:modelValueany
- Fired when the selected file(s) change.
- @click:appendMouseEvent
- @click:prependMouseEvent
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
| Touche | Action |
|---|---|
| Tab | Moves focus to the file input or dropzone label. |
| Enter / Space | Opens 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.
- colorrgba(0, 0, 0, 0)
- Default dropzone background.
- colorvar(--origam-color__border---default)
- Dropzone dashed border and text colour.
- dimensionvar(--origam-radius---md)
- Dropzone corner radius (8px).
- dimension140px
- Minimum height of the empty dropzone.
- colorvar(--origam-color__feedback--info---bgSubtle)
- Dropzone background during dragover.
- colorvar(--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
Dropzone mode
Chips display
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.