HapplyUI

File Upload

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).

<FileUpload.Dropzone type="document" />

Image Upload

Preset for uploading images (JPG, PNG).

<FileUpload.Dropzone type="image" />

Video Upload

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

<FileUpload.Dropzone type="video" />

Audio Upload

Preset for uploading audio files (MP3, WAV).

<FileUpload.Dropzone type="audio" />

Attachment Upload

General-purpose attachment upload preset.

<FileUpload.Dropzone type="attachment" />

Custom Overrides

Override the preset title, description, or button text.

<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.

<FileUpload.Root dragging>
  <FileUpload.Content>
    <FileUpload.Title>Drop your file here</FileUpload.Title>
    <FileUpload.Description>Release to start the upload.</FileUpload.Description>
  </FileUpload.Content>
  <FileUpload.Button>Choose file</FileUpload.Button>
</FileUpload.Root>

Disabled

Blocks interaction (the hidden file input is disabled so the file picker cannot open). The title, description, and button shift to muted disabled colors while the icon stays as-is — the dropzone is not uniformly dimmed.

<FileUpload.Dropzone type="image" disabled />

Disabled (hand-composed)

`disabled` on Root is passed down through context, so Button, Icon, Title, and Description mute themselves without being told individually. Pass `disabled` on a slot to override what it inherits — an explicit value always wins, so `disabled={false}` keeps that one slot at full strength.

<FileUpload.Root disabled>
  <FileUpload.Icon as={RiImageLine} />
  <FileUpload.Content>
    <FileUpload.Title>Upload your banner image</FileUpload.Title>
    <FileUpload.Description>Recommended size: 1200 × 675 px</FileUpload.Description>
  </FileUpload.Content>
  <FileUpload.Button>Choose file</FileUpload.Button>
</FileUpload.Root>

API Reference

FileUpload.Dropzone

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

PropTypeDefaultDescription
type'document' | 'image' | 'video' | 'audio' | 'attachment'-The upload type preset. Determines the icon, title, description, and button text.
titlestring-Override the preset title text.
descriptionstring-Override the preset description text.
buttonTextstring-Override the preset button text.
inputPropsReact.InputHTMLAttributes<HTMLInputElement>-Props passed to the hidden file input (e.g., accept, multiple).
disabledbooleanfalseDisables the dropzone: mutes the title/description/button to disabled colors (icon unchanged), removes the pointer cursor and hover state, blocks click/drag interaction, and disables the hidden file input.

FileUpload.Root

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

PropTypeDefaultDescription
asChildbooleanfalseMerge props onto a child element instead of rendering a <label>.
draggingbooleanfalseWhen true, applies a highlighted border and background to indicate drag-over state.
disabledbooleanfalseBlocks click/drag interaction via pointer-events, removes the pointer cursor and hover state, and puts the dropzone on the weak background. Also provided through context: Button, Icon, Title, and Description mute themselves from it, so a hand-composed dropzone dims without threading `disabled` to every slot. An explicit `disabled` on a slot wins over the inherited value.

FileUpload.Content

Wrapper for the title and description with consistent vertical spacing.

PropTypeDefaultDescription

FileUpload.Title

The main heading text inside the dropzone.

PropTypeDefaultDescription
disabledboolean-Mutes the title to the disabled color. Inherited from a disabled Root when omitted; set it here to override that.

FileUpload.Description

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

PropTypeDefaultDescription
disabledboolean-Mutes the description to the disabled color. Inherited from a disabled Root when omitted; set it here to override that.

FileUpload.Button

A visual button inside the dropzone.

PropTypeDefaultDescription
disabledboolean-Mutes the button label to the disabled color. Inherited from a disabled Root when omitted; set it here to override that.

FileUpload.Icon

A polymorphic icon slot for custom compositions.

PropTypeDefaultDescription
asReact.ElementType'div'The element or component to render.
disabledboolean-Mutes the icon to the disabled color. Inherited from a disabled Root when omitted; set it here to override that. The Dropzone presets render their own illustration rather than this slot, so their icon keeps its color when disabled.

Previous
File Format Icon