InputFile

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 profitiert dadurch von dessen Semantik, dem Dateiauswahldialog des Betriebssystems sowie der standardisierten Unterstützung durch Browser und assistive Technologien. Sie unterstützt die Auswahl einzelner oder mehrerer Dateien sowie die Einschränkung zulässiger Dateitypen.

Anstelle der browserspezifischen Darstellung des nativen Elements zeigt die Komponente eine einheitliche Schaltfläche „Datei auswählen“ sowie die Namen der ausgewählten Dateien an. Zusätzlich können Dateien per Drag & Drop auf dem Feld abgelegt werden.

Beispiel

Standard-Datei-Eingabefeld ohne optional gesetzte Felder:

<KolInputFile _label="Datei hochladen" />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung versehen werden. Es darf visuell ausgeblendet werden, wenn der Zweck des Eingabefeldes durch den direkten visuellen Kontext absolut unmissverständlich ist.

• Im Fehlerfall wird die Fehlermeldung direkt an der Komponente dargestellt und automatisch mit ihr verknüpft, sodass sie auch assistiven Technologien zur Verfügung steht.

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.
Einheitliche Darstellung statt browserspezifischem Dateifeld	Anstelle der browserspezifischen Darstellung zeigt die Komponente eine Schaltfläche „Datei auswählen“ und die Namen der gewählten Dateien an (siehe Dateiauswahl und Drag & Drop). Fokus, Tastaturbedienung und Screenreader-Ausgabe entsprechen dem nativen Dateifeld.
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

• Schränken Sie die zulässigen Dateitypen über _accept ein.
• Aktivieren Sie die Auswahl mehrerer Dateien über _multiple.
• Kennzeichnen Sie Pflichtfelder über _required.
• Setzen Sie eine getroffene Auswahl bei Bedarf über die Methode reset() zurück. Dabei werden die ausgewählten Dateien entfernt und der Hinweistext im Feld wiederhergestellt.

Tastatursteuerung

Die Tastaturbedienung wird durch den Browser und das Betriebssystem bestimmt. Daher können sich einzelne Tastaturfunktionen je nach Browser 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	Öffnet den nativen Dateiauswahldialog.

Die Bedienung innerhalb des Dateiauswahldialogs wird durch das Betriebssystem bestimmt.

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 und beim Ablegen per Drag & Drop nicht greift.
• 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 legen Sie fest, 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 auf dem Feld abgelegt werden. Diese Funktion ergänzt die Dateiauswahl, ersetzt sie jedoch nicht. Abgelegte Dateien werden nicht gegen _accept und _multiple geprüft.

Wie setze ich die Auswahl zurück?
Rufen Sie die Methode reset() der Komponente auf. Sie entfernt die ausgewählten Dateien und stellt den Hinweistext im Feld wieder her.

Playground

Testen Sie die verschiedenen Eigenschaften der InputFile-Komponente:

Icons

Message

<KolInputFile _label="Datei hochladen" />

Funktionalitäten

Einfaches Eingabefeld

Jedes Feld benötigt mindestens ein Label (_label), um für alle Nutzenden verständlich und zugänglich zu sein. Das Label wird als natives label-Element mit dem Feld verknüpft.

<KolInputFile _label="Dokument hochladen" />

Dateiauswahl und Drag & Drop

Die Komponente zeigt eine Schaltfläche „Datei auswählen“ an. Ein Klick an beliebiger Stelle des Feldes öffnet den Dateiauswahldialog des Betriebssystems; per Tastatur öffnen Enter bzw. Leertaste den Dialog, sobald das Feld fokussiert ist.

Die Namen der ausgewählten Dateien werden als Text im Feld angezeigt. Solange keine Datei ausgewählt ist, erscheint dort der Hinweis „Datei auswählen oder hier ablegen...“. Wählen Sie im Beispiel eine Datei aus, um die Anzeige zu sehen.

Zusätzlich können Dateien per Drag & Drop auf dem Feld abgelegt werden. Diese Komfortfunktion ergänzt die tastaturbedienbare Auswahl über den Dateiauswahldialog, ersetzt sie jedoch nicht.

Hinweis: Beim Ablegen per Drag & Drop werden _accept und _multiple derzeit nicht berücksichtigt – es werden alle abgelegten Dateien übernommen (siehe ). Prüfen Sie Anzahl, Typ und Größe der Dateien daher immer auf Anwendungsebene bzw. serverseitig.

<KolInputFile _label="Dokument hochladen" />

Formularattribute

Mit den folgenden Properties passen Sie das Feld an gängige Formularanforderungen an:

• _disabled: Deaktiviert das Feld. Deaktivierte Felder sind nicht fokussierbar und können nicht bearbeitet werden (mit Bedacht verwenden!).

• _required: Kennzeichnet das Feld als Pflichtfeld.

Die Properties werden 1:1 auf die gleichnamigen nativen HTML-Attribute des input-Elements übertragen. Mit _disabled wird zusätzlich die Schaltfläche „Datei auswählen“ deaktiviert.

<KolInputFile _label="Dokument hochladen" />

Dateitypbeschränkung

Mit _accept legen Sie fest, welche Dateitypen im Dateiauswahldialog angeboten werden. Der Wert wird auf das native accept-Attribut übertragen und kann Dateiendungen und MIME-Typen enthalten.

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)

Die Einschränkung zulässiger Dateitypen über _accept wird von Browsern und assistiven Technologien unterstützt.

Hinweis: Die Einschränkung wirkt nur im Dateiauswahldialog. Per Drag & Drop abgelegte Dateien werden derzeit nicht gegen _accept geprüft (siehe ).

