Blitz UIBlitz UIAlpha
X

File Upload

Enables users to upload files to a server or application.

Package
shadcn/ui
"use client"

import Image from "next/image"

Installation

pnpm dlx shadcn@latest add @blitz-ui/use-file-upload

Usage

import { useFileUpload } from "@/hooks/use-file-upload"
const [{ files }, { openFileDialog, getInputProps }] = useFileUpload({
  accept: "image/*",
  multiple: false,
})
 
return (
  <div>
    <Button onClick={openFileDialog}>Upload Image</Button>
    <input {...getInputProps()} className="sr-only" />
    {files.map((file) => (
      <div key={file.id}>{file.file.name}</div>
    ))}
  </div>
)

Examples

Avatar Upload

"use client"

import {

Compact Upload

"use client"

import {

Gallery Upload

Progress Upload

Table Upload

Image Upload

Sortable Upload

API Reference

useFileUpload

A custom hook for managing file upload state and interactions.

const [state, actions] = useFileUpload(options)

Options

PropTypeDefaultDescription
maxFilesnumberInfinityMaximum number of files allowed (only when multiple is true).
maxSizenumberInfinityMaximum size for each file in bytes.
acceptstring"*"Accepted file types (e.g., "image/*", ".pdf,.docx").
multiplebooleanfalseWhether to allow multiple file selection.
initialFilesFileMetadata[][]Initial set of files to populate the state.
onFilesChange(files: FileWithPreview[]) => void-Callback fired whenever the files list changes.
onFilesAdded(files: FileWithPreview[]) => void-Callback fired when new valid files are added.
onError(errors: string[]) => void-Callback fired when validation errors occur.

State

PropertyTypeDescription
filesFileWithPreview[]The list of currently selected/uploaded files.
isDraggingbooleanWhether a file is currently being dragged over the target area.
errorsstring[]Any current validation error messages.

Actions

MethodTypeDescription
addFiles(files: FileList | File[]) => voidManually add files to the state.
removeFile(id: string) => voidRemove a file by its unique ID.
clearFiles() => voidRemove all files from the state.
clearErrors() => voidClear all current error messages.
openFileDialog() => voidProgrammatically open the browser's file selection dialog.
getInputProps(props?) => InputPropsReturns props for a hidden <input type="file" /> element.
handleDragEnter(e) => voidEvent handler for the onDragEnter event.
handleDragLeave(e) => voidEvent handler for the onDragLeave event.
handleDragOver(e) => voidEvent handler for the onDragOver event.
handleDrop(e) => voidEvent handler for the onDrop event.

Types

FileMetadata

type FileMetadata = {
  name: string
  size: number
  type: string
  url: string
  id: string
}

FileWithPreview

type FileWithPreview = {
  file: File | FileMetadata
  id: string
  preview?: string
}

formatBytes

A utility function to format a byte count into a human-readable string (e.g., 1.5 MB).

function formatBytes(bytes: number, decimals?: number): string