Correct and idiomatic ways to use the <mds-file-preview> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in agents/variants.md and the shared component rules in agents/conventions.md.

Minimal File Card

The required prop is filename. The component infers icon, badge colour, and type description automatically from the extension. Always pass a real filename with extension.

<mds-file-preview filename="relazione-annuale.pdf"></mds-file-preview>

File Card with Size

Pass filesize as a numeric byte count and the component formats it automatically (JEDEC: KB, MB, GB). Pass a plain string to show a pre-formatted label verbatim.

<!-- Numeric bytes - auto-formatted to "9.77 MB" -->
<mds-file-preview filename="contratto.docx" filesize="10248594"></mds-file-preview>

<!-- Pre-formatted string - shown verbatim -->
<mds-file-preview filename="archivio.zip" filesize="12 MB"></mds-file-preview>

Download Interaction

The whole card is clickable: the component emits mdsFileDownload with { target, filename, extension } on click. Add downloadable to declare the intent; the current release emits the event with or without it. Listen to the event; do not add a click handler on a wrapper element.

<mds-file-preview
  filename="documento.pdf"
  filesize="2048000"
  downloadable
></mds-file-preview>

document.querySelector('mds-file-preview').addEventListener('mdsFileDownload', (e) => {
  const { filename, extension } = e.detail;
  console.log('Download richiesto:', filename, extension);
});

Delete Affordance

Add deletable to show a dismiss button in the top-right corner. The component emits mdsFileDelete with { target, filename, extension }. The consumer is responsible for removing the element from the DOM.

<mds-file-preview
  filename="bozza.docx"
  filesize="512000"
  deletable
></mds-file-preview>

document.querySelector('mds-file-preview').addEventListener('mdsFileDelete', (e) => {
  e.detail.target.remove();
});

Image Thumbnail

Set src to show a thumbnail instead of the generic icon. The thumbnail renders only when the format supports preview (images) and no message is set; other formats fall back to the icon.

<mds-file-preview
  filename="foto-profilo.jpg"
  filesize="84791746"
  src="./thumbnails/foto-profilo-thumb.webp"
></mds-file-preview>

Status / Feedback State

Set message to switch the card to a feedback layout - the thumbnail is suppressed and the text is displayed alongside the icon. Pair with variant to colour the status region semantically. variant has no visual effect without message.

<!-- Errore di formato -->
<mds-file-preview
  filename="documento.exe"
  message="Formato file non consentito"
  variant="error"
></mds-file-preview>

<!-- Caricamento in corso -->
<mds-file-preview
  filename="video.mp4"
  filesize="52428800"
  message="Caricamento in corso..."
  variant="info"
></mds-file-preview>

Overriding Format Detection

Use suffix to force a known extension category when the filename has no extension or the extension is ambiguous. Use description to override only the textual type caption while leaving icon and badge inference intact.

<!-- Force suffix when filename has no extension -->
<mds-file-preview filename="report" suffix="pdf"></mds-file-preview>

<!-- Custom description label, icon unchanged -->
<mds-file-preview
  filename="modulo.pdf"
  description="Modulo di iscrizione"
></mds-file-preview>

Custom Icon

Set icon to override the auto-detected glyph with any icon slug from the Magma library, or a data:image/svg+xml;base64, URI for a dynamic icon from an API.

<!-- Named icon slug -->
<mds-file-preview
  filename="report.csv"
  filesize="32768"
  icon="mi/baseline/table-chart"
></mds-file-preview>

Filename Truncation

truncate defaults to word, which keeps the filename on one line with an ellipsis. Use all to clamp it to two lines with an ellipsis. Use none to allow the filename to wrap freely.

<mds-file-preview
  filename="Questo-e-uno-dei-nomi-file-piu-lunghi-che-lumanita-abbia-mai-visto.docx"
  filesize="84791746"
  truncate="all"
></mds-file-preview>

Inside mds-input-upload

<mds-file-preview> is the child card rendered by mds-input-upload. When integrating with the upload component, let mds-input-upload manage the cards rather than instantiating mds-file-preview directly.

<mds-input-upload
  max-files="5"
  accept=".pdf,.docx"
></mds-input-upload>

Styling Customization

Style the card only through its documented --mds-file-preview-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) and the --magma-radius-* scale so dark mode and the corner geometry keep working.

.carta-allegato mds-file-preview {
  --mds-file-preview-background-color: rgb(var(--magma-accent-surface-subtle));
  --mds-file-preview-border-radius: var(--magma-radius-md);
  --mds-file-preview-icon-background: rgb(var(--magma-accent-emphasis));
  --mds-file-preview-icon-color: rgb(var(--magma-accent-on-emphasis));
}