ki-file-upload
@kimen/elements/ki-file-upload- Source
- Agent reference
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.
<ki-file-uploadlabel="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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
accept | accept | string | undefined | – | Comma-separated extensions, MIME types and MIME wildcards allowed in new selections. |
browse-label | browseLabel | string | 'Browse files' | Visible text of the native file picker button. |
cancel-label | cancelLabel | string | 'Cancel upload of {file}' | Accessible name template for cancellation. Use {file} for the displayed filename. |
count-error | countError | string | 'Too many files.' | Rejection text for a file beyond selection capacity. |
disabled | disabled | boolean | false | Disables the picker and file actions and excludes the field from submission. |
done-label | doneLabel | string | 'Uploaded' | Status text for a completed upload. |
drop-label | dropLabel | string | 'Drop files here or' | Drop instruction shown just before the Browse button. |
error-text | errorText | string | undefined | – | Application validation error. Clear it to allow form submission again. |
failed-label | failedLabel | string | 'Upload failed.' | Fallback status text for a failed upload without a supplied error. |
help-text | helpText | string | undefined | – | Guidance for file formats, limits or the purpose of this field. |
label | label | string | 'Upload files' | Visible label and accessible name of the upload group. |
list-label | listLabel | string | 'Files' | Accessible name of the list of files. |
max-files | maxFiles | number | undefined | – | Maximum accepted local files as a nonnegative integer. Single-file mode also caps this at one. |
max-size | maxSize | string | undefined | – | Maximum size per selected file in bytes or decimal B, KB, MB or GB, such as "10MB". |
multiple | multiple | boolean | false | Allows a selection of more than one file. |
name | name | string | undefined | – | Form-data key repeated for each accepted original file. |
queued-label | queuedLabel | string | 'Queued' | Status text for an accepted file waiting to upload. |
remove-label | removeLabel | string | 'Remove {file}' | Accessible name template for removal. Use {file} for the displayed filename. |
required | required | boolean | false | Requires at least one original accepted file to submit the form. |
required-label | requiredLabel | string | 'Required' | Visible annotation for a required file field. |
required-message | requiredMessage | string | 'Select a file.' | Validation message when the form requires a file and none is selected. |
size-error | sizeError | string | 'This file is too large.' | Rejection text for a file larger than max-size. |
type-error | typeError | string | 'This file type is not allowed.' | Rejection text for a file that does not match accept. |
uploading-label | uploadingLabel | string | 'Uploading {file}' | Progress indicator name template. Use {file} for the displayed filename. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-file-cancel | CustomEvent<KiFileActionDetail> | Requests that the application cancel the identified upload. |
ki-file-remove | CustomEvent<KiFileActionDetail> | Reports a row removed by the user, after updating the file list. |
ki-files-add | CustomEvent<KiFilesAddDetail> | Reports the accepted rows in one picker or drop batch, each with its original File. |
Slots
| Slot | Description |
|---|---|
help | Plain-language guidance for the picker, in place of help-text. |
CSS parts
| Part | Description |
|---|---|
action | Native button for removal or cancellation. |
browse | Native button that opens the file picker. |
drop-zone | Surface that receives files dragged from the operating system. |
error | Field-level form validation error. |
file-meta | Size, outcome or error text for the file. |
file-name | Name displayed for the file. |
help | Guidance associated with the field. |
input | Hidden native file picker. |
label | Field label and optional required annotation. |
list | List of selected files and rejections. |
progress | Progress indicator for an uploading file. |
row | A 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.
| Token | Description |
|---|---|
--ki-corner-inline | Small radius for an outline around inline content. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The 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-bg | Drop zone background while files are dragged over it. |
--ki-file-upload-active-border | Drop zone boundary while files are dragged over it. |
--ki-file-upload-active-fg | Main drop zone text while files are dragged over it. |
--ki-file-upload-backdrop-filter | Complete backdrop filter applied behind the drop zone. |
--ki-file-upload-bg | Drop zone background at rest. |
--ki-file-upload-bg-image | Optional image over the drop zone background. |
--ki-file-upload-border | Dashed boundary of the drop zone. |
--ki-file-upload-border-width | Outline stroke width for the drop zone and file rows. |
--ki-file-upload-error-bg | Background of a file row with an error. |
--ki-file-upload-error-border | Boundary of a file row with an error. |
--ki-file-upload-error-fg | Text of a file error or field error. |
--ki-file-upload-fg | Main drop zone text at rest. |
--ki-file-upload-radius | Drop zone corner radius. |
--ki-file-upload-row-backdrop-filter | Complete backdrop filter applied behind a file row. |
--ki-file-upload-row-bg | Background of a file row and the field label. |
--ki-file-upload-row-bg-image | Optional image over the file row background. |
--ki-file-upload-row-border | Boundary of a file row without an error. |
--ki-file-upload-row-fg | File names, row action icons and the field label. |
--ki-file-upload-row-radius | File row corner radius. |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness 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-3xl | The 3xl spacing step for a stack or grid gap. |
--ki-layout-spacing-md | The md spacing step for a stack or grid gap. |
--ki-layout-spacing-xs | The xs spacing step for a stack or grid gap. |
--ki-text-primary-high-em | semantic color for text primary high em. |
--ki-text-supporting | Supporting 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-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-underline-offset | Gap between text and its underline. |
--ki-typography-underline-thickness | Stroke width of a resting text underline. |
--ki-typography-underline-thickness-hover | Stroke width of an emphasized underline on hover. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |