# jb-file-input React component

[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/jb-file-input)
[![GitHub license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://raw.githubusercontent.com/javadbat/jb-file-input/main/LICENSE)
[![NPM Version](https://img.shields.io/npm/v/jb-file-input-react)](https://www.npmjs.com/package/jb-file-input-react)
![GitHub Created At](https://img.shields.io/github/created-at/javadbat/jb-file-input)

file upload web-component

this component is a simple react component that use [jb-file-input](https://github.com/javadbat/jb-file-input) inside and its just a simple wrapper for it so i suggest you to read jb-file-input document too, it has more complete & updated document.

## Demo
in codeSandBox: [codeSandbox preview](https://3f63dj.csb.app/samples/jb-file-input) for just see the demo and [codeSandbox editor](https://codesandbox.io/p/sandbox/jb-design-system-3f63dj?file=%2Fsrc%2Fsamples%2FJBFileInput.tsx) if you want to see and play with code

[Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--overview)

## Usage
just import the component and write jsx like this:

```jsx
import {JBFileInput} from 'jb-file-input/react';

<JBFileInput ></JBFileInput>
```

## When to use

Use `JBFileInput` when the user needs to choose one local file and your application will handle upload, download, storage, or preview behavior outside the component. See the [React wrapper demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal).

## Props

| prop | type | description |
| --- | --- | --- |
| `name` | `string` | Form field name. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| `value` | `File` | Selected file value. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--initial-value) |
| `accept` | `string` | Native accept string used by the internal file input. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| `label` | `string` | Placeholder label and accessible name. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--label) |
| `message` | `string` | Helper text shown below the label and restored after errors clear. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--label) |
| `error` | `string` | External validation error that makes the component invalid. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--external-error) |
| `required` | `boolean` | Enables required validation. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--required) |
| `maxSize` | `number \| null` | Maximum allowed file size in KB. Set to `null` to disable size validation. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--max-size-validation) |
| `validationList` | `ValidationItem<ValidationValue>[]` | Custom validation rules from `jb-validation`. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--custom-validation) |
| `isUploading` | `boolean` | Shows the upload progress section. Upload is still handled by your app. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading) |
| `uploadPercent` | `number` | Visual upload progress percentage. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading) |
| `hideDownload` | `boolean` | Hides the default download button. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--hide-download-button) |

## Events

| prop | event |
| --- | --- |
| `onChange` | `change` — see the [events demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) |

The web component also dispatches `download` and `delete` events. Use a ref and `addEventListener` if you need those from React; both are covered in the [events demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events).

## Value

`event.target.value` and `ref.current.value` are the selected `File` or `null`. Set the underlying value to `null` to clear it, or call `ref.current.reset()` to restore `initialValue`; see the [value and reset demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods).

```jsx
const fileInputRef = useRef(null);

<JBFileInput
  ref={fileInputRef}
  onChange={(event) => console.log(event.target.value)}
/>;

fileInputRef.current?.reset();
```

## Validation

Use `required` when the user must select a file. Use `error` for an external validation failure and `validationList` for custom checks such as MIME type.

Use `maxSize` for the built-in file-size check. The value is in KB.

```jsx
<JBFileInput maxSize={1024} />
```

```jsx
const validationList = [
  {
    validator: ({ file }) => !file || file.size < 1024 * 1024,
    message: 'File must be smaller than 1MB',
  },
];

<JBFileInput required validationList={validationList} />;
```

## Loading State

`JBFileInput` does not upload files by itself. Use `isUploading` and `uploadPercent` to display progress from an upload flow owned by your app; see the [loading-state demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading).

```jsx
<JBFileInput isUploading uploadPercent={45} />
```

## Download Button

The default download button has no built-in download logic. Listen for the underlying `download` event with a ref when you use the default overlay button; the [events demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) shows the event flow.

```jsx
useEffect(() => {
  const input = fileInputRef.current;
  if (!input) return;

  const onDownload = () => downloadFile(input.value);
  input.addEventListener('download', onDownload);
  return () => input.removeEventListener('download', onDownload);
}, []);
```

Use `hideDownload` to hide the default button in the [hidden download demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--hide-download-button).

```jsx
<JBFileInput hideDownload />
```

## Slots

Pass custom slot content as JSX children as shown in the [slots demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--slots).

Pass custom slot content as JSX children. Supported slot names include `placeholder`, `placeholder-icon`, `upload`, `uploader-icon`, `file-icon`, `overlay`, and `overlay-content`.

```jsx
<JBFileInput>
  <div slot="placeholder">Drop or select a file</div>
</JBFileInput>
```

## CSS parts and states

The React wrapper uses the same parts, states, attributes, and CSS variables as the web component, including `::part(file-name)`, `::part(progress-top-level)`, `:state(empty)`, `:state(fill)`, `[is-uploading]`, and `[hide-download]`. The `progress-top-level` part exposes the upload progress overlay whose width follows `uploadPercent`. See the shared [style gallery](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-style--gallery).

```css
.contract-file::part(file-name) {
  font-weight: 600;
}

.contract-file[is-uploading] {
  --jb-file-input-loading-bg: linear-gradient(90deg, #2563eb, #14b8a6);
}
```

## Shared Documentation

For web-component behavior, events, slots, and CSS variables, see [`jb-file-input`](../README.md) and the [shared documentation](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-readme--docs).

## Related Docs
- see [jb-file-input](https://github.com/javadbat/jb-file-input) if you want to use this component as a web-component

- see [All JB Design system Component List](https://javadbat.github.io/design-system/) for more components

- use [Contribution Guide](https://github.com/javadbat/design-system/blob/main/docs/contribution-guide.md) if you want to contribute in this component.

## AI agent notes

- Import `JBFileInput` from `jb-file-input/react`; the wrapper imports and registers the underlying `jb-file-input` web component.
- The component only selects a file; upload and download logic must be implemented by the app.
- Use `isUploading` and `uploadPercent` to reflect external upload progress.
- Use `label`, `message`, `error`, `accept`, and `hideDownload` in React; the wrapper maps them to the underlying web-component API.
- Use a ref for imperative methods such as `openFileSelector()`, `reset()`, `checkValidity()`, and `reportValidity()`.