Correct and idiomatic ways to use the <mds-input-upload> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Single-File Upload (Default)

The simplest form. Without any attributes the drop zone accepts one file of any type up to 20 MB. Inside a <form> it submits the accepted files under its name, as a native file input does: post the form as multipart/form-data to send their contents.

<form action="/upload" method="post" enctype="multipart/form-data">
  <mds-input-upload name="allegato"></mds-input-upload>
  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
</form>

To send the form with your own code, new FormData(form) carries the files too.

<form id="modulo-upload" action="/upload">
  <mds-input-upload name="allegato"></mds-input-upload>
  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
</form>

<script>
  document.querySelector('#modulo-upload').addEventListener('submit', async (e) => {
    e.preventDefault();
    await fetch(e.target.action, { method: 'POST', body: new FormData(e.target) });
  });
</script>

Restricting Accepted File Types

Set accept to a comma-separated list of MIME types, wildcard MIME types, or extensions. The native file picker and the per-file validator both respect the same value.

<!-- Solo PDF -->
<mds-input-upload accept=".pdf"></mds-input-upload>

<!-- Immagini di qualsiasi formato -->
<mds-input-upload accept="image/*"></mds-input-upload>

<!-- Mix di MIME esplicito ed estensione -->
<mds-input-upload accept="application/pdf, image/jpeg, .png"></mds-input-upload>

Limiting File Size

Set max-file-size (in MB) to reject files above that threshold. Each oversized file is shown as an error preview with a localized message and excluded from the form value.

<mds-input-upload accept="image/*" max-file-size="5"></mds-input-upload>

Multi-File Upload

Set max-files to a number greater than one to enable multiple selection. The native picker switches to multi-select mode automatically; the progress bar tracks how many slots are filled. The form submits one name entry per accepted file.

<mds-input-upload
  name="allegati"
  accept=".pdf, image/jpeg, image/png"
  max-file-size="70"
  max-files="3"
></mds-input-upload>

Seeding with Initial Files

Pass a FileList or File[] to initialValue to prepopulate the control - useful when editing an existing record that already has attachments. The files reach the previews, getFiles(), the form value and mdsInputUploadChange whether you assign them before or after the first render. Reassigning the prop re-runs the add pipeline, including validation.

<mds-input-upload id="allegati"></mds-input-upload>
<script>
  const upload = document.querySelector('#allegati');
  // seed with files already loaded from the server as File objects
  upload.initialValue = existingFiles;
</script>

Listening for File Changes

The mdsInputUploadChange event fires with the current valid FileList (or null) on every add, remove, or reset. Use it to drive UI outside the component - for example to enable a submit button only when files are present.

<mds-input-upload id="doc-upload" accept=".pdf" max-files="5"></mds-input-upload>
<script>
  document.querySelector('#doc-upload').addEventListener('mdsInputUploadChange', (e) => {
    const files = e.detail;
    console.log('File selezionati:', files ? files.length : 0);
  });
</script>

Programmatic Control via Methods

Use the imperative API for host-driven workflows. getFiles() returns the accepted files (an empty FileList when there are none), getFilesError() returns any validation errors, and reset() clears all selections.

<mds-input-upload id="upload-contratto" accept=".pdf" max-file-size="10"></mds-input-upload>
<mds-button id="btn-verifica" label="Verifica"></mds-button>
<mds-button id="btn-annulla" label="Annulla" tone="outline"></mds-button>
<script>
  const upload = document.querySelector('#upload-contratto');

  document.querySelector('#btn-verifica').addEventListener('click', async () => {
    const errors = await upload.getFilesError();
    if (errors) {
      console.warn('Errori nei file:', errors);
      return;
    }
    const files = await upload.getFiles();
    console.log('Pronti per il caricamento:', files);
  });

  document.querySelector('#btn-annulla').addEventListener('click', () => {
    upload.reset();
  });
</script>

Exposing the Sort Chooser

Setting sort to "date" or "status" makes the sort tab bar visible once more than one file is present. The files start in the sort order; once the user picks another order from the tab bar, it stays in place as files are added, and the choice is persisted to localStorage. The highlighted tab is always the order applied. When sort is omitted, no tab bar is shown and the last localStorage preference is applied silently.

<!-- Mostra il selettore di ordinamento, avviato su "per data" -->
<mds-input-upload sort="date" max-files="5"></mds-input-upload>

<!-- Mostra il selettore di ordinamento, avviato su "per stato" -->
<mds-input-upload sort="status" max-files="5"></mds-input-upload>

Form Reset Behavior

The component is form-associated: a form reset clears every selected file automatically, without calling reset() explicitly.

<form id="modulo-allegati">
  <mds-input-upload name="allegati" accept=".pdf" max-files="3"></mds-input-upload>
  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
  <mds-button type="reset" label="Cancella tutto" variant="error" tone="outline"></mds-button>
</form>

CSS Customization

Style the component only through its documented --mds-input-upload-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode keeps working.

.upload-area-evidenziata mds-input-upload {
  --mds-input-upload-drag-area-background-color: rgb(var(--magma-accent-surface-subtle));
  --mds-input-upload-drag-area-background-color-on-drag: rgb(var(--magma-accent-surface));
  --mds-input-upload-drag-area-border: 3px dashed rgb(var(--magma-accent-border));
  --mds-input-upload-drag-area-border-on-drag: 3px dashed rgb(var(--magma-accent-emphasis));
  --mds-input-upload-min-cols: 2;
}