InputFile

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

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Synonyme: Upload, File Uploader, File Picker, Dateiauswahl

Beschreibung: Die InputFile-Komponente erzeugt ein Eingabefeld für Datei-Uploads. Sie ermöglicht Nutzern, eine oder mehrere Dateien auszuwählen und einzureichen – ideal für Formular-basierte Dateiübergaben, Dokumentationen oder Medien-Uploads.

Beispiel

Einfaches Datei-Eingabefeld mit Beschriftung und Konfigurationsmöglichkeiten:

<KolInputFile _label="Datei hochladen" />

Barrierefreiheit

Die InputFile-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt:

• Label-Pflicht: Jedes Eingabefeld muss über das Attribut _label eine aussagekräftige Beschriftung erhalten, die von Screenreadern erkannt wird.
• Dateitypbeschränkung: Die Attribute _accept und _multiple werden korrekt an die zugrundeliegende HTML5-API übermittelt und von assistiven Technologien erkannt.
• Fehlerbehandlung: Mit dem Attribut _msg können Fehlermeldungen angegeben werden, die von Screenreadern vorgelesen werden.
• Tastatursteuerung: Die Komponente ist vollständig über die Tastatur bedienbar. Tab fokussiert das Eingabefeld und öffnet den vordefinierten Dateiauswahldialog des Betriebssystems.
• Fokusmanagement: Klare visuelle Fokusindikatoren für Nutzer mit Sehbehinderungen.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Fokussiert das Eingabefeld und öffnet den Dateiauswahldialog.

Best Practices / Empfehlungen

• Dateitypbeschränkung: Verwenden Sie das Attribut _accept, um nur die erforderlichen Dateitypen zuzulassen. Dies verhindert unnötige Upload-Versuche und verbessert die User Experience. Beachten Sie die MIME-Type-Syntax: z.B. image/* für alle Bilder, .pdf für PDF-Dateien oder .doc,.docx für Microsoft Word.
• Sicherheit: Das Attribut _accept ist lediglich eine Benutzerfreundlichkeits-Funktion. Validieren Sie Dateitypen zwingend auf dem Server, da die Client-seitige Filterung umgangen werden kann.
• Größenbegrenzung: Begrenzen Sie die maximale Dateigröße auf dem Server, um Speicher- und Upload-Kapazität zu schützen. Dies muss auf dem Server erfolgt, nicht im Client.
• Mehrfachauswahl: Nutzen Sie _multiple, wenn Nutzer mehrere Dateien gleichzeitig hochladen sollen.
• ID und Name: Setzen Sie _name korrekt, damit die Dateien beim Formular-Submit mitgesendet werden.
• Aussagekräftige Label: Verwenden Sie beschreibende Labels, die den Zweck des Uploads deutlich machen, z.B. „Beilagedokumente" statt nur „Datei".
• Fehlerbehandlung: Geben Sie bei ungültigen Dateien konkrete Fehlermeldungen über _msg aus – nicht nur „Fehler", sondern z.B. „Nur PDF-Dateien erlaubt" oder „Maximale Größe: 5 MB".

Anwendungsfälle

• Hochladen von Profilbildern oder Avataren
• Einreichung von Bewerbungsdokumenten oder Lebensläufen
• Upload von Anhängen in Kontaktformularen
• Batch-Import von Daten (z.B. CSV, Excel)
• Einreichen von Szenarien-Dateien oder Konfigurationen
• Bildergalerie oder Dateimanagement-Interfaces

Konstruktion / Technik

Playground

Testen Sie die verschiedenen Eigenschaften der InputFile-Komponente:

Icons

Message

<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" | "_variant" | "_hasCloser" | "_label" | "_level"> & { _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; } & { _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _type?: "button" | "reset" | "submit" | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _accessKey?: string | undefined; _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

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.

---