File Upload - HapplyUI

A styled dropzone area for file uploads with built-in presets for document, image, video, audio, and attachment types. Each preset includes a unique illustration, title, description, and button text for consistent usage across the platform.

Installation

bunx @happlyui/cli@latest add file-upload

Dependencies

npm packages

@radix-ui/react-slot

Registry dependencies

These are automatically installed when you add this component.

happly-ui-utils
polymorphic

Usage

import * as FileUpload from "@/components/ui/file-upload"

<FileUpload.Dropzone type="document" />

Examples

Document Upload

Preset for uploading documents (PDF, DOCX, XLSX, PPTX, ZIP).

Choose an existing file or upload a new one.

Supported formats: PDF, DOCX, XLSX, PPTX, ZIP. Max size: 50MB.

Browse File

<FileUpload.Dropzone type="document" />

Image Upload

Preset for uploading images (JPG, PNG).

Choose an existing image or upload a new one.

Supported formats: JPG, PNG. Max size: 3MB.

Browse File

<FileUpload.Dropzone type="image" />

Video Upload

Preset for uploading videos (MP4, AVI, MOV).

Choose an existing video file or upload a new one.

Supported formats: MP4, AVI, MOV. Max size: 50MB.

Browse File

<FileUpload.Dropzone type="video" />

Audio Upload

Preset for uploading audio files (MP3, WAV).

Choose an existing audio file or upload a new one.

Supported formats: MP3, WAV. Max size: 50MB.

Browse File

<FileUpload.Dropzone type="audio" />

Attachment Upload

General-purpose attachment upload preset.

Choose an existing file or upload a new one.

Supported formats: PDF, DOCX, XLSX, PPTX, ZIP. Max size: 50MB.

Upload

<FileUpload.Dropzone type="attachment" />

Custom Overrides

Override the preset title, description, or button text.

Upload your banner image

Recommended size: 1200 × 675 px (16:9 ratio, horizontal layout)

Choose Image

<FileUpload.Dropzone
  type="image"
  title="Upload your banner image"
  description="Recommended size: 1200 × 675 px"
  buttonText="Choose Image"
  inputProps={{ accept: 'image/*' }}
/>

Dragging

Visual feedback when a file is dragged over the dropzone.

Drop your file here

Release to upload

Browse File

<FileUpload.Root dragging>
  <FileUpload.Content>
    <FileUpload.Title>Drop your file here</FileUpload.Title>
    <FileUpload.Description>Release to upload</FileUpload.Description>
  </FileUpload.Content>
  <FileUpload.Button>Browse File</FileUpload.Button>
</FileUpload.Root>

API Reference

FileUpload.Dropzone

A convenience preset component that renders the full dropzone based on file type.

Prop	Type	Default	Description
`type`	`'document' \| 'image' \| 'video' \| 'audio' \| 'attachment'`	-	The upload type preset. Determines the icon, title, description, and button text.
`title`	`string`	-	Override the preset title text.
`description`	`string`	-	Override the preset description text.
`buttonText`	`string`	-	Override the preset button text.
`inputProps`	`React.InputHTMLAttributes<HTMLInputElement>`	-	Props passed to the hidden file input (e.g., accept, multiple).

FileUpload.Root

The dropzone container for custom compositions. Renders as a <label> by default.

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Merge props onto a child element instead of rendering a <label>.
`dragging`	`boolean`	`false`	When true, applies a highlighted border and background to indicate drag-over state.

FileUpload.Content

Wrapper for the title and description with consistent vertical spacing.

Prop	Type	Default	Description

FileUpload.Title

The main heading text inside the dropzone.

Prop	Type	Default	Description

FileUpload.Description

Secondary description text (e.g., accepted formats, size limits).

Prop	Type	Default	Description

FileUpload.Button

A visual button inside the dropzone.

Prop	Type	Default	Description

FileUpload.Icon

A polymorphic icon slot for custom compositions.

Prop	Type	Default	Description
`as`	`React.ElementType`	`'div'`	The element or component to render.