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
• Demo

Using With JS Frameworks

See the React documentation.

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

<script>
  import 'jb-file-input'
</script>

<jb-file-input></jb-file-input>

API reference

Attributes

| name | type | default | description | | --- | --- | --- | --- | | name | string | "" | Form field name. Demo | | required | boolean | false | Enables required validation. Demo | | label | string | localized default | Placeholder label and accessible name. Demo | | message | string | "" | Helper text shown below the label. Demo | | error | string | "" | External validation error that makes the component invalid. Demo | | accept | string | common document/image types | Native file accept string forwarded to the internal file input. Demo | | is-uploading | boolean | false | Visual state attribute that shows the upload progress section. Demo | | hide-download | boolean | false | Hides the default download button in the file overlay. Demo | | disabled | boolean | false | Disables file selection and mutation actions while keeping download available for a selected file. Demo |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | File \| null | no | Selected file. Set to null to reset the component. Demo | | initialValue | File \| null | no | Default and reset file. It initializes value until the live value is explicitly set. Demo | | isDirty | boolean | yes | true when current value is not the same File reference as initialValue. Demo | | accept | string | no | Native accept string used by the internal file input. Demo | | isUploading | boolean | no | Shows or hides the upload progress section. | | isLoading | boolean | yes | Computed aggregate loading state; currently mirrors isUploading. | | uploadPercent | number \| null | no | Visual upload progress percentage used by the upload-state background. Demo | | required | boolean | no | Enables required validation. Demo | | 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 | | disabled | boolean | no | Disables file selection, reselection, and deletion while keeping download available, and sets disabled accessibility/custom state. Demo | | 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 | | validationMessage | string | yes | Current native validation message from ElementInternals. Demo |

Methods

| name | returns | description | | --- | --- | --- | | openFileSelector() | void | Opens the native file picker unless the component is disabled. Demo | | reset() | void | Restores initialValue and clears displayed validation. Demo | | checkValidity() | boolean | Runs validation without showing the error state. Dispatches invalid when invalid. Demo | | reportValidity() | boolean | Runs validation and shows the error state. Dispatches invalid when invalid. Demo |

Events

| event | cancelable | when it fires | | --- | --- | --- | | change | no | When a file is selected or deleted. Demo | | download | no | When the default download button is clicked. Demo | | delete | no | After the selected file is cleared from the default delete button. Demo | | invalid | no | When checkValidity() or reportValidity() finds an invalid value. Demo |

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.

<jb-file-input label="Contract" message="PDF files up to 1 MB"></jb-file-input>
<jb-file-input label="Contract" error="The selected file is not allowed"></jb-file-input>

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 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.

Validation

Use required when the user must select a file before submitting a form; see the required validation demo.

<jb-file-input required></jb-file-input>

Set the maxSize property to a number in KB to reject larger files, or set it to null to remove the limit.

const fileInput = document.querySelector("jb-file-input");
fileInput.maxSize = 1024;

For custom validation, set validation.list from jb-validation; the custom validation demo shows a file-size rule.

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.

in HTML

<jb-file-input is-uploading>

or in javascript:

// 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 exercises download and delete events:

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:

<jb-file-input hide-download></jb-file-input>

CSS Variables

For complete styling guidance, live examples, official parts and states, and the full CSS variable reference, see the Styling docs and style gallery.

Slots

Use the supported placeholder and overlay slots in the slots demo.

| 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 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. |

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; if you want to use this component in react

• see All JB Design system Component List for more components

• use Contribution Guide if you want to contribute in this component.

AI agent notes

This package includes 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 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 <jb-file-input>.
• 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.