HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
File InputView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA field for choosing files from a picker or by dropping them on it.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/file-input'import'@fusion.dev/helix-headless/file-input'Preview
API ReferenceRoothelix-file-inputA field for choosing files from a picker or by dropping them on it.
PropTypeDescriptionacceptstringDefault""Which files the picker offers and a drop takes, as a native accept list.addedTextstringDefault"Added: {names}"What a reader hears when a drop or a paste adds files, with {names} and
{count} filled in.bytesLabelstringDefault"{count, plural, one {# byte} other {# bytes}}"A file's size under a kilobyte. {count} is how many bytes, written in
the locale, and each language writes the forms it has.capture"environment"|"user"Which camera or microphone a mobile picker should offer, if any.directorybooleanDefaultfalseWhether the picker chooses a folder, and the field takes every file in
it. The platform's webkitdirectory.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.localestringDefault""The locale the words, the sizes, and the numbers and lists in sentences
are in, as a BCP 47 tag such as pl. Empty reads the nearest lang, then
the browser's language.maxFilesnumberThe most files the field holds, under multiple. Files past it are
refused.maxFileSizenumberThe most bytes one file may have. A larger one is refused.multiplebooleanDefaultfalseWhether more than one file can be chosen.namestringDefault""The name the control's value is submitted under.progressLabelstringDefault"Uploading {name}"The name of a file's progress bar, read by screen readers, with {name}
filled in. A label with no {name} has it added after it.rejectedTextstringDefault"Not added: {names}"What a reader hears when files are refused, with {count} and {names}
filled in.removedTextstringDefault"Removed: {name}"What a reader hears when a file is removed, with {name} filled in.removeLabelstringDefault"Remove {name}"The accessible name of the control that removes a file. {name} is
replaced with the file's name.renderFile(file: File, index: number) => unknownDraws a file's row in place of its name, size, and type: a Lit template, a
string, or a DOM node, given the file and its place in the list. The
remove button stays beside it.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.transformFiles(files: File[]) => File[] | Promise<File[]>Your own step between taking files and holding them, such as shrinking an
image, as Zag's file upload transformFiles. It is given the files taken
from one pick, drop, or paste and returns the files to hold, or a promise
of them. A promise that rejects refuses those files, with its message.triggerLabelstringDefault"Choose files"The trigger's text when nothing is slotted into it.validate(file: File) => string | nullYour own check on each arriving file, which returns why it is refused, or
nothing to take it. A property, since a function cannot be an attribute.valueMissingMessagestringThe message shown when the field is required and empty.
ReadTypeDescriptionfilesFile[]The chosen files. It is read-only.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionfeedbackThe message that says what is wrong with the chosen files.hintHelp under the field.labelThe label, for content richer than the label text.remove-iconThe icon on each file's remove button, in place of the bin. Each button shows a copy.triggerThe content that opens the picker when pressed.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the chosen files change, with their names, and cancelable. Canceling it keeps the files the field had, even when the browser has already written a new pick.helix-rejectHelixRejectEventFired when files arrive and some are left out. detail.files lists each with its reason: type, size, count or invalid, and your validate message.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.clear() => voidRemoves every chosen file.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.removeAt(at: number) => voidRemoves one file, by its index.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.setFileStatus(file: File, status: FileStatus | null) => voidShows how a file's upload is going, in its row: a bar for progress,
from 0 to 1, or a bar without a measure while state is uploading, and
text beside it. state names the row file-uploading, file-done or
file-error beside file, and a reader hears text when the state
becomes done or error. null clears it.
PartDescriptioncontrolThe file input itself, which carries the label and validity.detailA file's name, with its size and type below it.feedbackThe message that says what is wrong.fieldThe box you press or drop files on.fileOne chosen file.file-doneA file whose upload setFileStatus says is done. Set together with file.file-errorA file whose upload setFileStatus says failed. Set together with file.file-uploadingA file whose upload setFileStatus says is under way. Set together with file.hintHelp under the field, while nothing is wrong.kindA file's type.kind-cellThe grid cell around the tag, rendered only when the tag sits in a Tag.Group.kind-dismissThe remove button, when dismissible.kind-dismiss-markThe glyph on the dismiss control, where none is slotted.kind-labelThe label, trimmed to its capitals and baseline.kind-linkThe link around the label, when the tag has an href.kind-startThe category before the label.labelThe label above the field.listThe chosen files.liveThe live region that says added-text, rejected-text, and removed-text. It is rendered from the first time it has something to say. Visually hidden in the styled tier.metaThe row that holds a file's size and type.nameA file's name.progressA file's upload bar, a <progress>, while setFileStatus gives it a measure or says it is under way.removeThe control that removes a file.sizeA file's size.size-cellThe grid cell around the tag, rendered only when the tag sits in a Tag.Group.size-dismissThe remove button, when dismissible.size-dismiss-markThe glyph on the dismiss control, where none is slotted.size-labelThe label, trimmed to its capitals and baseline.size-linkThe link around the label, when the tag has an href.size-startThe category before the label.statusHow a file's upload is going, from setFileStatus: the bar and the words.status-textThe words setFileStatus gives a file, such as the reason it failed.triggerThe label that opens the picker.
CSS PropertyDescription--file-input-background-colorFill behind the field.--file-input-border-colorThe field's dashed edge at rest.--file-input-drop-background-colorFill behind the field while files are dragged over it.--file-input-drop-border-colorThe field's edge while files are dragged over it.--file-input-file-background-colorFill behind each chosen file.--file-input-file-border-colorThe edge of each chosen file.--file-input-file-padding-blockPadding above and below each chosen file.--file-input-file-padding-inlinePadding at each side of each chosen file.--file-input-file-radiusCorner radius of each chosen file.--file-input-paddingPadding inside the field.--file-input-progress-colorThe filled part of a file's upload bar.--file-input-progress-track-colorThe unfilled part of a file's upload bar.--file-input-radiusCorner radius of the field.--file-input-remove-colorThe remove button's icon at rest.--file-input-remove-color-hoverThe remove button's icon under the pointer.--file-input-status-colorThe words beside a file's upload bar.--file-input-status-color-errorThe words beside a file whose upload failed.
Custom stateDescriptiondroppingFiles are being dragged over the field.has-filesThe field holds at least one file.invalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-file-inputA field for choosing files from a picker or by dropping them on it.
PropTypeDescriptionacceptstringDefault""Which files the picker offers and a drop takes, as a native accept list.addedTextstringDefault"Added: {names}"What a reader hears when a drop or a paste adds files, with {names} and
{count} filled in.bytesLabelstringDefault"{count, plural, one {# byte} other {# bytes}}"A file's size under a kilobyte. {count} is how many bytes, written in
the locale, and each language writes the forms it has.capture"environment"|"user"Which camera or microphone a mobile picker should offer, if any.directorybooleanDefaultfalseWhether the picker chooses a folder, and the field takes every file in
it. The platform's webkitdirectory.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.localestringDefault""The locale the words, the sizes, and the numbers and lists in sentences
are in, as a BCP 47 tag such as pl. Empty reads the nearest lang, then
the browser's language.maxFilesnumberThe most files the field holds, under multiple. Files past it are
refused.maxFileSizenumberThe most bytes one file may have. A larger one is refused.multiplebooleanDefaultfalseWhether more than one file can be chosen.namestringDefault""The name the control's value is submitted under.progressLabelstringDefault"Uploading {name}"The name of a file's progress bar, read by screen readers, with {name}
filled in. A label with no {name} has it added after it.rejectedTextstringDefault"Not added: {names}"What a reader hears when files are refused, with {count} and {names}
filled in.removedTextstringDefault"Removed: {name}"What a reader hears when a file is removed, with {name} filled in.removeLabelstringDefault"Remove {name}"The accessible name of the control that removes a file. {name} is
replaced with the file's name.renderFile(file: File, index: number) => unknownDraws a file's row in place of its name, size, and type: a Lit template, a
string, or a DOM node, given the file and its place in the list. The
remove button stays beside it.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.transformFiles(files: File[]) => File[] | Promise<File[]>Your own step between taking files and holding them, such as shrinking an
image, as Zag's file upload transformFiles. It is given the files taken
from one pick, drop, or paste and returns the files to hold, or a promise
of them. A promise that rejects refuses those files, with its message.triggerLabelstringDefault"Choose files"The trigger's text when nothing is slotted into it.validate(file: File) => string | nullYour own check on each arriving file, which returns why it is refused, or
nothing to take it. A property, since a function cannot be an attribute.valueMissingMessagestringThe message shown when the field is required and empty.
ReadTypeDescriptionfilesFile[]The chosen files. It is read-only.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionfeedbackThe message that says what is wrong with the chosen files.hintHelp under the field.labelThe label, for content richer than the label text.remove-iconThe icon on each file's remove button, in place of the bin. Each button shows a copy.triggerThe content that opens the picker when pressed.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the chosen files change, with their names, and cancelable. Canceling it keeps the files the field had, even when the browser has already written a new pick.helix-rejectHelixRejectEventFired when files arrive and some are left out. detail.files lists each with its reason: type, size, count or invalid, and your validate message.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.clear() => voidRemoves every chosen file.focus(options: FocusOptions) => voidMoves focus to the native file input, as a label pointing at it would.removeAt(at: number) => voidRemoves one file, by its index.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.setFileStatus(file: File, status: FileStatus | null) => voidShows how a file's upload is going, in its row: a bar for progress,
from 0 to 1, or a bar without a measure while state is uploading, and
text beside it. state names the row file-uploading, file-done or
file-error beside file, and a reader hears text when the state
becomes done or error. null clears it.
PartDescriptioncontrolThe file input itself, which carries the label and validity.detailA file's name, with its size and type below it.feedbackThe message that says what is wrong.fieldThe box you press or drop files on.fileOne chosen file.file-doneA file whose upload setFileStatus says is done. Set together with file.file-errorA file whose upload setFileStatus says failed. Set together with file.file-uploadingA file whose upload setFileStatus says is under way. Set together with file.hintHelp under the field, while nothing is wrong.kindA file's type.kind-cellThe grid cell around the tag, rendered only when the tag sits in a Tag.Group.kind-dismissThe remove button, when dismissible.kind-dismiss-markThe glyph on the dismiss control, where none is slotted.kind-labelThe label, trimmed to its capitals and baseline.kind-linkThe link around the label, when the tag has an href.kind-startThe category before the label.labelThe label above the field.listThe chosen files.liveThe live region that says added-text, rejected-text, and removed-text. It is rendered from the first time it has something to say. Visually hidden in the styled tier.metaThe row that holds a file's size and type.nameA file's name.progressA file's upload bar, a <progress>, while setFileStatus gives it a measure or says it is under way.removeThe control that removes a file.sizeA file's size.size-cellThe grid cell around the tag, rendered only when the tag sits in a Tag.Group.size-dismissThe remove button, when dismissible.size-dismiss-markThe glyph on the dismiss control, where none is slotted.size-labelThe label, trimmed to its capitals and baseline.size-linkThe link around the label, when the tag has an href.size-startThe category before the label.statusHow a file's upload is going, from setFileStatus: the bar and the words.status-textThe words setFileStatus gives a file, such as the reason it failed.triggerThe label that opens the picker.
Custom stateDescriptiondroppingFiles are being dragged over the field.has-filesThe field holds at least one file.invalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionDisabledA disabled file input, which does not accept a drop or a click.EventsA drop and a click send the same events, and the value is the file names.From A CameraA file input that opens the camera on a phone, set with capture.InvalidA required file input with no file chosen, and its error message.PreviewA drop zone that also opens a picker on a click, and accepts several files.PreviewA drop zone that also opens a picker on a click, and accepts several files.SingleOne image file, as for an avatar upload.