EnInputFileDrop
Usage
EnInputFileDrop is a drop zone for picking files: the user drags files onto it, or chooses browse to open the file picker. It renders a cloud-upload icon, the prompt "Drag your files here or browse.", and, when accept names the allowed extensions, a Supported line listing them (accept="pdf,docx,csv" reads "Supported: PDF, DOCX, CSV"). Selected files are listed under the drop zone, each with a remove icon; the prompt stays, so the user can see how to add or replace a file.
It is a full EnForm field: name, rules, required, locked and critical all apply, and limit, maxFileSizeMb and maxTotalSizeMb guard the count and size. compact gives a single-row layout for use inline with other controls.
Preview
Props
| Name | Description | Default | Control |
|---|---|---|---|
| compact | Renders a compact single-row layout suited for use alongside other form controls. boolean | false | |
| icon | Icon class to display in the drop zone. string | "icon-af-cloud-upload" | |
| accept | Comma-separated list of allowed file extensions (without dots). string | "*" | |
| limit | Maximum number of files allowed. number | 1 | |
| maxFileSizeMb | Maximum size of any one file in MB. 0 means no limit. Sugar for the number | 0 | |
| maxTotalSizeMb | Maximum combined size of all files in MB. 0 means no limit. Sugar for the number | 0 | |
| showSupportedTypes | Whether to display the supported file types derived from the accept prop. boolean | true | |
| value | Used for a raw value passed into the input. string | number | unknown | |
| name | Sets name attribute for the input. Required for proper form handling. string | null | |
| id | Sets id attribute for input. If left blank, it will default to the string | null | |
| placeholder | Sets the placeholder value. string | null | |
| label | Used to describe field in error message string | null | |
| disabled | Sets the disabled attribute. boolean | null | |
| required | Sets the field to required. boolean | false | |
| critical | Flags the field as critical. Critical is not required: a required field blocks saving, while a critical field saves fine empty but blocks something later, such as activating or completing a record. Use it for "you will need this before you can finish", not "you must enter this now". While the field is empty, the control takes the boolean | false | |
| locked | Locks the field: disables the control and marks it with a lock icon. Text-like controls show the
lock inside the input, in the spot a select keeps its arrow. Option groups, booleans and file
inputs have no box to put it in, so they show it beside the label of a surrounding boolean | false | |
| lockedMessage | Why the field is locked, for example "Locked while payroll is open". Shown as a tooltip when the
pointer rests on the locked control, and on the lock icon beside the label, which becomes
focusable so keyboard users can reach the text (the disabled control itself cannot take focus).
Rendered through en-components' string | "" | |
| typeCast | Used to specifically validate different types. string | "string" | |
| mode | Sets when and how often validation occurs. TODO: create docs for modes string | "eager" | |
| displayOnly | Displays the value of the field in a span element, instead of as an input. boolean | false | |
| emptyValue | What a string | boolean | false | |
| rules | A pipe separated string of validation rules for the field. View validation rules string | "" | |
| renderInForm | Prevents a field from being rendered at all when used in the boolean | Function | true | |
| renderInTable | Prevents a field from generating a column/heading in the boolean | Function | true | |
| customMessages | Provide a custom error messages by rule. Should be an object with keys that match the rule name and value being a string of the message to display. Record<string, any> | null |
Slots
default
No description
Events
change
No description
input
No description
error
No description
Methods
No methods defined.
Guidelines
Keep the built-in prompt
The default slot replaces the prompt, so a document import can say "Drag your PDF, Word, CSV, or Excel documents here or browse." Don't. accept already produces the Supported line, so a prompt that names the file types says them twice, and the two lists drift apart the first time accept changes. Leave the prompt alone and let accept state the types.
Replace the prompt only when the zone has to say what the file is for ("Drop the carrier's invoice here") and nothing above it does. Keep the <span class="en-file-drop-browse">browse</span> in the replacement; that span is what makes "browse" look like a link.
What the field says on its own
The drop zone writes its own error message for what it checks as files arrive. These are not validation rules, so customMessages does not change them:
| When | Message |
|---|---|
A file's extension is not in accept | "These files are not a supported type: file names" |
More files arrive than limit allows | "File limit (n) has been reached." |
| A single-slot field would be replaced by a file over the size cap | "file name exceeds the size limit and was not added." |
customMessages covers the validation rules that run afterward: required, size, total_size and anything in rules. The two size messages already restate the cap in MB when it came from maxFileSizeMb or maxTotalSizeMb.
A spec or mockup should quote the messages above rather than write its own. The copy belongs to the component, so every upload in the product reads the same way.
One file at a time
With the default limit of 1 the drop zone behaves like a bare file input:
- A new pick replaces the current file. The user does not have to remove it first.
- Dropping several files at once keeps the first and shows the limit message.
- A file of the wrong type is rejected and the file already selected stays.
Dos
- Set
accept. It filters the file picker and produces the Supported line. - Use it, with its defaults, for every document import: carrier documents, invoices, census and import files. One drop zone, one prompt, one set of messages across the product.
- Put the instruction ("Upload the carrier's information:") in the field's label or the text above the zone, not in the prompt.
- Use
compactwhen the zone sits in a row with other controls.
Don'ts
- Don't hand-build a drag-and-drop zone. The component already handles the drag states, the hidden file input, keyboard activation and the error messages.
- Don't restate the file types in the prompt, and don't turn off
showSupportedTypesunless the types are listed somewhere else the user can see. - Don't write new copy for the messages in the table above. Quote them.