<KolInputFile _accept="image/*" _label="Bild hochladen" />

Mehrfachauswahl

Mit _multiple ermöglichen Sie die Auswahl mehrerer Dateien in einem Arbeitsgang. Die Namen aller ausgewählten Dateien werden kommagetrennt im Feld angezeigt.

<KolInputFile _label="Anhänge hochladen" _multiple={true} />

Hinweistexte und Fehlermeldungen

Mit _hint und _msg geben Sie Nutzenden zusätzliche Orientierung zur Eingabe und machen Validierungsfehler unmittelbar am Feld sichtbar:

• _hint: Ergänzende Hinweise zur Eingabe (wird immer angezeigt und über aria-describedby mit dem Feld verknüpft)
• _msg: Fehlermeldungen oder Validierungshinweise (wird nur in Verbindung mit _touched angezeigt)
• _touched: Zeigt an, ob das Feld von Nutzenden bereits angefasst wurde, und steuert damit, ob _msg sichtbar wird
• _hideMsg: Unterdrückt die Fehlermeldung am Feld, wenn sie an anderer Stelle dargestellt wird

Hinweis: _msg wird erst dann eingeblendet, wenn _touched auf true gesetzt ist. So werden Validierungsfehler nicht bereits beim ersten Rendern, sondern erst nach einer Interaktion mit dem Feld angezeigt. Handelt es sich um eine Fehlermeldung, wird das Feld zusätzlich über aria-invalid als ungültig gekennzeichnet.

Anwendungsfall für _hideMsg: Besteht eine fachliche Einheit aus mehreren Eingabefeldern innerhalb eines Field-Sets, beispielsweise ein sechsstelliger Bestätigungscode mit einem einzelnen Feld je Stelle, kann eine gemeinsame Fehlermeldung für die gesamte Gruppe sinnvoller sein als eine Meldung je Einzelfeld. In diesem Fall unterdrücken Sie die Fehlermeldung an den einzelnen Feldern über _hideMsg und stellen sie stattdessen einmalig am Field-Set dar.

Wichtig: _hideMsg blendet die Fehlermeldung nicht nur visuell aus. Die Meldung wird weder gerendert noch über aria-describedby mit dem Feld verknüpft – lediglich die Kennzeichnung über aria-invalid bleibt erhalten. Stellen Sie daher sicher, dass die gemeinsame Fehlermeldung auf Anwendungsebene für alle Nutzenden, auch für Nutzende assistiver Technologien, wahrnehmbar ist.

Message

<KolInputFile _hideMsg={false} _hint="Akzeptierte Formate: PDF, DOC, DOCX. Maximale Größe: 10 MB." _label="Dokument hochladen" _msg={{ "_description": "Bitte laden Sie eine PDF-Datei mit maximal 10 MB hoch." }} _touched={true} />

Label ausblenden

Mit _hideLabel blenden Sie das Label visuell aus, um das Feld kompakter zu gestalten. Für assistive Technologien bleibt die Beschriftung als zugänglicher Name (aria-label) weiterhin verfügbar; sehende Nutzende erhalten sie bei Maus-Hover und Tastaturfokus als Tooltip.

<KolInputFile _hideLabel={false} _label="Dokument hochladen" />

Icons

Mit _icons versehen Sie das Feld links und/oder rechts mit zusätzlichen Icons, um visuellen Kontext zu geben.

Verfügbare Positionen sind:

• left: Icon links vom Feld
• right: Icon rechts vom Feld

Wird ein Icon nur über seine Icon-Klasse angegeben, gilt es als dekorativ und wird vor assistiven Technologien verborgen. Trägt ein Icon eine Information, die nicht bereits aus Label oder Hinweis hervorgeht, übergeben Sie es als Objekt mit label – das Icon erhält dann eine zugängliche Beschriftung.

Icons

<KolInputFile _icons={{ "left": "kolicon-kolibri" }} _label="Dokument hochladen" />

SmartButton

Mit _smartButton platzieren Sie einen Button mit beliebiger Aktion direkt im Eingabefeld, etwa um eine zugehörige Funktion griffbereit anzubieten. Der SmartButton wird immer als Icon-Button ohne sichtbare Beschriftung dargestellt; sein _label dient als zugänglicher Name und muss die Aktion daher eindeutig beschreiben. Der SmartButton ist per Tastatur erreichbar und wird zusammen mit dem Feld deaktiviert (_disabled).

<KolInputFile _label="Mit SmartButton" _smartButton={{ "_label": "Action" }} />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Eingabefeld wird angeklickt	-
focus	Eingabefeld wird fokussiert	-
blur	Eingabefeld verliert Fokus	-
keydown	Taste wird im Eingabefeld gedrückt	-
input	Dateien werden über den Dialog ausgewählt oder per Drag & Drop abgelegt	Ausgewählte Dateien als FileList
change	Dateien werden über den Dialog ausgewählt oder per Drag & Drop abgelegt	Ausgewählte Dateien als FileList

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
_ariaDetails	_aria-details	References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS).	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.	string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; }	undefined
_infoPopover	_info-popover	Defines the informational popover after the label.	any	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; } & { _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _accessKey?: string | undefined; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _type?: "button" | "reset" | "submit" | undefined; _variant?: VariantClassNamePropType | 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; }	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 | string[] | undefined	undefined

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

focus(options?: KolFocusOptions) => Promise<void>

Sets focus on the internal element.

Parameters

Name	Type	Description
options	KolFocusOptions | undefined

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.

---