File uploader API
Props, slots, labels and styling of the slotsmith File uploader.
Slots
FileUploader has 13 slots. Pass a replacement for any of them in components; every slot you leave out keeps its fallback. Element slots receive DOM props, so a library's own element fits as it is; widget slots receive named props and usually need a few lines of adapter.
| Name | Kind | Props it receives | Default fallback | data-* attributes |
|---|---|---|---|---|
Root | <element> | DOM props: | Fallback source |
|
Dropzone | <element> | DOM props: | Fallback source |
|
Input | <element> | DOM props: | Fallback source | — |
Icon | {widget} |
| Fallback source |
|
Empty | {widget} |
| Fallback source | — |
Trigger | {widget} |
| Fallback source | — |
List | <element> | DOM props:
| Fallback source | — |
Item | <element> | DOM props: | Fallback source |
|
Thumbnail | {widget} |
| Fallback source | — |
ItemMeta | {widget} |
| Fallback source | — |
Progress | {widget} |
| Fallback source |
|
Action | {widget} |
| Fallback source |
|
Rejections | {widget} |
| Fallback source | — |
Props
Every prop of FileUploader, grouped as in the library's documentation. Controlled state comes in pairs: pass a value with its change handler, or only the default to leave the state inside the component.
| Name | Type | Default | Description |
|---|---|---|---|
| Selection | |||
accept | string | | — | |
multiple | boolean |
| Allow more than one file. Defaults to |
max | number | — | How many items the list may hold in total. |
max | number | — | |
min | number | — | |
validate | ( | — | Your own rule. Return a message to refuse the file, or nothing to allow it. |
disabled | boolean | — | Nothing can be picked, dropped or removed. |
| Value | |||
value | UploadItem< | — | Controlled items. |
on | ( | — | Called with the new items after every change. |
default | InitialValue< | — | Where an uncontrolled uploader starts: items, files or URLs. |
on | ( | — | Convenience for picker mode: the picked files, whenever they change. |
on | ( | — | Convenience for upload mode: the stored URLs, whenever they change. |
name | string | — | The form field name. A plain HTML form then submits every item under it: a file picked in the browser as the file, as |
| Uploading | |||
upload | UploadFn< | — | Sends one file. Omit it and nothing is ever uploaded — the component becomes a picker and items stay |
auto | boolean | true | Start uploading as soon as files are picked. Defaults to |
concurrency | number | 3 | How many uploads may run at once. Defaults to |
on | ( | — | Called for each file that finished uploading. |
on | ( | — | Called when an upload fails. |
on | ( | — | Called with the files the constraints turned away. |
| Rendering | |||
variant | FileUploaderVariant | dropzone | How the component is laid out. Defaults to |
components | Partial< | — | Replace any part; the rest fall back to |
labels | Partial< | — | Override any text. Wins over |
locale | LocaleInput | the provider's | The language: a locale object, or the tag of one given to |
validation | Partial< | — | Wording for rejection messages. |
slot | FileUploaderSlotProps | — | Extra DOM props for the element parts. |
preview | boolean | | — | Object-URL previews for images. |
hide | boolean | — | Hide the item list, e.g. when you render the files yourself. |
children | ReactNode | — | Rendered inside the drop zone, under the title. |
capture | boolean | — | Swallow drops that miss the drop zone, so the browser doesn't open the file. |
virtual | FileUploaderVirtualOptions | — | Renders only the items in view, for batches of hundreds: pass the virtualizer hook ( |
Any other prop is passed to the root <div> element.
Labels & locales
Every string FileUploader shows or announces, with its English default. Pass labels to change some of them for one component, or locale to switch every string to another language. The demo below does both.
| Key | Type | English default | Description |
|---|---|---|---|
title | ReactNode | "Drag and drop, | The drop zone's headline. |
hint | ( | hint(prints | The line under it; the default names the limits. |
drop | ReactNode | "Drop to add" | While a file is over the zone. |
browse | ReactNode | "Browse" | The browse button. |
dropzone | string | "Add files" | Accessible name of the drop zone. |
remove | string | "Remove file" | |
retry | string | "Retry upload" | |
cancel | string | "Cancel upload" | |
progress | ( | progress(prints | Accessible name of an item's progress bar. |
ready | ReactNode | "Ready" | Status wording per item state. |
uploading | ReactNode | "Uploading…" | |
done | ReactNode | "Uploaded" | |
failed | ReactNode | "Failed" | |
preview | ( | preview(prints | Accessible name for a preview. |
dismiss | string | "Dismiss" | Dismisses the rejection list. |
rejected | ( | rejectedTitle(prints | Announced when files are refused. |
Validation messages
The messages for files the constraints turn away, a second labels section. Pass validationLabels to change some of them for one component; a locale pack translates them with the rest.
| Key | Type | English default | Description |
|---|---|---|---|
wrong | ( | wrongType(prints | A file that matches none of the |
too | ( | tooLarge(prints | A file over |
too | ( | tooSmall(prints | A file under |
too | ( | tooMany(prints | A file past |
import { FileUploader } from "slotsmith/file-uploader";
import { de } from "slotsmith/locales/de";
export default function Labels() {
return (
<FileUploader
multiple
accept="image/*"
maxSize={2 * 1024 * 1024}
// Every string in German, the rejection messages included, from the ready-made pack…
locale={de}
// …except these, replaced for this uploader only. `labels` covers the parts' text,
labels={{ title: "Belege hierher ziehen", browse: "Belege auswählen" }}
// and `validationLabels` the messages for refused files.
validationLabels={{ wrongType: (name) => `${name}: bitte nur Bilder` }}
/>
);
}The ready-made language packs, right-to-left support and app-wide locales are on the Languages page.
Styling
The class names the fallbacks of FileUploader put on their elements, and the tokens its stylesheet reads. Set a token on the component, or on any element around it, to restyle it; target a class only for what no token covers.
| Class | Slot |
|---|---|
.sfu | |
.sfu__actions | — |
.sfu__error | — |
.sfu__compact | — |
.sfu__hint | — |
.sfu__input | |
.sfu__icon | |
.sfu__copy | |
.sfu__title | — |
.sfu__browse | |
.sfu__thumb | |
.sfu__thumb-img | — |
.sfu__meta | |
.sfu__name | — |
.sfu__sub | — |
.sfu__progress | |
.sfu__progress-bar | — |
.sfu__action | |
.sfu__rejections | |
.sfu__zone | |
.sfu__list | |
.sfu__item |
| Token | Layer |
|---|---|
--sfu-accent | This component |
--sfu-bg | This component |
--sfu-border | This component |
--sfu-danger | This component |
--sfu-font-size | This component |
--sfu-gap | This component |
--sfu-hover | This component |
--sfu-muted | This component |
--sfu-radius | This component |
--sfu-surface | This component |
--sfu-text | This component |
--sfu-tile-size | This component |
--ss-accent | Shared by every component |
--ss-border | Shared by every component |
--ss-danger | Shared by every component |
--ss-font-size | Shared by every component |
--ss-hover | Shared by every component |
--ss-muted | Shared by every component |
--ss-radius | Shared by every component |
--ss-surface | Shared by every component |
--ss-text | Shared by every component |
Every token switches to its dark value under .dark, [data-theme="dark"], on the page or on any element around the component.