# jb file input
[](https://www.webcomponents.org/element/jb-file-input)
[](https://raw.githubusercontent.com/javadbat/jb-file-input/main/LICENSE)
[](https://www.npmjs.com/package/jb-file-input)
File upload web component.
this component just let user select file and wait for you to get the value and handle it yourself and it's not handling any kind of upload or something
## When to use
Use `jb-file-input` when the user needs to choose one local file and your application will handle upload, download, storage, or preview behavior outside the component.
Use `isUploading` and `uploadPercent` only to reflect an upload flow you own elsewhere; `jb-file-input` does not upload files by itself.
## Samples
- [Codepen](https://codepen.io/javadbat/pen/xxgmWNB)
- [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--overview)
## Using With JS Frameworks
See the [React documentation](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-react-readme--docs).
Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX
## Usage
just import package with import or from js CDN and write web component tag in your html
```html
```
## API reference
### Attributes
| name | type | default | description |
| --- | --- | --- | --- |
| `name` | `string` | `""` | Form field name. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| [`required`](#validation) | `boolean` | `false` | Enables required validation. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--required) |
| [`label`](#label-message-and-error) | `string` | localized default | Placeholder label and accessible name. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--label) |
| [`message`](#label-message-and-error) | `string` | `""` | Helper text shown below the label. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--label) |
| [`error`](#label-message-and-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) |
| `accept` | `string` | common document/image types | Native file accept string forwarded to the internal file input. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| [`is-uploading`](#loading-state) | `boolean` | `false` | Visual state attribute that shows the upload progress section. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading) |
| [`hide-download`](#hide-download-button) | `boolean` | `false` | Hides the default download button in the file overlay. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--hide-download-button) |
| `disabled` | `boolean` | `false` | Disables file selection and mutation actions while keeping download available for a selected file. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--disabled) |
### Properties
| name | type | readonly | description |
| --- | --- | --- | --- |
| [`value`](#value) | `File \| null` | no | Selected file. Set to `null` to reset the component. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--initial-value) |
| `initialValue` | `File \| null` | no | Default and reset file. It initializes `value` until the live value is explicitly set. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--initial-value) |
| `isDirty` | `boolean` | yes | `true` when current `value` is not the same `File` reference as `initialValue`. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--initial-value) |
| `accept` | `string` | no | Native accept string used by the internal file input. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| [`isUploading`](#loading-state) | `boolean` | no | Shows or hides the upload progress section. |
| `isLoading` | `boolean` | yes | Computed aggregate loading state; currently mirrors `isUploading`. |
| [`uploadPercent`](#loading-state) | `number \| null` | no | Visual upload progress percentage used by the upload-state background. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading) |
| `required` | `boolean` | no | Enables required validation. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--required) |
| `label` | `string` | no | Placeholder label and accessible name. |
| `message` | `string` | no | Helper text restored after validation errors clear. |
| `error` | `string \| null` | no | External validation error; set to `null` to clear it. |
| `maxSize` | `number \| null` | no | 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) |
| `disabled` | `boolean` | no | Disables file selection, reselection, and deletion while keeping download available, and sets disabled accessibility/custom state. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--disabled) |
| `status` | `'empty' \| 'selected'` | yes | Current visual value status. |
| `selectedFileType` | `string \| null` | yes | Reserved for selected file MIME type. Current implementation returns `null`. |
| `validation` | `ValidationHelper<{ file: File \| null }>` | yes | Validation helper from `jb-validation`; set `validation.list` for custom rules. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--custom-validation) |
| `validationMessage` | `string` | yes | Current native validation message from `ElementInternals`. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods) |
### Methods
| name | returns | description |
| --- | --- | --- |
| `openFileSelector()` | `void` | Opens the native file picker unless the component is disabled. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--normal) |
| `reset()` | `void` | Restores `initialValue` and clears displayed validation. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods) |
| `checkValidity()` | `boolean` | Runs validation without showing the error state. Dispatches `invalid` when invalid. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods) |
| `reportValidity()` | `boolean` | Runs validation and shows the error state. Dispatches `invalid` when invalid. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods) |
### Events
| event | cancelable | when it fires |
| --- | --- | --- |
| `change` | no | When a file is selected or deleted. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) |
| `download` | no | When the default download button is clicked. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) |
| `delete` | no | After the selected file is cleared from the default delete button. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) |
| `invalid` | no | When `checkValidity()` or `reportValidity()` finds an invalid value. [Demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods) |
## Label, message, and error
Use `label` for the visible placeholder label and accessible name, `message` for helper text, and `error` for an external validation failure. Clearing `error` restores `message`.
```html
```
## Value
`jb-file-input` use file as default value type. means you can get value by `dom.value` and set it by `dom.value= yourFile`; the [initial value demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--initial-value) shows controlled and reset behavior.
### Reset Value
You can clear the selected file with `dom.value = null`, or restore `initialValue` with `dom.reset()` in the [imperative methods demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--imperative-methods).
## Validation
Use `required` when the user must select a file before submitting a form; see the [required validation demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--required).
```html
```
Set the `maxSize` property to a number in KB to reject larger files, or set it to `null` to remove the limit.
```js
const fileInput = document.querySelector("jb-file-input");
fileInput.maxSize = 1024;
```
For custom validation, set `validation.list` from `jb-validation`; the [custom validation demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--custom-validation) shows a file-size rule.
```js
const fileInput = document.querySelector("jb-file-input");
fileInput.validation.list = [
{
validator: ({ file }) => file && file.size < 1024 * 1024,
message: "File must be smaller than 1MB"
}
];
```
## Loading State
jb-file-input does not show any loading by default because it's just a file input and not file uploader. You can show upload state in your file uploader flow by setting the `is-uploading` attribute (or `isUploading` property) and `uploadPercent` property; see the [uploading demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--uploading).
in HTML
```html
```
or in javascript:
```ts
// show upload section
document.querySelector("jb-file-input").isUploading = true;
// set upload percent
document.querySelector("jb-file-input").uploadPercent = 10; //10% of file uploaded
```
## Download Button
when file upload is complete user access to download button and you can add your own function to download file by add event listener; the [events demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--events) exercises download and delete events:
```ts
document.querySelector("jb-file-input").addEventListener("download",()=>{
//download file however you want
})
```
download button has no default functionality because file download in every project has it's own way so we just create a ui button to enable you ad function for it.
### Hide Download Button
if you don't want download button to be shown add `hide-download` attribute to dom; see the [hidden download demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--hide-download-button):
```HTML
```
## CSS Variables
For complete styling guidance, live examples, official parts and states, and the full CSS variable reference, see the [Styling docs](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-styling--docs) and [style gallery](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-style--gallery).
## Slots
Use the supported placeholder and overlay slots in the [slots demo](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput--slots).
| slot | description |
| --- | --- |
| `placeholder` | Replaces the entire empty placeholder section. |
| `placeholder-icon` | Replaces the default upload icon inside the default placeholder. |
| `upload` | Replaces the entire upload progress section. |
| `uploader-icon` | Replaces the loading icon inside the default upload section. |
| `file-icon` | Replaces the default selected-file icon. |
| `overlay` | Replaces the entire selected-file hover overlay. |
| `overlay-content` | Replaces the content inside the default overlay. |
## CSS parts and states
The [style gallery](https://javadbat.github.io/design-system/?path=/story/components-form-elements-jbfileinput-style--gallery) shows the shared parts, states, and themes in context.
| part | description |
| --- | --- |
| `placeholder-title` | Label text in the default placeholder section. |
| `message` | Helper or validation message in the empty state. Selected-file errors use the error overlay. |
| `uploading-title` | Title text in the default upload section. |
| `loading` | Default loading element. |
| `upload-loading` | Default loading element in the upload section. |
| `progress-top-level` | Upload progress overlay whose width follows the current upload percentage. |
| `file-name` | Selected file name text. |
| `placeholder-icon` | Default placeholder SVG icon. |
| `file-icon` | Default selected-file SVG icon. |
| state or attribute | description |
| --- | --- |
| `:state(empty)` | Applied when no file is selected. |
| `:state(fill)` | Applied when a file is selected. |
| `:state(disabled)` | Applied when the file input is disabled. |
| `[is-uploading]` | Shows the upload progress section. |
| `[hide-download]` | Hides the default download button. |
```css
jb-file-input::part(file-name) {
font-weight: 600;
}
jb-file-input:state(fill) {
--jb-file-input-bg-color: var(--jb-neutral-9);
}
jb-file-input:state(disabled) {
opacity: 0.5;
}
jb-file-input[is-uploading] {
--jb-file-input-loading-bg: linear-gradient(90deg, var(--jb-primary), var(--jb-secondary));
}
```
## Related Docs
- see [`jb-file-input/react`](https://github.com/javadbat/jb-file-input/tree/main/react); if you want to use this component in react
- 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
This package includes [`custom-elements.json`](./custom-elements.json) so documentation tools, IDEs, and AI coding agents can discover the tag name, attributes, properties, events, slots, CSS parts, CSS variables, and public methods.
The package also exposes `"customElements": "custom-elements.json"` in `package.json`, which gives tools a stable package-level pointer to the manifest. This field is documented by the Custom Elements Manifest project in its [Referencing manifests from npm packages](https://github.com/webcomponents/custom-elements-manifest#referencing-manifests-from-npm-packages) section.
In `custom-elements.json`, the `exports` array describes what this module makes available:
| kind | meaning |
| --- | --- |
| `js` | A JavaScript/TypeScript export from the module, such as `JBFileInputWebComponent`. |
| `custom-element-definition` | The custom element registration for a tag name, such as `jb-file-input`. |
- Import `jb-file-input` once before using ``.
- The component only selects a file; upload and download logic must be implemented by the app.
- Read the selected file from `.value`; set `.value = null` to clear it, or call `reset()` to restore `initialValue`.
- Use `isUploading` plus `uploadPercent` to reflect external upload progress; read `isLoading` for the aggregate busy state.
- Listen to `download` when using the default download button.