Skip to Content

FileUpload

파일 업로드 컴포넌트. 드래그 앤 드롭 또는 클릭으로 파일을 업로드하고, 업로드된 파일 목록을 관리한다.


개요

Foundation의 FileUpload 컴포넌트를 FormItem으로 래핑하여 레이블, 필수 표시, 오류 메시지 등 폼 시스템과 통합한 컴포넌트이다.

주요 특징

  • Drag & Drop: 파일을 드래그하여 업로드 영역에 드롭
  • 파일 유효성 검증: 확장자, 용량, 개수 제한
  • 파일 목록 관리: 업로드된 파일 목록 표시 및 삭제
  • 기존 파일 표시: 서버에 이미 저장된 파일을 메타데이터만으로 목록에 표시
  • 파일 리스트 높이 제한: fileListMaxHeight로 파일 목록 영역 스크롤 처리
  • FormItem 통합: 레이블, 필수 표시, 오류 메시지 지원
  • 디자인 토큰: 테마 커스터마이징 지원

기본 사용

<FileUpload onChange={(files) => console.log(files)} />

파일 리스트 높이 제한

fileListMaxHeight prop으로 파일 목록 영역의 최대 높이를 지정한다. 파일이 많을 때 해당 영역만 스크롤된다.

// 숫자: px 단위 <FileUpload fileListMaxHeight={200} onChange={(files) => console.log(files)} /> // 문자열: CSS 단위 (rem, vh 등) <FileUpload fileListMaxHeight="10rem" onChange={(files) => console.log(files)} />

파일 리스트 커스텀 클래스

fileListClassName prop으로 파일 목록 영역에 추가 CSS 클래스를 적용할 수 있다.

<FileUpload fileListMaxHeight={200} fileListClassName="border rounded-md p-1" onChange={(files) => console.log(files)} />

FormItem 래핑

label, required, error, orientation 등 FormItem props를 지원한다.

<FileUpload label="첨부파일" required labelWidth={110} onChange={(files) => console.log(files)} /> <FileUpload label="첨부파일" orientation="vertical" error="파일을 첨부해 주세요." onChange={(files) => console.log(files)} />

기존 파일 표시

existingFiles로 서버에 저장된 파일을 목록에 표시한다. onRemoveExisting을 제공하면 삭제 버튼이 나타난다.

const [existingFiles, setExistingFiles] = useState([ { id: "1", name: "report.pdf", size: 1234567, url: "/files/report.pdf" }, { id: "2", name: "data.xlsx", size: 456789 }, ]) <FileUpload existingFiles={existingFiles} onRemoveExisting={(file) => { setExistingFiles((prev) => prev.filter((f) => f.id !== file.id)) }} onChange={(files) => console.log(files)} />

API Reference

Props

PropTypeDefaultDescription
acceptstring-허용 MIME 타입 또는 확장자 (HTML accept 형식)
maxSizenumber5242880최대 파일 크기 (byte)
maxFilesnumber10최대 파일 수
multiplebooleantrue다중 파일 선택
disabledbooleanfalse비활성화
descriptionstring-설명 텍스트
valueFile[]-파일 목록 (controlled)
onChange(files: File[]) => void-파일 변경 콜백
onError(error: string) => void-에러 발생 콜백
existingFilesExistingFile[]-서버 저장 기존 파일 목록
onRemoveExisting(file: ExistingFile) => void-기존 파일 삭제 콜백
fileListClassNamestring-파일 목록 영역 추가 CSS 클래스
fileListMaxHeightnumber | string-파일 목록 영역 최대 높이 (number: px, string: CSS 단위)
labelReactNode-레이블 텍스트
labelWidthnumber-레이블 너비 (px)
labelAlignstring-레이블 정렬
requiredboolean-필수 입력
orientation"vertical" | "horizontal"-레이블 위치
errorstring-에러 메시지
classNamestring-FormItem 컨테이너 CSS 클래스

관련 컴포넌트

Last updated on