Skip to main content

Upload

File upload control styled on top of a native <input type="file">. The input is focusable, keyboard-operable, and works with no JavaScript. Use accept to restrict file types and multiple to allow more than one file per submission. Drag-and-drop, per-file previews, progress bars, and client-side validation are deferred to a consumer-chosen third-party library initialized against the .upload element.

Usage​

When to use

  • A form needs the user to attach one or more files
  • A drag-and-drop target is required for image or document upload
  • File previews, progress, and per-item removal are needed

When not to use

  • For a single avatar change - consider a simpler inline edit pattern
  • For pasting rich content - use a content-editable region instead

Do

  • Restrict accept to the file types the server can handle
  • Provide clear instructions about file size and format limits
  • Announce file list changes to assistive tech

Don't

  • Don't hide the native input so completely that it becomes unfocusable
  • Don't rely solely on drag-and-drop - always provide a clickable label fallback

API​

Slots​

SlotRequiredDescription
labelYesVisible label text for the file input.
helper-Helper text rendered below the input.

Props​

PropTypeDefaultDescription
namestring-Name attribute for form submission.
idstring-Associates the control with its label. Auto-generated when omitted.
acceptstring-Comma-separated list of allowed MIME types or file extensions.
is_multipleboolean-Allows selection of more than one file.
is_disabledboolean-Disables the control.
is_requiredboolean-Marks the control as required.
is_invalidboolean-Marks the control as invalid. Renders aria-invalid="true" when set.
helper_idstring-ID of the helper element; the control gets aria-describedby pointing to it.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.requiredAnnotation-Marks the field as mandatory.

Examples​

Sizes​

Sm, default, and lg variants stacked vertically. Padding, font size, and the file-selector button scale together.

Required​

A required field, where the preceding label picks up its asterisk from the control rather than from any markup of its own.

Accessibility​

  • WCAG 2.2 AA
  • The native <input type="file"> remains focusable and operable via the keyboard
  • The visible label is linked to the input via for / id
  • File list changes are announced via aria-live="polite"
  • Remove buttons have descriptive labels that include the file name
  • accept and multiple define native input behavior; file size/count limits are enforced via JavaScript plus server-side validation (for example data-max-size / data-max-files) and surfaced via aria-invalid

Dependencies​

  • close - per-file remove button uses the close component
  • Optional: Dropzone, FilePond, or Uppy for progressive enhancement

Progressive enhancement​

  • No JS: native file input with a styled label; multiple file selection via multiple; type filtering via accept; file size/count limits enforced via JS plus server-side validation (for example data-max-size / data-max-files)
  • With JS: drag-and-drop drop zone, file list with previews, per-file progress, client-side type/size validation, per-item remove action
  • How to enable: include a third-party library (see Dependencies) and initialize it against the .upload element

The base component works without JS. Advanced features can be added via well-maintained third-party libraries:

  • Dropzone fork (NicolasCARPi) - actively maintained fork of the original Dropzone, no dependencies, drag-and-drop, progress, file validation
  • FilePond - vanilla JS, CDN-ready, drag-and-drop, preview, reordering, file-type validation
  • Uppy - modular, resumable uploads, large files
  • close - remove button used per file