Light Dark System

File

<zn-file> | ZnFile
Since 1.0 experimental

File controls allow selecting an arbitrary number of files for uploading.

Examples

Basic File Upload with Label

Use the label attribute to give the file control an accessible label.

<zn-file label="Upload Document"></zn-file>

Help Text

Add descriptive help text to a file control with the help-text attribute. For help text that contains HTML, use the help-text slot instead.


Accepted formats: PDF, DOC, DOCX (Max 5MB)
 
<zn-file label="Upload Resume" help-text="Accepted formats: PDF, DOC, DOCX (Max 5MB)"></zn-file>
<br />
<zn-file label="Upload Resume">
  <div slot="help-text">Accepted formats: <strong>PDF, DOC, DOCX</strong> (Max 5MB)</div>
</zn-file>

Multiple Files

Use the multiple attribute to allow users to select more than one file at a time.

<zn-file label="Upload Photos" multiple></zn-file>

Clearable Files

Add the clearable attribute to display a close button next to each selected file, allowing users to remove individual files from the selection. 

<zn-file label="Upload Documents" multiple clearable></zn-file>

Droparea Mode

Use the droparea attribute to render the file control as a bordered upload area with a centered upload button. When a file is selected, the area displays an image preview (for image files) or the file name (for non-previewable files), along with a clear button in the top-right corner. The area also accepts files via drag-and-drop. 

<zn-file label="Upload Files" droparea></zn-file>

Accepted File Types

Use the accept attribute to specify which file types are accepted. This controls which files appear in the file picker dialog and provides client-side validation. 



<zn-file label="Upload Images" accept="image/*" multiple></zn-file>
<br />
<zn-file label="Upload Document" accept=".pdf,.doc,.docx"></zn-file>
<br />
<zn-file label="Upload Text File" accept="text/plain"></zn-file>

Droparea with Accepted Types

Combine droparea and accept for a prominent upload area with file type restrictions. Selected image files render a preview inside the box. 

<zn-file label="Upload Image" accept="image/*" droparea></zn-file>

Droparea with Image Preview

When an image file is selected, the droparea renders a centered thumbnail preview alongside a clear button in the top-right. The example below pre-loads a sample image so you can see the preview state. 

<zn-file class="file-with-preview" label="Primary Logo" accept="image/*" droparea></zn-file>

