Skip to content
Compositions

FileUploadDropzone

FileUploadDropzone - A drag-and-drop zone for file uploads. Use with the useFileUpload hook for full functionality.

Usage

import { FileMetadata, FileUploadActions, FileUploadDropzone, FileUploadItem, FileUploadList, FileUploadOptions, FileUploadState, FileUploadTrigger, FileWithPreview, formatBytes, useFileUpload } from "@instruments/materia-ui/compositions/file-upload";

Best practices

  • FileUploadDropzone is presentational - wire it to the useFileUpload hook for the actual file input, drag state, and file list; it stores nothing itself.

  • Forward the hook's handleDragEnter/Leave/Over/Drop and drag state into dragging so the drag styling matches the real drop-target state.

  • Keep title/description (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via children when needed.

Props

FileUploadDropzone

PropTypeDefaultDescription
childrenReactNode

Children to render inside (overrides default content)

classNamestring

Additional class names

descriptionstring

Secondary description text

disabledboolean

Whether the dropzone is disabled

iconLucideIcon

Icon to display (default: CloudUpload)

draggingboolean

Whether files are currently being dragged over

onClick() => void

Click handler to open file dialog

onDragEnter(e: DragEvent<HTMLElement>) => void

Drag event handlers from useFileUpload

onDragLeave(e: DragEvent<HTMLElement>) => void
onDragOver(e: DragEvent<HTMLElement>) => void
onDrop(e: DragEvent<HTMLElement>) => void
refRef<HTMLButtonElement>

Ref for the dropzone element

titlestring

Primary text

FileUploadItem

PropTypeDefaultDescription
classNamestring | undefined

Additional class names

errorstring | undefined

Error message if upload failed

completeboolean | undefined

Whether upload is complete

name(required)string

File name

onRemove(() => void) | undefined

Callback when remove button is clicked

previewUrlstring | undefined

Preview URL for images

progressnumber | undefined

Upload progress (0-100), undefined means not uploading

size(required)number

File size in bytes

type(required)string

File MIME type

FileUploadList

PropTypeDefaultDescription
animatedboolean

Whether the list should animate

classNamestring

Additional class names

completedRecord<string, boolean>

Completed files (keyed by file id)

errorsRecord<string, string>

Errors for each file (keyed by file id)

files(required)FileWithPreview[]

Array of files to display

onRemove(id: string) => void

Callback when a file's remove button is clicked

orientationOrientation

Orientation of the list

progressRecord<string, number>

Upload progress for each file (keyed by file id)

renderItem(file: FileWithPreview) => ReactNode

Render custom item content

FileUploadTrigger

PropTypeDefaultDescription
childrenReactNode

Custom children (overrides default button content)

onClick() => void

Click handler to open file dialog

refRef<HTMLButtonElement>

Ref for the button element

uploadingboolean

Whether files are currently being uploaded

uploadingLabelstring

Custom label when uploading

renderuseRender.RenderProp<Record<string, unknown>> | undefined

Replace the rendered <button> with another element or component (e.g. <Link href="…" />); styling, decorations and props are applied to it.

tone"neutral" | "brand" | "danger" | null | undefined
radius"rounded" | "square" | "full" | null | undefined
sizeButtonSizeProp"base"

Size token; icon-* variants produce a square icon-only button. Also accepts a responsive object keyed by viewport breakpoints and/or @-prefixed container queries - e.g. { base: "sm", md: "base", "@sm": "lg" }.

dotstring | undefined

CSS colour for a status dot; empty/undefined renders no dot.

loadingboolean | undefinedfalse

Show a spinner and block presses. The button stays focusable (it is aria-disabled, not natively disabled) so keyboard focus is kept.

squareboolean | null | undefined
iconIconComponent | undefined

Leading icon (Lucide or SVG component); with no children it becomes an icon-only button.

emphasis"link" | "outline" | "solid" | "ghost" | "soft" | "transparent" | null | undefined
asInputboolean | null | undefined
align"center" | "end" | "start" | null | undefined
pressedboolean | null | undefined
testIdstring
suffixIconIconComponent | undefined

Trailing icon (Lucide or SVG component) rendered at the end.

expandableboolean | undefinedfalse

Icon-only at rest; expands on hover/focus-visible to reveal the label to the right of the icon. Collapsed geometry equals the matching icon-* size, expanded equals the text button of that size - so pass a text size (sm/base/lg) OR its icon twin (icon-sm …); both resolve identically. Requires both icon and children; ignored with square. The label stays in the DOM in both states (stable accessible name).

focusedboolean | undefined

Force the focus ring on - for documentation/testing only.

hoveredboolean | undefined

Force the hover state on - for documentation/testing only.

loadingLabelstring | undefined

Label shown in place of children while loading.

iconClassNamestring | undefined

Extra classes for the leading icon.

suffixIconClassNamestring | undefined

Extra classes for the trailing icon.

dotPlacement"end" | "start" | undefined"start"

Dot position relative to content.

Also exports

  • interfaceFileMetadata
  • interfaceFileUploadActions
  • interfaceFileUploadOptions
  • interfaceFileUploadState
  • interfaceFileWithPreview
  • constformatBytes
  • constuseFileUpload

Composition

Builds on

Button, Center, Icon, Progress, Stack, Text