Skip to content
Kimenpre-v1documentation home
Color scheme

ki-file-upload

Use ki-file-upload for attachments, data imports or media. Give the field a label and explain the file limits where people choose their files. The Browse button opens the native file picker with a keyboard, pointer or touch.

Theme for this example
Color scheme for this example
<ki-file-upload
label="Incident attachments"
name="attachments"
accept=".csv,.pdf"
max-size="10MB"
max-files="3"
help-text="Choose up to three CSV or PDF files, up to 10 MB each."
multiple
></ki-file-upload>

accept accepts extensions, MIME types and MIME wildcards. Give max-size as bytes or use decimal units such as 10MB. Set multiple to allow more than one file and max-files to cap the selection. Rejected files stay in the list with a reason. Use the help slot to provide the guidance as markup.

Send the files

For a standard form submission, give the field a name and use enctype="multipart/form-data" on the form. Each accepted original File contributes an entry with that name. Read all entries in JavaScript with new FormData(form).getAll('attachments'). Mark the field required to make an accepted file necessary before submission.

For application-managed transfers, start work from ki-files-add, which reports the newly accepted rows. Update the files property with a new array and keep each row’s original file when changing its status or progress. Uploading rows show determinate progress when you provide a percentage.

Handle ki-file-cancel to stop an in-progress transfer and update the row. ki-file-remove identifies the row after the field removes it. Completion and failures are announced politely with the associated filenames. When translating row action and progress labels, keep the {file} placeholder so the label identifies the affected file.

API reference

When to use: collect local attachments, media or imports, and optionally show application-managed upload progress and results.

When not to use: transfer files without an application handler, collect a URL, or use client-side type and size checks as upload authorization.

Properties & attributes

AttributePropertyTypeDefaultDescription
acceptacceptstring | undefined–Comma-separated extensions, MIME types and MIME wildcards allowed in new selections.
browse-labelbrowseLabelstring'Browse files'Visible text of the native file picker button.
cancel-labelcancelLabelstring'Cancel upload of {file}'Accessible name template for cancellation. Use {file} for the displayed filename.
count-errorcountErrorstring'Too many files.'Rejection text for a file beyond selection capacity.
disableddisabledbooleanfalseDisables the picker and file actions and excludes the field from submission.
done-labeldoneLabelstring'Uploaded'Status text for a completed upload.
drop-labeldropLabelstring'Drop files here or'Drop instruction shown just before the Browse button.
error-texterrorTextstring | undefined–Application validation error. Clear it to allow form submission again.
failed-labelfailedLabelstring'Upload failed.'Fallback status text for a failed upload without a supplied error.
help-texthelpTextstring | undefined–Guidance for file formats, limits or the purpose of this field.
labellabelstring'Upload files'Visible label and accessible name of the upload group.
list-labellistLabelstring'Files'Accessible name of the list of files.
max-filesmaxFilesnumber | undefined–Maximum accepted local files as a nonnegative integer. Single-file mode also caps this at one.
max-sizemaxSizestring | undefined–Maximum size per selected file in bytes or decimal B, KB, MB or GB, such as "10MB".
multiplemultiplebooleanfalseAllows a selection of more than one file.
namenamestring | undefined–Form-data key repeated for each accepted original file.
queued-labelqueuedLabelstring'Queued'Status text for an accepted file waiting to upload.
remove-labelremoveLabelstring'Remove {file}'Accessible name template for removal. Use {file} for the displayed filename.
requiredrequiredbooleanfalseRequires at least one original accepted file to submit the form.
required-labelrequiredLabelstring'Required'Visible annotation for a required file field.
required-messagerequiredMessagestring'Select a file.'Validation message when the form requires a file and none is selected.
size-errorsizeErrorstring'This file is too large.'Rejection text for a file larger than max-size.
type-errortypeErrorstring'This file type is not allowed.'Rejection text for a file that does not match accept.
uploading-labeluploadingLabelstring'Uploading {file}'Progress indicator name template. Use {file} for the displayed filename.

Events

EventDetail typeDescription
ki-file-cancelCustomEvent<KiFileActionDetail>Requests that the application cancel the identified upload.
ki-file-removeCustomEvent<KiFileActionDetail>Reports a row removed by the user, after updating the file list.
ki-files-addCustomEvent<KiFilesAddDetail>Reports the accepted rows in one picker or drop batch, each with its original File.

Slots

SlotDescription
helpPlain-language guidance for the picker, in place of help-text.

CSS parts

PartDescription
actionNative button for removal or cancellation.
browseNative button that opens the file picker.
drop-zoneSurface that receives files dragged from the operating system.
errorField-level form validation error.
file-metaSize, outcome or error text for the file.
file-nameName displayed for the file.
helpGuidance associated with the field.
inputHidden native file picker.
labelField label and optional required annotation.
listList of selected files and rejections.
progressProgress indicator for an uploading file.
rowA file row, with data-status matching its lifecycle state.

CSS custom properties

The public styling contract of ki-file-upload: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-corner-inlineSmall radius for an outline around inline content.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-file-upload-active-bgDrop zone background while files are dragged over it.
--ki-file-upload-active-borderDrop zone boundary while files are dragged over it.
--ki-file-upload-active-fgMain drop zone text while files are dragged over it.
--ki-file-upload-backdrop-filterComplete backdrop filter applied behind the drop zone.
--ki-file-upload-bgDrop zone background at rest.
--ki-file-upload-bg-imageOptional image over the drop zone background.
--ki-file-upload-borderDashed boundary of the drop zone.
--ki-file-upload-border-widthOutline stroke width for the drop zone and file rows.
--ki-file-upload-error-bgBackground of a file row with an error.
--ki-file-upload-error-borderBoundary of a file row with an error.
--ki-file-upload-error-fgText of a file error or field error.
--ki-file-upload-fgMain drop zone text at rest.
--ki-file-upload-radiusDrop zone corner radius.
--ki-file-upload-row-backdrop-filterComplete backdrop filter applied behind a file row.
--ki-file-upload-row-bgBackground of a file row and the field label.
--ki-file-upload-row-bg-imageOptional image over the file row background.
--ki-file-upload-row-borderBoundary of a file row without an error.
--ki-file-upload-row-fgFile names, row action icons and the field label.
--ki-file-upload-row-radiusFile row corner radius.
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-layout-spacing-3xlThe 3xl spacing step for a stack or grid gap.
--ki-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-text-primary-high-emsemantic color for text primary high em.
--ki-text-supportingSupporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-underline-offsetGap between text and its underline.
--ki-typography-underline-thicknessStroke width of a resting text underline.
--ki-typography-underline-thickness-hoverStroke width of an emphasized underline on hover.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

Workshop

Open ki-file-upload in Storybook