<script type="module">
  const fileInput = document.querySelector('.file-with-preview');

  await customElements.whenDefined('zn-file');
  await fileInput.updateComplete;

  // Inline SVG sample so the demo works offline. Explicit width/height keep older
  // browsers happy that don't size SVGs from viewBox alone inside <img>.
  const sampleSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" viewBox="0 0 200 200">
    <defs>
      <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
        <stop offset="0%" stop-color="#3b82f6"/>
        <stop offset="100%" stop-color="#7c3aed"/>
      </linearGradient>
    </defs>
    <rect width="200" height="200" rx="24" fill="url(#g)"/>
    <circle cx="100" cy="100" r="50" fill="none" stroke="#000" stroke-width="10"/>
  </svg>`;

  const file = new File([sampleSvg], 'sample-logo.svg', { type: 'image/svg+xml' });
  const dt = new DataTransfer();
  dt.items.add(file);
  fileInput.files = dt.files;
</script>

Droparea with Non-Previewable File

When the selected file is not an image, the droparea displays the file name centered inside the box.

<zn-file class="file-with-doc" label="Upload Document" accept=".pdf,.doc,.docx" droparea></zn-file>

<script type="module">
  const fileInput = document.querySelector('.file-with-doc');

  await customElements.whenDefined('zn-file');
  await fileInput.updateComplete;

  const file = new File(['%PDF-1.4 sample'], 'project-brief.pdf', { type: 'application/pdf' });
  const dt = new DataTransfer();
  dt.items.add(file);
  fileInput.files = dt.files;
</script>

Displaying an Already-Uploaded File (CDN URL)

Use the src attribute to point the file control at an already-uploaded file — for example, a logo hosted on a CDN. The droparea renders the image preview when src points to an image, or the URL as a filename otherwise. Add the show-link attribute to render the current link as a clickable URL beneath the control. Read fileInput.previewSrc to retrieve the current link programmatically (whether from a local selection or the src attribute). 

<zn-file
  class="file-with-cdn"
  label="Primary Logo"
  droparea
  show-link
  src="https://upload.wikimedia.org/wikipedia/commons/1/1b/ViaDeTogniPalazzoStelline.jpg"
></zn-file>

Auto-Submit on Change

Add the trigger-submit attribute to automatically submit the surrounding form whenever the user picks, drops, or clears a file. This is useful for forms that only contain the file control and a CSRF token — no explicit submit button needed. 

<form action="/logo/upload" method="post" enctype="multipart/form-data">
  <input type="hidden" name="_token" value="">
  <zn-file name="logo" droparea trigger-submit accept="image/*"></zn-file>
</form>

Directory Upload

Use the webkitdirectory attribute to allow users to select entire directories instead of individual files. When a directory is selected, all files within it and its subdirectories are included. 

<zn-file label="Upload Folder" webkitdirectory></zn-file>

Directory Droparea

Combine webkitdirectory with droparea for a drag-and-drop folder upload interface. 

<zn-file label="Upload Project Folder" webkitdirectory droparea></zn-file>

Camera Capture

Use the capture attribute to prompt users to use their device’s camera or microphone. This only works on mobile devices and requires the accept attribute to specify the media type. 


<zn-file label="Take Photo" accept="image/*" capture="environment"></zn-file>
<br />
<zn-file label="Take Selfie" accept="image/*" capture="user"></zn-file>

Hide Value

Use the hide-value attribute to suppress the display of selected file names. This is useful when you want to handle file display in a custom way or when working with the trigger slot. 

<zn-file label="Upload File" hide-value></zn-file>

Disabled

Use the disabled attribute to disable the file control.


<zn-file label="Upload Document" disabled></zn-file>
<br />
<zn-file label="Upload Files" droparea disabled></zn-file>

Sizes

Use the size attribute to change the file control’s size. Size medium is the default. 



<zn-file label="Small Upload" size="small"></zn-file>
<br />
<zn-file label="Medium Upload" size="medium"></zn-file>
<br />
<zn-file label="Large Upload" size="large"></zn-file>

Required

Use the required attribute to make the file control mandatory. The form will not submit unless at least one file is selected.


Submit 
<form class="file-required-form">
  <zn-file name="document" label="Upload Required Document" required></zn-file>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>

<script type="module">
  const form = document.querySelector('.file-required-form');

  await Promise.all([
    customElements.whenDefined('zn-button'),
    customElements.whenDefined('zn-file')
  ]).then(() => {
    form.addEventListener('submit', (e) => {
      e.preventDefault();
      const formData = new FormData(form);
      alert('Form submitted with files!');
    });
  });
</script>

Custom Trigger

Use the trigger slot to provide completely custom content for the file control. The trigger will automatically handle click events to open the file picker and drag-and-drop functionality.

Click to upload or drag and drop

SVG, PNG, JPG or GIF (max. 800x400px) 

<zn-file name="custom-upload" multiple>
  <div slot="trigger" style="padding: 2rem; border: 2px dashed var(--zn-color-neutral-300); border-radius: var(--zn-border-radius); text-align: center; cursor: pointer;">
    <zn-icon src="cloud_upload" style="font-size: 3rem; color: var(--zn-color-primary-600);"></zn-icon>
    <p style="margin: 0.5rem 0 0; font-weight: var(--zn-font-weight-semibold);">Click to upload or drag and drop</p>
    <p style="margin: 0.25rem 0 0; font-size: var(--zn-font-size-small); color: var(--zn-color-neutral-600);">SVG, PNG, JPG or GIF (max. 800x400px)</p>
  </div>
</zn-file>

Handling File Events

Listen to zn-change and zn-input events to respond when users select files. Access the selected files through the files property. 

<zn-file class="file-events" label="Upload Files" multiple></zn-file>
<div class="file-event-output"></div>

<script type="module">
  const fileInput = document.querySelector('.file-events');
  const output = document.querySelector('.file-event-output');

  await customElements.whenDefined('zn-file');

  fileInput.addEventListener('zn-change', (e) => {
    const files = fileInput.files;
    if (files && files.length > 0) {
      const fileList = Array.from(files).map(f => `${f.name} (${(f.size / 1024).toFixed(2)} KB)`).join('<br>');
      output.innerHTML = `<strong>Selected files:</strong><br>${fileList}`;
    } else {
      output.innerHTML = '';
    }
  });
</script>

Error Handling

The file control emits a zn-error event when multiple files are dropped without the multiple attribute being set. 

<zn-file class="file-error" label="Upload Single File" droparea></zn-file>
<div class="error-output" style="color: var(--zn-color-danger-600); margin-top: 0.5rem;"></div>

<script type="module">
  const fileInput = document.querySelector('.file-error');
  const errorOutput = document.querySelector('.error-output');

  await customElements.whenDefined('zn-file');

  fileInput.addEventListener('zn-error', () => {
    errorOutput.textContent = 'Error: Only one file can be uploaded at a time.';
    setTimeout(() => {
      errorOutput.textContent = '';
    }, 3000);
  });

  fileInput.addEventListener('zn-change', () => {
    errorOutput.textContent = '';
  });
</script>

Working with FileList

The files property returns a FileList object containing File objects. You can access file information such as name, size, type, and last modified date. 

<zn-file class="file-info" label="Upload Files" multiple clearable></zn-file>
<div class="file-info-output"></div>

<script type="module">
  const fileInput = document.querySelector('.file-info');
  const output = document.querySelector('.file-info-output');

  await customElements.whenDefined('zn-file');

  fileInput.addEventListener('zn-change', () => {
    const files = fileInput.files;
    if (files && files.length > 0) {
      let html = '<table style="width: 100%; border-collapse: collapse; margin-top: 1rem;"><thead><tr style="text-align: left; border-bottom: 1px solid var(--zn-color-neutral-200);"><th>Name</th><th>Size</th><th>Type</th></tr></thead><tbody>';

      Array.from(files).forEach(file => {
        const sizeKB = (file.size / 1024).toFixed(2);
        html += `<tr style="border-bottom: 1px solid var(--zn-color-neutral-100);"><td style="padding: 0.5rem 0;">${file.name}</td><td>${sizeKB} KB</td><td>${file.type || 'unknown'}</td></tr>`;
      });

      html += '</tbody></table>';
      output.innerHTML = html;
    } else {
      output.innerHTML = '';
    }
  });
</script>

Form Integration

File controls work seamlessly with forms. The selected files are submitted as part of the form data when using FormData.



Submit Form Reset 
<form class="file-form" enctype="multipart/form-data">
  <zn-input name="name" label="Your Name" required></zn-input>
  <br />
  <zn-file name="documents" label="Upload Documents" multiple clearable></zn-file>
  <br />
  <zn-button type="submit" variant="primary">Submit Form</zn-button>
  <zn-button type="reset">Reset</zn-button>
</form>
<div class="form-output"></div>

<script type="module">
  const form = document.querySelector('.file-form');
  const output = document.querySelector('.form-output');

  await Promise.all([
    customElements.whenDefined('zn-button'),
    customElements.whenDefined('zn-file'),
    customElements.whenDefined('zn-input')
  ]).then(() => {
    form.addEventListener('submit', (e) => {
      e.preventDefault();
      const formData = new FormData(form);

      let info = `<strong>Form Data:</strong><br>Name: ${formData.get('name')}<br>`;
      const files = formData.getAll('documents');
      if (files.length > 0) {
        info += `<strong>Files (${files.length}):</strong><br>`;
        files.forEach(file => {
          info += `- ${file.name} (${(file.size / 1024).toFixed(2)} KB)<br>`;
        });
      }

      output.innerHTML = info;
    });

    form.addEventListener('reset', () => {
      output.innerHTML = '';
    });
  });
</script>

Programmatic File Access

You can programmatically access and manipulate the file control’s value and files.


Get File Names Clear Files 
<zn-file class="file-programmatic" label="Upload Files" multiple></zn-file>
<br />
<zn-button class="get-files-btn">Get File Names</zn-button>
<zn-button class="clear-files-btn">Clear Files</zn-button>
<div class="programmatic-output"></div>

<script type="module">
  const fileInput = document.querySelector('.file-programmatic');
  const getFilesBtn = document.querySelector('.get-files-btn');
  const clearFilesBtn = document.querySelector('.clear-files-btn');
  const output = document.querySelector('.programmatic-output');

  await Promise.all([
    customElements.whenDefined('zn-button'),
    customElements.whenDefined('zn-file')
  ]).then(() => {
    getFilesBtn.addEventListener('click', () => {
      const files = fileInput.files;
      if (files && files.length > 0) {
        const fileNames = Array.from(files).map(f => f.name).join(', ');
        output.innerHTML = `<strong>Selected files:</strong> ${fileNames}`;
      } else {
        output.innerHTML = 'No files selected';
      }
    });

    clearFilesBtn.addEventListener('click', () => {
      fileInput.value = '';
      output.innerHTML = 'Files cleared';
    });
  });
</script>

Validation

The file control supports standard HTML5 form validation. Use the required attribute to make file selection mandatory.


Upload 
<form class="file-validation-form">
  <zn-file name="avatar" label="Profile Picture" accept="image/*" required></zn-file>
  <br />
  <zn-button type="submit" variant="primary">Upload</zn-button>
</form>

<script type="module">
  const form = document.querySelector('.file-validation-form');

  await Promise.all([
    customElements.whenDefined('zn-button'),
    customElements.whenDefined('zn-file')
  ]).then(() => {
    form.addEventListener('submit', (e) => {
      e.preventDefault();
      alert('File uploaded successfully!');
    });
  });
</script>

Custom Validation

You can set custom validation messages using the setCustomValidity() method.


Submit 
<form class="custom-validation-form">
  <zn-file class="custom-validation" name="document" label="Upload PDF (max 2MB)" accept=".pdf"></zn-file>
  <br />
  <zn-button type="submit" variant="primary">Submit</zn-button>
</form>
<div class="custom-validation-output"></div>

<script type="module">
  const form = document.querySelector('.custom-validation-form');
  const fileInput = document.querySelector('.custom-validation');
  const output = document.querySelector('.custom-validation-output');

  await Promise.all([
    customElements.whenDefined('zn-button'),
    customElements.whenDefined('zn-file')
  ]).then(() => {
    fileInput.addEventListener('zn-change', () => {
      const files = fileInput.files;
      if (files && files.length > 0) {
        const file = files[0];
        const maxSize = 2 * 1024 * 1024; // 2MB

        if (file.size > maxSize) {
          fileInput.setCustomValidity('File size must not exceed 2MB');
          output.innerHTML = `<span style="color: var(--zn-color-danger-600);">File too large: ${(file.size / 1024 / 1024).toFixed(2)} MB (max 2MB)</span>`;
        } else {
          fileInput.setCustomValidity('');
          output.innerHTML = `<span style="color: var(--zn-color-success-600);">File size: ${(file.size / 1024).toFixed(2)} KB - Valid!</span>`;
        }
      }
    });

    form.addEventListener('submit', (e) => {
      e.preventDefault();
      if (form.checkValidity()) {
        alert('Form submitted!');
      }
    });
  });
</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.4/dist/components/file/file.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.4/dist/components/file/file.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/file/file.js';

Slots

Name Description
label The file control’s label. Alternatively, you can use the label attribute.
help-text Text that describes how to use the file control. Alternatively, you can use the help-text attribute.
trigger Optional content to be used as trigger instead of the default content. Opening the file dialog on click and as well as drag and drop will work for this content. Following attributes will no longer work: label, droparea, help-text, size, hide-value. Also if using the disabled attribute, the disabled styling will not be applied and must be taken care of yourself.

Learn more about using slots.

Properties

Name Description Reflects Type Default
files The selected files as a FileList object containing a list of File objects. The FileList behaves like an array, so you can get the number of selected files via its length property. see MDN - -
name The name of the file control, submitted as a name/value pair with form data. string ''
value The value of the file control contains a string that represents the path of the selected file. If multiple files are selected, the value represents the first file in the list. If no file is selected, the value is an empty string. Beware that the only valid value when setting a file control is an empty string! see MDN - -
defaultValue The default value of the form control. Primarily used for resetting the form control. string ''
size The file control’s size. 'small' | 'medium' | 'large' 'medium'
label The file control’s label. If you need to display HTML, use the label slot instead. string ''
clearable If this is set, then the only way to remove files is to click the cross next to them. boolean false
helpText
help-text 		The file control’s help text. If you need to display HTML, use the help-text slot instead. string ''
disabled Disables the file control. boolean false
droparea Draw the file control as a drop area boolean false
accept Comma separated list of supported file types see MDN string ''
capture Specifies the types of files that the server accepts. Can be set either to user or environment. Works only when not using a droparea! see MDN 'user' | 'environment' -
multiple Indicates whether the user can select more than one file. Has no effect if webkitdirectory is set. see MDN boolean false
webkitdirectory Indicates that the file control should let the user select directories instead of files. When a directory is selected, the directory and its entire hierarchy of contents are included in the set of selected items. Note: This is a non-standard attribute but is supported in the major browsers. see MDN boolean false
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ''
required Makes the input a required field. boolean false
hideValue
hide-value 		Suppress the value from being displayed in the file control boolean false
src URL of an already-uploaded file (e.g., from a CDN) to display as the current value when no file has been selected locally. If the URL points to an image, it is rendered as a preview inside the droparea. Otherwise the URL is shown as a filename. string ''
triggerSubmit
trigger-submit 		When enabled, automatically submit the surrounding form whenever the value changes (file selected, dropped, or cleared). Useful for forms that only contain this control and a CSRF token. boolean false
showLink
show-link 		When enabled, render the current link (previewSrc) as a clickable URL below the control. Useful for showing the existing CDN link alongside the preview. boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
previewSrc Returns the URL currently shown in the droparea — the locally-selected file’s object URL if a file is selected, otherwise the externally supplied src. Useful for getting the current CDN link to submit alongside form data. string -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
zn-blur Emitted when the control loses focus. -
zn-change Emitted when an alteration to the control’s value is committed by the user. -
zn-clear Emitted when the user confirms clearing the selected file or src. -
zn-error Emitted when multiple files are selected via drag and drop, without the multiple property being set. -
zn-focus Emitted when the control gains focus. -
zn-input Emitted when the control receives input. -

Learn more about events.

Methods

Name Description Arguments
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
focus() Sets focus on the button or droparea. options: FocusOptions
blur() Removes focus from the button or droparea. -

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The input’s wrapper.
form-control-help-text The help text’s wrapper.
button-wrapper The wrapper around the button and text value.
button The zn-button acting as a file input.
button__base The zn-button’s exported base part.
value The chosen files or placeholder text for the file input.
droparea The element wrapping the drop zone.
droparea-background The background of the drop zone.
upload The upload button shown in the droparea when no file is selected.
preview The image preview rendered in the droparea for previewable files.
filename The filename label rendered in the droparea for non-previewable files.
clear The clear button rendered in the droparea when a file is present.
clear-confirm The confirmation dialog shown before clearing the file.
link The current link anchor rendered when show-link is enabled.
trigger The container that wraps the trigger.

Learn more about customizing CSS parts.

Animations

Name Description
file.iconDrop The animation to use for the file icon when a file is dropped
file.text.disappear The disappear animation to use for the file placeholder text when a file is dropped
file.text.appear The appear animation to use for the file placeholder text when a file is dropped

Learn more about customizing animations.

Dependencies

This component automatically imports the following dependencies.

  • <zn-button>
  • <zn-dialog>
  • <zn-example>
  • <zn-icon>
  • <zn-tooltip>