FileField lets people choose files from their device, either through a button or a drag-and-drop area.
Importing
The component can be imported via:
Usage
FileField lets people choose files from their device. By default it renders a
single button (type="button") that opens the native file picker. Selected
files are reported through the required onFileSelected callback, which
receives the first selected file plus the full list of selected files.
Reacting to a selection
onFileSelected is called every time a file is chosen — through the picker or
by dropping onto a dropzone. The input resets itself after each selection, so
choosing the same file twice still fires the callback.
Dropzone
Set type="dropzone" to render a drag-and-drop area instead of a button.
People can drop files anywhere in the area or click browse to open the
picker. The drop target highlights while a file is dragged over it.
Restricting file types
Pass a comma-separated list of MIME types to accept (the same value the native
<input type="file"> accepts). In dropzone mode, dragging an unsupported file
shows an "Invalid file type" message listing the accepted types, and dropping it
is ignored.
Multiple files
Set allowMultiple to let people choose more than one file at a time. The full
list is passed as the second argument to onFileSelected.
Loading state
Set isLoading while an upload is in progress. In button mode the button shows
a spinner; in dropzone mode the area is replaced with a loading indicator.
Previewing a selected image
In dropzone mode, pass selectedImageUrl to preview an already-selected image.
The dropzone then shows the image alongside Replace and Delete controls.
Use onFileDeleted to handle the delete action.
Label, description, and errors
FileField is built on the same form primitives as the other field components,
so it accepts label, description, error, and isInvalid. When you don't
provide a visible label, supply an ariaLabel (or ariaLabelledby) so the
control still has an accessible name.
Disabled
Set isDisabled to prevent interaction. The button, dropzone, and any
Replace / Delete controls are all disabled.
API
PlumaFileField extends Box
Default:'*'
A comma-separated list of accepted MIME types (e.g. 'image/png,image/jpeg').
Matches the native <input type="file"> accept attribute.
Default:false
Whether multiple files can be selected at once.
Element (or elements) that describe the form field. Also used for error messages, as aria-errormessage isn't supported in all assistive technologies: https://a11ysupport.io/tech/aria/aria-errormessage_attribute
String value that labels the form field.
Element (or elements) that label the form field.
Default:'Choose file'
In button mode, the text of the button that opens the file picker.
Default:secondary
In button mode, the visual style variant of the button.
Additional classes to be applied to the top-level container. This is necessary as an argument in Ember, where we apply splattributes on the input itself, which means we can't pass a custom class to the containing element the classic way.
A description for the field, providing additional context or hints.
An error message associated with the form field.
Boolean: Ember-only. If the error named block is used,
this prop can be set to true to indicate an error is present,
which will make the error block render.
An optional id to be assigned to the input element. Also used to generate ids for labels and error messages. If one isn't provided, it will be generated.
Whether the form field is disabled.
Whether the form field is in an invalid state.
Default:false
Whether the component should render in a loading state (e.g. while a file is uploading). In dropzone mode, replaces the contents with a spinner.
The label text to show with the form field.
The name attribute is used for HTML forms
In dropzone mode with a selectedImageUrl, called when the "Delete"
control is clicked.
Called when one or more files are selected (via the picker or by dropping). Receives the first selected file, plus the full list of selected files.
In dropzone mode, the URL of an already-selected image to preview. When set, the dropzone shows the image with "Replace" and "Delete" controls.
Whether to allow browser autofill and password managers. When false (default), adds attributes to disable password managers (1Password, LastPass, Bitwarden, Dashlane). Set to true for fields where autofill is desired (e.g., email, password, address fields).
Whether the generated description id should be included in the input's aria-describedby attribute.
Disable this when a label`` tag surrounds the input as well as it's description text, for example in an OptionCard` component.
Whether the generated label id should be included in the input's aria-labelledby attribute.
Disable this when the label tag surrounds the input as well as it's label text,
for example in an OptionCard component.
By default, form elements will throw an error if no label or aria-label is provided. Disable this to suppress the error, for example when building a custom form element, and you want to handle labeling yourself.
Default:'button'
The presentation of the file input. 'button' renders a single button
that opens the file picker; 'dropzone' renders a drag-and-drop area.
Additional classes to be applied to the description element.
Additional classes to be applied to the error element.
Additional classes to be applied to the field node.
Ember-only: this is used internally to detect whether a label
named block is present, and to ignore empty label props if so.
Additional classes to be applied to the input node.
Sets the size attribute on the input element. This controls the visible width of the input in characters.
Whether the component should render with "legacy" styles.
Additional classes to be applied to the label node.
Whether to apply the center-baseline variant.