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.
Preview
Rendering the live preview…
defaultRendering the live preview…
dropzoneRendering the live preview…
chipsStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and 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
Content slots exposed by this component.
- #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
Events emitted by this component.
- @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
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <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.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- 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
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
Keyboard interactions
| Key | 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.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- 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.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic file input
Dropzone mode
Chips display
Ecosystem
Family
Components from the same folder that share conventions and often compose together.