Skip to content
Docs
컴포넌트로 돌아가기

Upload

@hua-labs/ui
v1.0.0

드래그 앤 드롭을 지원하는 파일 업로드 컴포넌트입니다. 파일 타입 필터링, 용량 제한, 업로드 진행률 표시 등을 지원합니다.

라이브 데모

기본 사용법

파일을 선택하거나 여기에 드래그하세요

이미지 전용 (최대 5MB)

이미지를 여기에 드롭하세요 (최대 5MB)

지원 형식: image/* • 최대 크기: 5 MB

다중 파일 (개수 제한)

최대 3개 파일을 드롭하세요 (각 최대 10MB)

• 최대 크기: 10 MB • 최대 3개

크기 옵션

size="sm"

Small

size="md" (default)

Medium

size="lg"

Large

비활성화 상태

업로드가 비활성화되었습니다

Props

이름타입기본값설명
filesUploadedFile[][]업로드된 파일 목록
onChange(files: File[]) => void-Callback when files are selected
onRemove(file: UploadedFile) => void-Callback when file is removed
multiplebooleanfalse다중 파일 선택 허용
acceptstring-허용 파일 타입 (예: "image/*", ".pdf")
maxSizenumber-Maximum file size in bytes
maxFilesnumber-Maximum number of files
disabledbooleanfalse비활성화 상태
dragDropbooleantrueEnable drag and drop functionality
placeholderstring"파일을 선택하거나 여기에 드래그하세요"플레이스홀더 텍스트
size"sm" | "md" | "lg""md"업로드 영역 크기
dotstring-
styleReact.CSSProperties-

UploadedFile 인터페이스

PropertyTypeRequired설명
idstring*docs:components.upload.props.id
fileFile*docs:components.upload.props.file
namestring*docs:components.upload.props.name
sizenumber*docs:components.upload.props.size
typestring*docs:components.upload.props.type
progressnumber-docs:components.upload.props.progress
status"pending" | "uploading" | "success" | "error"-docs:components.upload.props.status
urlstring-docs:components.upload.props.url
errorstring-docs:components.upload.props.error

파일 타입 필터 예시

image/*모든 이미지 파일
image/png, image/jpegPNG, JPEG 이미지만
.pdfPDF 문서만
video/*모든 비디오 파일
.doc, .docx, .pdf문서 파일 (Word, PDF)

코드 예시

docs:common.basicUsagetsx
1import { Upload } from '@hua-labs/ui/form';
2import type { UploadedFile } from '@hua-labs/ui';
3const [files, setFiles] = useState<UploadedFile[]>([]);
4 
5const handleChange = (newFiles: File[]) => {
6 const uploadedFiles = newFiles.map((file) => ({
7 id: crypto.randomUUID(),
8 file,
9 name: file.name,
10 size: file.size,
11 type: file.type,
12 status: "success" as const,
13 }));
14 setFiles((prev) => [...prev, ...uploadedFiles]);
15};
16 
17<Upload
18 files={files}
19 onChange={handleChange}
20 onRemove={(file) => setFiles((prev) => prev.filter((f) => f.id !== file.id))}
21/>
docs:components.upload.examples.imageOnlytsx
1<Upload
2 accept="image/*"
3 maxSize={5 * 1024 * 1024} // 5MB
4 files={files}
5 onChange={handleChange}
6 onRemove={handleRemove}
7 placeholder="이미지를 선택하거나 드래그하세요"
8/>
docs:components.upload.examples.multipletsx
1<Upload
2 multiple
3 maxFiles={5}
4 maxSize={10 * 1024 * 1024} // 10MB
5 files={files}
6 onChange={handleChange}
7 onRemove={handleRemove}
8 placeholder="최대 5개 파일 (각 10MB 이하)"
9/>
docs:components.upload.examples.progresstsx
1// 파일 상태 업데이트 예시
2const uploadFile = async (file: UploadedFile) => {
3 // 업로드 시작
4 updateFileStatus(file.id, { status: "uploading", progress: 0 });
5 
6 try {
7 // 실제 업로드 로직 (예: XMLHttpRequest with progress)
8 const url = await uploadToServer(file.file, (progress) => {
9 updateFileStatus(file.id, { progress });
10 });
11 
12 updateFileStatus(file.id, { status: "success", url });
13 } catch (error) {
14 updateFileStatus(file.id, { status: "error", error: "업로드 실패" });
15 }
16};

사용 팁

  • onChange로 File 객체를 받아 서버나 스토리지 서비스에 업로드하세요
  • UploadedFile의 status와 progress 필드를 활용해 업로드 진행 상태를 표시하세요
  • 검증은 클라이언트에서 수행되지만, 서버에서도 파일 크기와 타입을 항상 검증하세요

접근성

  • 키보드 지원: Enter 또는 Space로 파일 선택기 열기
  • 스크린 리더: 파일 입력에 적절한 aria-label 제공
  • 포커스 표시: 인터랙티브 요소에 명확한 포커스 표시