Component

FilePicker

파일 chooser 정책과 트리거 모양을 분리하는 얇은 primitive입니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

허용 확장자 또는 MIME type · 비우면 모든 형식

파일당 최대 MB · 비우면 제한 없음

최대 파일 개수 · 비우면 제한 없음

Code

import { useState } from 'react'

import { FilePicker, Button } from '@amineslab/ui'

function optionalLimit(value: string) {
    return value.trim() && Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : undefined;
}

type FileDemoConstraints = {
    accept?: string;
    maxSize?: string;
    maxFiles?: string;
};

function FilePickerExample({ disabled = false, multiple, accept = '.jpg,.png,.pdf', maxSize = '10', maxFiles = '4', }: FileDemoConstraints & {
    disabled?: boolean;
    multiple: boolean;
}) {
    const [error, setError] = useState('');
    return (<div className="grid gap-2">
      <FilePicker disabled={disabled} accept={accept} maxSize={optionalLimit(maxSize)} maxFiles={optionalLimit(maxFiles)} multiple={multiple} onSelect={() => undefined} onError={(errors) => setError(errors[0]?.message ?? '')}>
        <Button type="button" variant="outline">
          파일 선택
        </Button>
      </FilePicker>
      {error && (<p role="alert" className="m-0 text-body-3 text-danger-700">
          {error}
        </p>)}
    </div>);
}

export default function ExamplePreview() {
  return (<FilePickerExample {...({"disabled":false,"accept":".jpg,.png,.pdf","maxSize":"10","maxFiles":"4","multiple":false} as const)}/>)
}

Props

@amineslab/ui에서 FilePicker를 가져옵니다.

import { FilePicker } from '@amineslab/ui'

`FilePicker`

native input을 자식 트리거에 연결합니다.

Name	Type	Default	Description
`children*`	`ReactElement`	-	클릭 가능한 단일 트리거입니다.
`onSelect*`	`(files: File[]) => void`	-	검증을 통과한 파일을 전달합니다.
`accept`	`string`	-	허용 확장자 또는 MIME type입니다. 선택 결과도 검증합니다.
`maxSize`	`number`	-	파일당 최대 용량(MB)입니다. 생략하면 제한하지 않습니다.
`maxFiles`	`number`	-	한 번에 선택 가능한 최대 파일 개수입니다.
`onError`	`(errors: FileError[]) => void`	-	형식·용량·개수 제한 오류를 전달합니다.
`multiple`	`boolean`	`false`	여러 파일을 선택합니다.
`disabled`	`boolean`	`false`	트리거와 chooser를 비활성화합니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

트리거와 정책 분리

트리거의 모양은 Button이, native chooser와 accept 정책은 FilePicker가 담당합니다.

import { useState } from 'react'

import { FilePicker, Button } from '@amineslab/ui'

function optionalLimit(value: string) {
    return value.trim() && Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : undefined;
}

type FileDemoConstraints = {
    accept?: string;
    maxSize?: string;
    maxFiles?: string;
};

function FilePickerExample({ disabled = false, multiple, accept = '.jpg,.png,.pdf', maxSize = '10', maxFiles = '4', }: FileDemoConstraints & {
    disabled?: boolean;
    multiple: boolean;
}) {
    const [error, setError] = useState('');
    return (<div className="grid gap-2">
      <FilePicker disabled={disabled} accept={accept} maxSize={optionalLimit(maxSize)} maxFiles={optionalLimit(maxFiles)} multiple={multiple} onSelect={() => undefined} onError={(errors) => setError(errors[0]?.message ?? '')}>
        <Button type="button" variant="outline">
          파일 선택
        </Button>
      </FilePicker>
      {error && (<p role="alert" className="m-0 text-body-3 text-danger-700">
          {error}
        </p>)}
    </div>);
}

export default function ExamplePreview() {
  return (<FilePickerExample multiple={false}/>)
}

사용 기준

권장하는 사용

Button·IconButton 등 접근 가능한 자식을 주고, 형식·용량·개수 검증은 FilePicker가 수행합니다.
선택 결과는 onSelect로 전달하며 자식 버튼의 외형과 문구는 그대로 유지합니다.
업로드는 호출부가 소유합니다.

피해야 할 사용

겉모양만으로 사용을 결정하지 마세요.
의미와 키보드 동작, 모바일에서의 흐름을 함께 확인하세요.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

Enter / Space: Slot으로 연결된 자식 트리거의 native 동작으로 chooser를 엽니다.