FilePicker

파일을 끌어다 놓거나 눌러서 파일 창을 여는 dropzone입니다. 크기와 형식, 개수 제한을 검사하고 거부된 파일을 따로 알려 줍니다.

import { FilePicker } from 'neba';

<FilePicker
  multiple
  label="첨부"
  accept="image/*,.pdf"
  maxSize={5_000_000}
  maxFiles={4}
  onFilesChange={setFiles}
  onReject={setRejected}
/>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	'outline'	표면의 무게. 셋 다 점선 테두리는 공유합니다. 라이브러리에서 실선이 아닌 선을 긋는 유일한 곳이고, 장식이 아니라 "여기에 놓을 수 있다"는 관례이기 때문입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	상자의 여백과 글자 크기. 상자는 안에 쓰인 글이 아니라 받아 내야 할 제스처에 맞춰 커집니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
accept	string	—	브라우저 파일 창이 보여 줄 종류, 'image/*,.pdf'. 드롭된 파일도 같은 문자열로 검사합니다. 브라우저는 그렇게 하지 않습니다
multiple	boolean	false	파일을 여러 개 고를 수 있는지
maxSize	number	—	파일 하나의 최대 크기(바이트)
maxFiles	number	—	한 번에 들고 있을 수 있는 개수. 한 번의 드롭이 아니라 이미 들고 있는 것과 합쳐서 셉니다
value	readonly File[]	—	고른 파일들. controlled
defaultValue	readonly File[]	—	처음 고른 파일들
onFilesChange	(files: File[]) => void	—	파일 목록이 바뀔 때
onReject	(rejections: FileRejection[]) => void	—	되돌려 보낸 파일과 그 이유. 없으면 거부된 파일이 조용히 사라지는데, 드롭존이 하는 가장 나쁜 일입니다
title	ReactNode	—	상자 안의 문장
hint	ReactNode	—	그 아래 줄, 무엇을, 얼마나 크게, 몇 개까지
icon	ReactNode	—	문장 위의 글리프. null을 주면 그림 없는 상자가 됩니다
showList	boolean	true	고른 파일들을 상자 아래에 나열하고 각각 지울 방법을 붙입니다
removeLabel	(name: string) => string	—	파일 삭제 버튼의 접근성 이름
label	ReactNode	—	컨트롤과 연결되는 라벨. Base UI Field가 묶어 줍니다
description	ReactNode	—	보조 설명
error	ReactNode	—	오류 메시지. 값이 있으면 invalid 상태도 함께 켜지고 색 계열이 danger로 넘어갑니다
invalid	boolean	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
readOnly	boolean	false	값은 보이지만 바꿀 수 없음. 색과 가장자리는 유지한 채 채도만 빠집니다
disabled	boolean	false	사용 불가. 색 계열을 버리고 중립 회색이 됩니다
fullWidth	boolean	true	컨테이너 너비만큼 확장
required	boolean	false	폼 제출 전에 파일이 있어야 하는지
name	string	—	폼 제출 시의 필드 이름

<div>의 native 속성은 root로 전달됩니다. color · defaultValue · title만 위 표와 이름이 겹쳐 제외됩니다.

예시

variant

세 가지 무게 모두 점선 테두리를 공유합니다. 점선 사각형은 드롭을 받는 영역이라는 관례적 표시입니다.

import { FilePicker } from 'neba';

export default function FilePickerVariants() {
  return (
    <div className="grid w-full grid-cols-1 gap-4 lg:grid-cols-3">
      {(['solid', 'outline', 'text'] as const).map((variant) => (
        <FilePicker key={variant} variant={variant} size="sm" title={variant} hint="Any file" />
      ))}
    </div>
  );
}

accept · maxSize · maxFiles

브라우저의 accept 속성은 파일 창에만 적용되고 드래그로 도착한 파일에는 적용되지 않으므로, 이 컴포넌트가 같은 문자열을 직접 검사합니다. .확장자 · type/subtype · type/* 세 형태를 모두 지원합니다.

maxFiles는 한 번에 놓을 수 있는 개수가 아니라 보유할 수 있는 총 개수입니다. 이미 두 개를 들고 있는 maxFiles={3} 픽커에 세 개를 놓으면 하나만 받아들입니다.

onReject

제한에 걸려 거부된 파일과 그 이유를 전달합니다. 이 핸들러가 없으면 거부된 파일이 아무 표시 없이 사라지므로 반드시 붙이세요.

import { useState } from 'react';
import { Alert, FilePicker, type FileRejection } from 'neba';

const WHY: Record<FileRejection['reason'], string> = {
  type: 'is not an image',
  size: 'is over 100 kB',
  count: 'would be the third file'
};

/**
 * A rejected file that vanishes without a word is the worst thing a dropzone
 * does, which is why `onReject` exists at all: the component turns files away,
 * and only the application knows how to say so.
 */
export default function FilePickerRejection() {
  const [files, setFiles] = useState<File[]>([]);
  const [rejected, setRejected] = useState<FileRejection[]>([]);

  return (
    <div className="flex w-full flex-col gap-3">
      <FilePicker
        multiple
        accept="image/*"
        maxSize={100_000}
        maxFiles={2}
        title="Images only, under 100 kB, two at a time"
        hint="Try dropping something else"
        value={files}
        onFilesChange={(next) => {
          setFiles(next);
          setRejected([]);
        }}
        onReject={setRejected}
      />

      {rejected.length > 0 ? (
        <Alert color="warning" title="Some files were turned away" onClose={() => setRejected([])}>
          {rejected.map(({ file, reason }) => `${file.name} ${WHY[reason]}`).join(' · ')}
        </Alert>
      ) : null}
    </div>
  );
}

disabled · readOnly · error

import { FilePicker } from 'neba';

const SAMPLE = [new File(['x'.repeat(24_000)], 'design-spec.pdf', { type: 'application/pdf' })];

export default function FilePickerStates() {
  return (
    <div className="grid w-full grid-cols-1 gap-4 lg:grid-cols-2">
      <FilePicker
        size="sm"
        label="Required"
        required
        error="Pick a file before saving."
        title="Nothing here yet"
      />

      <FilePicker size="sm" label="Read-only" readOnly defaultValue={SAMPLE} title="Locked" />

      <FilePicker size="sm" label="Disabled" disabled title="Unavailable" />

      <FilePicker
        size="sm"
        label="No picture, no list"
        icon={null}
        showList={false}
        defaultValue={SAMPLE}
        title="Just the sentence"
        hint="icon={null} · showList={false}"
      />
    </div>
  );
}

title · hint · icon · showList

title과 hint는 dropzone 안의 안내 문구, icon은 그 위의 글리프입니다. showList는 선택된 파일 목록을 dropzone 아래에 표시합니다. removeLabel로 개별 제거 버튼의 이름을 지정합니다.

접근성

• 상자는 <div>이고 그 안의 누를 수 있는 영역이 실제 <button>입니다. 파일 목록은 그 버튼 바깥에 있으므로 제거 버튼들이 열기 버튼 안에 중첩되지 않습니다.
• <input type="file">은 display: none 대신 화면 밖으로 보냅니다. 일부 브라우저에서 display: none은 input을 focus 불가로 만들어 required 검증 메시지를 띄울 수 없게 합니다.
• 드래그 상태는 이벤트 발생 횟수를 세어 판단하므로, 포인터가 dropzone의 자식 요소를 지날 때 깜박이지 않습니다.