FileUpload
파일 업로드 컴포넌트. 드래그 앤 드롭 또는 클릭으로 파일을 업로드하고, 업로드된 파일 목록을 관리한다.
개요
Foundation의 FileUpload 컴포넌트를 FormItem으로 래핑하여 레이블, 필수 표시, 오류 메시지 등 폼 시스템과 통합한 컴포넌트이다.
주요 특징
- ✅ Drag & Drop: 파일을 드래그하여 업로드 영역에 드롭
- ✅ 파일 유효성 검증: 확장자, 용량, 개수 제한
- ✅ 파일 목록 관리: 업로드된 파일 목록 표시 및 삭제
- ✅ 기존 파일 표시: 서버에 이미 저장된 파일을 메타데이터만으로 목록에 표시
- ✅ 파일 리스트 높이 제한:
fileListMaxHeight로 파일 목록 영역 스크롤 처리 - ✅ FormItem 통합: 레이블, 필수 표시, 오류 메시지 지원
- ✅ 디자인 토큰: 테마 커스터마이징 지원
기본 사용
Preview
<FileUpload onChange={(files) => console.log(files)} />파일 리스트 높이 제한
fileListMaxHeight prop으로 파일 목록 영역의 최대 높이를 지정한다. 파일이 많을 때 해당 영역만 스크롤된다.
Code
// 숫자: px 단위
<FileUpload
fileListMaxHeight={200}
onChange={(files) => console.log(files)}
/>
// 문자열: CSS 단위 (rem, vh 등)
<FileUpload
fileListMaxHeight="10rem"
onChange={(files) => console.log(files)}
/>파일 리스트 커스텀 클래스
fileListClassName prop으로 파일 목록 영역에 추가 CSS 클래스를 적용할 수 있다.
Code
<FileUpload
fileListMaxHeight={200}
fileListClassName="border rounded-md p-1"
onChange={(files) => console.log(files)}
/>FormItem 래핑
label, required, error, orientation 등 FormItem props를 지원한다.
Code
<FileUpload
label="첨부파일"
required
labelWidth={110}
onChange={(files) => console.log(files)}
/>
<FileUpload
label="첨부파일"
orientation="vertical"
error="파일을 첨부해 주세요."
onChange={(files) => console.log(files)}
/>기존 파일 표시
existingFiles로 서버에 저장된 파일을 목록에 표시한다. onRemoveExisting을 제공하면 삭제 버튼이 나타난다.
Code
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
| Prop | Type | Default | Description |
|---|---|---|---|
accept | string | - | 허용 MIME 타입 또는 확장자 (HTML accept 형식) |
maxSize | number | 5242880 | 최대 파일 크기 (byte) |
maxFiles | number | 10 | 최대 파일 수 |
multiple | boolean | true | 다중 파일 선택 |
disabled | boolean | false | 비활성화 |
description | string | - | 설명 텍스트 |
value | File[] | - | 파일 목록 (controlled) |
onChange | (files: File[]) => void | - | 파일 변경 콜백 |
onError | (error: string) => void | - | 에러 발생 콜백 |
existingFiles | ExistingFile[] | - | 서버 저장 기존 파일 목록 |
onRemoveExisting | (file: ExistingFile) => void | - | 기존 파일 삭제 콜백 |
fileListClassName | string | - | 파일 목록 영역 추가 CSS 클래스 |
fileListMaxHeight | number | string | - | 파일 목록 영역 최대 높이 (number: px, string: CSS 단위) |
label | ReactNode | - | 레이블 텍스트 |
labelWidth | number | - | 레이블 너비 (px) |
labelAlign | string | - | 레이블 정렬 |
required | boolean | - | 필수 입력 |
orientation | "vertical" | "horizontal" | - | 레이블 위치 |
error | string | - | 에러 메시지 |
className | string | - | FormItem 컨테이너 CSS 클래스 |
관련 컴포넌트
- Foundation FileUpload: 기본 FileUpload 컴포넌트
- FormItem: 폼 래퍼
Last updated on