Components

File Upload

Manages file upload states including drag-and-drop, loading, error, and image preview. Built with the compound component pattern for flexible composition.

Replacing soon

GitHub

Drag and drop files here to upload

Anatomy

import {FileUpload} from '@staffbase/spark';

<FileUpload>
  <FileUpload.Wrapper />
  <FileUpload.Text />
  <FileUpload.Preview />
  <FileUpload.Overlay />
</FileUpload>;

Examples

Loading state

Set variant="loading" while the file is being uploaded. Use a LoadingSpinner inside to communicate progress.

Error state

Set variant="error" when the upload fails. Use FileUpload.Text with variant="critical" to surface the error.

Upload failed

Please try again

Image preview

Use FileUpload.Preview with variant="hasImage" to display a thumbnail with optional edit and delete actions.

Opening the file chooser programmatically

Use a ref to call openFileChooser() from a custom trigger button, such as an item in a Menu.

Drag and drop files here to upload or

API reference

FileUpload

Note: We have identified accessibility concerns on this component. Use with caution and test thoroughly with assistive technologies.

Name	Type	Description
`onDrop`	`DropzoneOptions['onDrop']`	Called with the accepted files when they are dropped onto the dropzone.
`variant`	`defaultloadingdraggingerrorhasImage`	Controls the visual border style of the component.
`children`	`ReactNode`	Content to display inside the dropzone. Use `FileUpload.Wrapper` to differentiate drag and non-drag states.
`disabled`	`boolean`	Disables the dropzone.
`accept`	`DropzoneOptions['accept']`	Restricts accepted file types, e.g. `{'image/png': ['.png']}`.
`ref`	`MutableRefObject<FileUploadRef>`	Ref exposing `openFileChooser()` to programmatically open the native file picker.
`className`	`string`	CSS class applied to the root element.

Wrapper

Conditionally renders its children based on whether a drag is in progress.

Name	Type	Description
`showOnDrag`	`boolean`	When `true`, renders children only while a drag is active. When `false`, renders children at all other times.
`children`	`ReactNode`	Content to show in the relevant drag state.

Text

Name	Type	Description
`children`	`string`	The text content.
`variant`	`defaultcriticalinfoneutral`	Visual style of the text. Default:`default`

Preview

Displays a background image thumbnail with optional action buttons.

Name	Type	Description
`previewUrl`	`string`	URL of the image to display as the preview background.
`onEdit`	`() => void`	When provided, renders an edit icon button that calls this handler.
`onDelete`	`() => void`	When provided, renders a delete icon button that calls this handler.
`additionalButtons`	`ReactElement`	Additional action buttons rendered alongside edit and delete.
`children`	`ReactNode`	Overlay content, such as `FileUpload.Overlay`.

Overlay

A full-size overlay rendered on top of FileUpload.Preview, typically used to show a drop hint during drag.

Name	Type	Description
`children`	`ReactNode`	Content displayed inside the overlay.

Always provide both a showOnDrag={false} wrapper (default content) and a showOnDrag={true} wrapper (drag hint) so the UI responds clearly during drag interactions.
Use variant to reflect the actual upload state — never leave it on "default" while loading or after an error.
Use LoadingSpinner inside the loading state and provide an aria-label describing what is loading.
Surface errors with variant="error" on the root and FileUpload.Text with variant="critical" for the message.
Restrict accepted file types with accept to prevent invalid uploads before they reach the server.