FileUpload

파일을 선택하거나 Drag & Drop으로 업로드할 수 있는 컴포넌트

개요

FileUpload 컴포넌트는 사용자가 파일을 선택하거나 드래그 앤 드롭하여 업로드할 수 있는 영역을 제공합니다.

주요 특징

• ✅ Drag & Drop: 파일을 드래그하여 업로드 영역에 드롭
• ✅ 파일 유효성 검증: 확장자, 용량, 개수 제한
• ✅ 파일 목록 관리: 업로드된 파일 목록 표시 및 삭제
• ✅ 파일 유형 아이콘: 확장자에 따른 자동 아이콘 표시
• ✅ Tooltip: 긴 파일명 Hover 시 전체 이름 표시
• ✅ 오류 처리: 유효하지 않은 파일 업로드 시 시각적 피드백
• ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 사용

<FileUpload
  description="파일을 선택하거나 드래그하여 업로드하세요."
  onChange={(files) => console.log(files)}
/>

파일 형식 제한

accept prop으로 허용할 파일 확장자 또는 MIME 타입을 지정합니다.

<FileUpload
  accept=".pdf,.xlsx,.docx"
  description="허용: PDF, Excel, Word 파일만"
  onError={(error) => console.log(error)}
/>
 
<FileUpload
  accept="image/*"
  description="이미지 파일만 허용"
/>

파일 용량 제한

maxSize prop으로 파일 단위 최대 용량을 바이트 단위로 설정합니다.

<FileUpload
  maxSize={1 * 1024 * 1024}
  description="최대 파일 크기: 1MB"
  onError={(error) => console.log(error)}
/>

파일 개수 제한

maxFiles로 최대 파일 수를, multiple={false}로 단일 파일 모드를 설정합니다.

<FileUpload
  maxFiles={3}
  description="최대 3개 파일만 업로드 가능"
/>
 
<FileUpload
  multiple={false}
  description="단일 파일만 업로드 가능"
/>

비활성화 상태

disabled prop으로 파일 추가 및 삭제를 제한합니다.

<FileUpload
  disabled
  description="비활성화 상태 - 파일 추가/삭제 불가"
/>

Drag & Drop 업로드

파일을 드래그하여 업로드 영역에 드롭할 수 있습니다. 드래그 시 영역이 시각적으로 변경됩니다.

<FileUpload
  description="파일을 드래그하여 업로드하세요."
  onChange={(files) => console.log(files)}
/>

파일 업로드 처리 및 상태 갱신

선택 또는 Drop된 파일이 유효성 검사를 통과하면 자동으로 업로드되며, 파일 목록 및 용량 정보가 실시간으로 갱신됩니다.

<FileUpload
  description="파일 업로드/삭제 시 목록과 용량이 자동 갱신됩니다."
  onChange={(files) => setFiles(files)}
/>

설명 텍스트

description prop으로 업로드 조건(확장자, 용량 등)을 안내합니다.

<FileUpload
  description="허용 확장자: .pdf, .xlsx, .docx / 최대 용량: 5MB / 최대 10개"
/>

API Reference

Props

Events

기본 사용법

import { FileUpload } from "@vortex/ui-foundation"
// iCignal에서도 동일하게 사용 가능
import { FileUpload } from "@vortex/ui-icignal"
 
<FileUpload
  accept=".pdf,.xlsx"
  maxSize={5 * 1024 * 1024}
  maxFiles={5}
  description="PDF, Excel 파일만 허용 (최대 5MB)"
  onChange={(files) => console.log(files)}
  onError={(error) => console.error(error)}
/>

접근성

권장 사항

• ✅ description으로 허용 파일 형식과 용량 제한을 명확히 안내
• ✅ onError 콜백을 통해 오류 메시지를 사용자에게 전달
• ✅ 키보드로 업로드 영역에 접근 가능 (클릭 동작)
• ❌ 파일 유형 제한 시 accept만 사용하고 안내 텍스트 없이 사용 지양

관련 컴포넌트

• Button: 파일 선택 트리거
• Input: 텍스트 입력
• Tooltip: 파일명 툴팁