Input file

When to use

Reach for an input file whenever someone needs to attach one or more files to a form, such as a profile picture, a set of product photos, a signed PDF, or supporting documents for a claim. It shows files as thumbnails by default, better suited to images, or as a compact row list for anything else, such as PDFs, spreadsheets, or other attachments. For a single free-text value, reach for input instead, since this component is only for actual files. See Alternatives below for a direct comparison.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/input-file.js";

<eun-input-file name="photos" label="Photos" multiple></eun-input-file>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/input-file.js";
</script>

<eun-input-file name="photos" label="Photos" multiple></eun-input-file>

npm install @eunomia/elements

import "@eunomia/elements/input-file.js";

function PhotosField() {
  return <eun-input-file name="photos" label="Photos" multiple />;
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/input-file.js";

export function PhotosField() {
  return <eun-input-file name="photos" label="Photos" multiple />;
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/input-file.js";
</script>

<template>
  <eun-input-file name="photos" label="Photos" multiple />
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/input-file.js";

@Component({
  selector: "app-photos-field",
  template: `<eun-input-file name="photos" label="Photos" multiple>
  </eun-input-file>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class PhotosFieldComponent {}

Alternatives

Guidance

Live testing

Properties

Basic

Image kind (default)

<eun-input-file name="avatar" label="Avatar" hint="PNG or JPG"></eun-input-file>

File kind

<eun-input-file
  name="document"
  label="Document"
  kind="file"
  accept="application/pdf"
>
</eun-input-file>

Several files

Multiple

With multiple, the dropzone stays visible above the item list/grid so more files can keep being added.

<eun-input-file name="gallery" label="Gallery" multiple></eun-input-file>

Selectable, with bulk delete

selectable adds a checkbox to each item, plus a select-all checkbox and a "Delete selected" action once at least one is checked, independent from the always-available "Remove all".

<eun-input-file
  name="attachments"
  label="Attachments"
  kind="file"
  multiple
  selectable
>
</eun-input-file>

Restricting size and count

max-size (bytes) rejects oversized files, while max-files caps the total count once multiple is set. Both emit eunfilereject instead of silently dropping the file, so listen for it to surface why a file didn't make it in.

No rejections yet.

<eun-input-file
  name="receipts"
  label="Receipts"
  kind="file"
  multiple
  max-size="2000000"
  max-files="3"
  hint="Up to 3 files, 2 MB each"
>
</eun-input-file>

const field = document.querySelector("#receipts");

field.addEventListener("eunfilereject", (event) => {
  const summary = event.files
    .map(({ file, reason }) => `${file.name}: ${reason}`)
    .join("\n");
  console.log(summary);
});

States

Disabled

<eun-input-file label="Disabled" disabled></eun-input-file>

Readonly

A readonly field still shows and submits its files, but nothing can be added or removed.

<eun-input-file label="Readonly" readonly></eun-input-file>

Required

<eun-input-file
  label="Proof of address"
  kind="file"
  required
  hint="A recent utility bill or bank statement"
>
</eun-input-file>

Forms and stored files

Forms

Like every other Eunomia field, eun-input-file is a real form-associated custom element, so the selected File objects themselves are submitted under its name, exactly like a native <input type="file">.

[]

<form id="my-form">
  <eun-input-file name="attachments" label="Attachments" kind="file" multiple>
  </eun-input-file>
  <button type="submit">Submit</button>
  <button type="reset">Reset</button>
</form>

const form = document.querySelector("#my-form");

form.addEventListener("eunchange", () => {
  const files = new FormData(form).getAll("attachments");
  console.log(files.map((file) => file.name));
});

Stored files

To show a file that is already stored, put its URL in value next to, or instead of, File objects. It is displayed like any picked file, opens from that URL, and is submitted as that URL, so the server knows the file is kept. Its name is the last segment of the URL, unless you give it as { url, name }.

<eun-input-file id="logo" name="logo" label="Logo"></eun-input-file>

document.querySelector("#logo").value = [
  "https://cdn.example.com/logos/acme.png",
];
// or, with the name to display
document.querySelector("#logo").value = [
  { url: "https://cdn.example.com/logos/0c1d-acme.png", name: "acme.png" },
];

Filling its parent

The dropzone stretches to the height given to the field, set directly or by a flex or grid parent.

<div style="display: flex; flex-direction: column; height: 16rem">
  <eun-input-file label="Cover" style="flex: 1 1 auto"></eun-input-file>
</div>

Custom

Override the --input-file-* CSS variables, listed in full in the API tab.

<eun-input-file class="custom-input-file" label="Custom"></eun-input-file>

.custom-input-file {
  --input-file-border-color: #be185d;
  --input-file-border-color-hover: #be185d;
  --input-file-border-color-focus: #be185d;
  --input-file-focus-outline-color: #be185d;
}

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Keyboard interactions

Drag-and-drop is a pointer-only shortcut for the exact same selection the native picker already provides through the dropzone's Enter/Space, so nothing here is drag-and-drop-only.

Semantics and screen readers

Aria attributes

• aria-invalid="true"|"false" on the native file field: true while the error is shown, or while invalid is set
• aria-label on the native, visually-hidden file field: set from the label property directly, for the same cross-shadow-boundary reason documented on eun-input's own Accessibility tab (a plain-text aria-label instead of aria-labelledby/for pointing at the rendered <eun-label>)
• aria-describedby="description": set on the native field whenever a hint or error message is actually rendered below it
• aria-disabled on the dropzone: reflects both disabled and "max-files already reached"
• Each item is role="button" with an aria-label combining the file name and a short "Open in a new tab" hint (open-label), so its accessible name and its primary action always match
• Each item's remove button and (when selectable) checkbox carry their own aria-label including the file name, so multiple items' controls stay distinguishable to assistive technology
• The file count above the items ("3 files") is aria-live="polite", so additions and removals are announced without moving focus

Label accessibility

Always set label (or slot content into the label slot): describe what the files are for ("Proof of address", "Product photos"), not just that a file is expected.

Field states

Disabled vs. readonly

disabled removes the field from the tab order (tabindex="-1", aria-disabled="true"), disables every action, and excludes the value from form submission entirely. readonly keeps the field and its items focusable and their values submitted, but blocks adding, removing, or reordering, communicating "you can't change this right now", not "this doesn't apply". Prefer readonly over disabled whenever the already-selected files are still meaningful context for the user.

Required field

required behaves like a native required <input type="file">: an empty selection is invalid, any non-empty selection is valid, regardless of multiple.

Rejections aren't validation errors

Files rejected for type/size/max-files never reach value in the first place, so there's nothing invalid to report through checkValidity(). A native file picker behaves the same way, since you simply can't pick a mismatched file. Listen for eunfilereject if you want to surface why a specific file didn't make it in (see the Examples tab).

Reference links

WAI Web Accessibility Tutorials: Labeling Controls
WHATWG HTML: The file upload state of the input element