InputFile

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Synonyme: Datei-Eingabefeld, Dateiauswahl, Datei-Upload, File Input, File Upload

Beschreibung: Mit InputFile können Dateien ausgewählt und zur weiteren Verarbeitung bereitgestellt werden.

Die Komponente basiert auf dem nativen HTML5-Eingabetyp file und unterstützt die Auswahl einzelner oder mehrerer Dateien sowie die Einschränkung zulässiger Dateitypen.

Beispiel

Einfaches Datei-Eingabefeld mit Beschriftung und Konfigurationsmöglichkeiten:

<KolInputFile _label="Datei hochladen" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (_label) versehen werden.
• Zusätzliche Hinweise können über _hint, Fehlermeldungen über _msg bereitgestellt werden.
• Die Dateiauswahl ist vollständig über die Tastatur möglich. Tab fokussiert das Eingabefeld, Enter oder Leertaste öffnen anschließend den nativen Dateiauswahldialog des Betriebssystems.
• Dateien können zusätzlich per Drag & Drop ausgewählt werden. Diese Interaktion ist eine optionale Komfortfunktion und ersetzt nicht die vollständig tastaturbedienbare Dateiauswahl.
• Die Einschränkung zulässiger Dateitypen über _accept wird von Browsern und assistiven Technologien unterstützt.
• Mit _multiple können mehrere Dateien gleichzeitig ausgewählt werden.

Konkrete Designentscheidungen

Entscheidung	Begründung
Verwendung des nativen HTML5-Eingabetyps file	Die Komponente nutzt bewusst den nativen HTML5-Eingabetyp file und profitiert dadurch von dessen standardisierter Unterstützung durch Browser, Betriebssystem-Dateidialoge und assistive Technologien.
Fokusmanagement	Die Basis-Komponente setzt den nativen Fokusring des überlagerten Eingabefelds zurück. Der sichtbare Fokusindikator wird stattdessen für das gesamte Eingabefeld durch das jeweils verwendete Theme bereitgestellt.
Drag & Drop als Zusatzinteraktion	Die Auswahl per Drag & Drop ergänzt die Auswahl über den Dateiauswahldialog, ersetzt diese jedoch nicht. Dadurch bleibt die vollständige Bedienbarkeit über Tastatur und Betriebssystem-Dateidialog erhalten.

Links und Referenzen

Verwendung

• Die Einschränkung zulässiger Dateitypen kann über _accept konfiguriert werden.
• Die Auswahl mehrerer Dateien kann über _multiple aktiviert werden.
• Pflichtfelder werden über _required gekennzeichnet.

Hinweis: Neben der Auswahl über Tastatur und Dateiauswahldialog unterstützt das Eingabefeld auch das Ablegen von Dateien per Drag & Drop. Diese Interaktion ist eine zusätzliche Komfortfunktion und ersetzt nicht die vollständig tastaturbedienbare Dateiauswahl.

Tastatursteuerung

Die Tastaturbedienung wird durch den Browser, das Betriebssystem und den nativen Dateiauswahldialog bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser, Betriebssystem und Endgerät unterscheiden.

Typischerweise werden folgende Funktionen unterstützt:

Taste	Funktion
Tab	Fokus auf das Eingabefeld bzw. das nächste fokussierbare Element setzen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Enter / Leertaste	Öffnen des nativen Dateiauswahldialogs.

Best Practices / Empfehlungen

• Nutzen Sie _accept, um die Dateiauswahl auf die für den Anwendungsfall zulässigen Dateitypen einzuschränken und die Benutzerführung zu verbessern.
• Verlassen Sie sich nicht ausschließlich auf _accept. Prüfen Sie Dateitypen und Dateigrößen zusätzlich serverseitig, da die clientseitige Einschränkung umgangen werden kann.
• Verwenden Sie _multiple nur, wenn die Auswahl mehrerer Dateien für den Anwendungsfall erforderlich ist.
• Formulieren Sie aussagekräftige Beschriftungen (_label), die den Zweck des Datei-Uploads eindeutig beschreiben.
• Nutzen Sie _hint, um zulässige Dateiformate oder maximale Dateigrößen verständlich zu kommunizieren.
• Geben Sie Validierungsfehler über _msg aus und beschreiben Sie verständlich, wie Nutzende den Fehler beheben können.

Anwendungsfälle

• Hochladen von Profilbildern oder Avataren
• Bereitstellen von Anhängen in Formularen, beispielsweise Bewerbungsunterlagen oder Nachweisen
• Upload von Dokumenten zur Identifikation oder Verifizierung
• Hochladen mehrerer Dateien, beispielsweise Bilder oder Dokumentensammlungen
• Bereitstellen von Dateien für Import- oder Verarbeitungsprozesse

FAQ

Kann ich die Auswahl auf bestimmte Dateitypen beschränken?
Ja. Über _accept können Sie festlegen, welche Dateitypen im Dateiauswahldialog angeboten werden. Diese Einschränkung dient der Benutzerführung und ersetzt keine serverseitige Validierung.

Wie kann ich mehrere Dateien auswählen?
Aktivieren Sie _multiple, damit mehrere Dateien in einem Arbeitsgang ausgewählt werden können.

