File Picker

Lets a user upload one or more files via drag-and-drop or a system file chooser, with visual cues for valid and invalid drops.

Drag files here or

Select files

Any file type, up to 10 MB

Overview

File pickers enable users to upload single or multiple files through drag-and-drop interaction or traditional file browser selection. This component provides flexible upload options with clear visual feedback and file management capabilities, making it suitable for both standalone use and integration within forms. Once files are selected, they display as a list or grid of thumbnails, providing visual confirmation of the uploaded content.

Usage

forge-file-picker combines a drag-and-drop target with a slotted trigger button, controlled through accept, max-size, capture, multiple, disabled, compact, and borderless. The component only handles the picking gesture; render uploaded files yourself afterward, typically as a list with a progress indicator per file while it uploads.

Always set type="button" on the slotted trigger button — without it, clicking the trigger inside a <form> submits that form. The system file-chooser dialog also returns focus to whichever element triggered it, so don’t move focus yourself once it closes.

<forge-file-picker>
  <button slot="trigger" type="button">Select files</button>
</forge-file-picker>

Rules

Always use forge-file-picker for file and image uploads.

Always pair the drag-and-drop target with a button — it's the only way to pick files with a keyboard or screen reader.

State any file-type or size constraints in the secondary or helper-text slot so they're visible before a user tries to upload.

Show per-file upload progress and completion, and let a user remove or retry a file after it's added.

Truncate long filenames with an ellipsis instead of wrapping or overflowing.

Don't

Don't use a native <input type="file"> for uploads — use forge-file-picker instead.

Don't accept a file past the accept or max-size constraint without immediate, specific error feedback.

Don't use a full-size file picker where space is tight — use compact instead.

Don't customize the trigger button's label without keeping it a clear, actionable verb, like "Select files".

Constraints

Set accept and max-size to restrict which files can be chosen, and state the limits in the helper text so they’re visible up front.

Accept and max-size restrict which files can be chosen; helper text states the limits.

<forge-file-picker accept="image/png,image/jpeg" max-size="5000000">
  <span slot="primary">
    Drag files here or
  </span>
  <span slot="secondary">
    PNG or JPEG, up to 5 MB
  </span>
  <forge-button variant="outlined">
    Select files
  </forge-button>
  <span slot="helper-text">
    PNG or JPEG, up to 5 MB
  </span>
</forge-file-picker>

Compact

Set compact to remove the drag-and-drop target, leaving only the trigger button — useful where space is tight.

Compact removes the drag-and-drop target, leaving only the trigger button.

<forge-file-picker compact>
  <forge-button variant="outlined">
    Select files
  </forge-button>
</forge-file-picker>

Borderless

Set borderless to drop the picker’s own border, for use inside another bordered container.

Borderless drops the picker's own border, for use inside another bordered container.

<forge-file-picker borderless>
  <span slot="primary">
    Drag files here or
  </span>
  <forge-button variant="outlined">
    Select files
  </forge-button>
</forge-file-picker>

Disabled

Set disabled so the picker can’t be interacted with.

A disabled file picker can't be interacted with.

<forge-file-picker disabled>
  <span slot="primary">
    Drag files here or
  </span>
  <forge-button variant="outlined" disabled>
    Select files
  </forge-button>
</forge-file-picker>

The file picker component allows for a user to upload files of their own to the system. The component provides a slot for a button, as well as drag-and-drop functionality to launch the system file chooser dialog. There are visual cues to let the user know when files they are dragging can be dropped, as well as events that are relayed to the developer to handle files that are legal and/or illegal based on the parameters set on the component. The expectation of this component is that it will be used as a familiar element on the page that will let users upload files, while providing that visual and functional consistency.

import "@tylertech/forge/file-picker";

Properties

Property	Attribute	Type	Default	Description
`accept`	`accept`	`string \| null`	`null`	Gets/sets the allowed file types.
`maxSize`	`maxSize`	`string \| null`	`null`	Gets/sets the maximum allowed file size.
`capture`	`capture`	`string \| null`	`null`	Gets/sets the camera to use when capturing video or images.
`multiple`	`multiple`	`boolean`	`false`	Gets/sets whether multiple files are allowed.
`disabled`	`disabled`	`boolean`	`false`	Gets/sets whether the file picker is disabled.
`compact`	`compact`	`boolean`	`false`	Gets/sets whether the file picker uses the compact variant.
`borderless`	`borderless`	`boolean`	`false`	Gets and sets whether the file picker is borderless.

Events

Name	Type	Description
`forge-file-picker-change`	`CustomEvent<IFilePickerChangeEventData>`	Dispatched when a file is chosen.

CSS Parts

Name	Description
`::part(form)`	The `<form>` element at the root.
`::part(primary)`	The container element around the primary slot.
`::part(secondary)`	The container element around the secondary slot.
`::part(input)`	The `<input type="file">` element.
`::part(helper-text-container)`	The container around the helper-text slot.

CSS Custom Properties

Name	Description
`--forge-file-picker-background`	Controls the background color.
`--forge-file-picker-width`	Controls the width.
`--forge-file-picker-height`	Controls the height.
`--forge-file-picker-max-width`	Controls the maximum width.
`--forge-file-picker-border-width`	Controls the border width.
`--forge-file-picker-border-style`	Controls the border style.
`--forge-file-picker-border-color`	Controls the border color.
`--forge-file-picker-gap`	Controls gap between each element.
`--forge-file-picker-padding`	Controls the padding.
`--forge-file-picker-padding-block`	Controls the top and bottom padding.
`--forge-file-picker-padding-inline`	Controls the left and right padding.
`--forge-file-picker-disabled-opacity`	Controls the opacity value of the file picker when it's disabled.
`--forge-file-picker-highlight-background`	Controls the background color of the file picker when dragging files into the form.
`--forge-file-picker-highlight-border-color`	Controls the border color of the file picker when dragging files into the form.

Trigger button

Give the trigger button text or a label that accurately describes what it does, and set type="button" on it — without that, clicking it inside a <form> can trigger an accidental submit.

Focus after the system dialog closes

Once the native file-chooser dialog closes, focus should return to the element that triggered it, so keyboard users don’t lose their place on the page.