Kann ich die maximale Dateigröße begrenzen?
Nein. Die maximale Dateigröße kann nicht über die Komponente begrenzt werden und muss durch die Anwendung bzw. serverseitig geprüft werden.

Unterstützt die Komponente Drag & Drop?
Ja. Dateien können zusätzlich zum nativen Dateiauswahldialog per Drag & Drop ausgewählt werden. Diese Funktion ergänzt die Dateiauswahl, ersetzt sie jedoch nicht.

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften der InputFile-Komponente:

<KolInputFile _label="Datei hochladen" />

Funktionalitäten (mit Code)

Basisfeld mit Beschriftung

Standard-Datei-Eingabefeld ohne Konfiguration:

<KolInputFile _label="Datei auswählen" />

Dateitypbeschränkung

Beschränkung der erlaubten Dateitypen über das Attribut _accept:

<KolInputFile _accept="image/*" _label="Datei auswählen" />

Beispiele für _accept-Werte:

• image/* – Alle Bildformate
• .pdf – Nur PDF-Dateien
• .doc,.docx – Microsoft Word-Dokumente
• .csv,.xlsx – Tabellendaten
• * oder leer – Alle Dateitypen (Standard)

Mehrfachauswahl

Ermöglichen Sie die Auswahl mehrerer Dateien gleichzeitig:

<KolInputFile _label="Mehrere Dateien auswählen" _multiple={true} />

Deaktivierter Zustand

Das Eingabefeld ist nicht interaktiv:

<KolInputFile _disabled={true} _label="Datei auswählen" />

Fehlermeldung

Fehler oder Validierungshinweise:

Message

<KolInputFile _label="Datei auswählen" _msg={{ "_description": "Nur PDF-Dateien bis 5 MB erlaubt" }} />

Hilfetexte und Beschriftung

Additionale Informationen für Nutzer:

<KolInputFile _hint="Akzeptierte Formate: PDF, DOC, DOCX. Max. Größe: 10 MB." _label="Dokument hochladen" />

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
focus	Eingabefeld wird fokussiert	-
click	Eingabefeld wird angeklickt	-
keydown	Eine Taste wird gedrückt, während das Eingabefeld fokussiert ist	-
input	Eine oder mehrere Dateien werden ausgewählt (natives input-Event)	Ausgewählte Dateien als FileList
change	Eine oder mehrere Dateien werden ausgewählt (natives change-Event)	Ausgewählte Dateien als FileList
blur	Eingabefeld verliert Fokus	-

API

Overview

The File input type creates an input field for file uploads. One or multiple files can be selected and submitted with a form.

Properties

Property	Attribute	Description	Type	Default
_accept	_accept	Defines which file formats are accepted.	string | undefined	undefined
_accessKey	_access-key	Defines the key combination that can be used to trigger or focus the component's interactive element.	string | undefined	undefined
_disabled	_disabled	Makes the element not focusable and ignore all events.	boolean | undefined	false
_hideLabel	_hide-label	Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it.	boolean | undefined	false
_hideMsg	_hide-msg	Hides the error message but leaves it in the DOM for the input's aria-describedby.	boolean | undefined	false
_hint	_hint	Defines the hint text.	string | undefined	''
_icons	_icons	Defines the icon classnames (e.g. _icons="fa-solid fa-user").	string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; }	undefined
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot.	string	undefined
_msg	_msg	Defines the properties for a message rendered as Alert component.	Omit<AlertProps, "_on" | "_label" | "_level" | "_variant" | "_hasCloser"> & { _description: string; } | string | undefined	undefined
_multiple	_multiple	Makes the input accept multiple inputs.	boolean | undefined	false
_name	_name	Defines the technical name of an input field.	string | undefined	undefined
_on	--	Gibt die EventCallback-Funktionen für das Input-Event an.	InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown | undefined	undefined
_required	_required	Makes the input element required.	boolean | undefined	false
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_smartButton	_smart-button	Allows to add a button with an arbitrary action within the element (_hide-label only).	string | undefined | { _label: string; } & { _type?: "button" | "reset" | "submit" | undefined; _accessKey?: string | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _customClass?: string | undefined; _disabled?: boolean | undefined; _hideLabel?: boolean | undefined; _icons?: IconsPropType | undefined; _id?: string | undefined; _inline?: boolean | undefined; _name?: string | undefined; _shortKey?: string | undefined; _syncValueBySelector?: string | undefined; _tooltipAlign?: AlignPropType | undefined; _variant?: string | undefined; }	undefined
_tooltipAlign	_tooltip-align	Defines where to show the Tooltip preferably: top, right, bottom or left.	"bottom" | "left" | "right" | "top" | undefined	'top'
_touched	_touched	Shows if the input was touched by a user.	boolean | undefined	false
_variant	_variant	Defines which variant should be used for presentation.	string | undefined	undefined

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

focus() => Promise<void>

Sets focus on the internal element.

Returns

Type: Promise<void>

getValue() => Promise<FileList | null | undefined>

Returns the current value.

Returns

Type: Promise<FileList | null | undefined>

reset() => Promise<void>

Resets the component's value.

Returns

Type: Promise<void>

Slots

Slot	Description
	The label of the input field.

---