--- title: Upload widget description: "Use the **Upload widget** to put a drop area on a page, so users can add many files at once and have Auclio create the objects that hold them. Its tile in the widget palette is labelled **File Upload**. ##…" url: "https://auclio.com/documentation/upload-widget/" updated: "2026-09-15" category: Widgets --- # Upload widget Use the **Upload widget** to put a drop area on a page, so users can add many files at once and have Auclio create the objects that hold them. Its tile in the widget palette is labelled **File Upload**. ## When to use it An Upload widget is for adding files in bulk, and for the objects that come with them. Use it for: - a drop area on an Invoices page, where every file becomes an invoice; - a general intake page where the person uploading chooses what each file is; - any place where users would otherwise create an object, open it, and attach a file, one at a time. Where a user adds one file to an object that already exists, use the file actions on a Table or Text Grid widget instead. See [Work with files](https://auclio.com/documentation/work-with-files/). Only data types that accept files can be used. If the widget offers you nothing, turn files on for the data type first. ## Add an Upload widget To add an Upload widget: 1. Open the page and enable **Layout edit mode**. 2. Select **Add a widget**. 3. Select the **File Upload** tile, or drag it onto the page. 4. Work through the four steps -- **Widget**, **Datasets**, **Properties**, and **Files** -- using **Next** and **Back**. 5. Select **Create**. 6. Save the page layout. Only two things are required: a **Widget Title**, and -- in fixed mode -- the **Dataset** files become. Every other setting has a default that works. Each is checked as you leave the step it is on, rather than all at the end. ## Configuration ### Widget **Widget Title** is required and shown by default; **Description** is optional and hidden by default. Both carry their own visibility controls. **Behaviour** is collapsed, with its current settings summarised on the header. It holds five settings: **Where properties are filled in** decides where the person uploading types the values the objects need. **In a review dialog** opens a dialog when they are ready; **On the file rows** puts the properties directly on the list of files, which finishes a short batch without opening anything. This is available only when the widget has a fixed dataset, because a batch whose data type is chosen per file has no single set of columns to put on the rows. **Objects per batch** decides how files become objects: - **Auto -- follow the dataset** reads the data type's own cap on files per object. One object per file, unless the data type accepts several. - **One object per file** always makes one object each. - **One object holding the whole batch** makes a single object carrying every file. **Review dialog opens as** sets the dialog's starting shape when a batch becomes several objects: **One object at a time**, a form with next and previous controls, or **A row per object**, a grid. A batch that becomes a single object is always a form. The person uploading can switch either way, so this is a default rather than a rule. **Drop area text** replaces the default *Drag & drop files here*. **Create the objects automatically** creates the batch as soon as its files have uploaded -- no **Create** button and no dialog. It needs a fixed dataset. Anything the data type requires that no default value fills still stops the batch and waits for a person, so pair this with default values on the **Properties** step. Combining it with **On the file rows** raises a warning for exactly that reason. ### Datasets **How each file's dataset is decided** offers two modes: - **Fixed -- everything becomes one dataset**, then choose the **Dataset**. This is the drop-on-the-Invoices-page case. - **User selected -- the person uploading chooses**, then optionally restrict the list with **Offer these datasets**. Left empty it offers every data type that accepts files and that the user may write to. In user-selected mode, **Suggest the dataset automatically** uses document AI to pre-select a data type for each file. The suggestion is always overridable, and a file begins uploading as soon as it has one. **Auto-classify at most** caps how many files per batch are sent for a suggestion, defaulting to 25, because each one costs an AI call. ### Properties A grid of the data type's properties, with four columns: **Property**, **Default value**, **Visible**, and **Editable**. A property left alone is asked for exactly as its data type defines it. Hide the ones the person uploading should not have to think about -- **a hidden property still receives its default value** -- and make visible-but-not-editable the ones they should see without changing. In user-selected mode there is one grid per offered data type, because their properties differ. ### Files **What the datasets allow** lists the file rules each chosen data type already enforces. It is not editable here; it is shown because those rules always apply. **Override the dataset's limits** is collapsed unless something is set, and tightens those rules for this widget only: - **Allowed file types** -- extensions separated by semicolons, for example `.pdf;.docx`. Empty means whatever each data type accepts. - **Max file size (MB)** -- per file. Leave at 0 to use the data type's limit. - **Max total size (MB)** -- everything in one upload added together. Leave at 0 for no limit. - **Max files at once** -- leave at 0 for the usual limit of 5,000 files. Where nothing constrains them, Auclio's own ceilings are **250 MB per file and 5,000 files in one batch**. **A limit here is only ever a tightening.** A stricter value is applied; a more generous one is ignored, because the data type always has the final say. Setting 50 MB here will not let a 40 MB file through a data type that caps files at 10 MB -- and a widget that appears to permit something its data type refuses is the most common confusion with this screen. ## What the person uploading sees The widget shows a drop area carrying its text and, beneath it, whichever rules are in force, written out -- *Up to 1,000 files*, *Max 20 MB per file*, *Max 200 MB in total*, *Allowed: .PDF, .DOCX*. A rule that has not been set is not mentioned. Files can be dropped or picked. While a file is being dragged over it, the area reads *Drop files here*. Uploading starts on its own; there is no separate upload step. Each file shows its own status, and the counters above the list show how the batch is going. In user-selected mode a classification bar sits above the list, with a data type selector that applies to everything or to a selection, a **Suggest automatically** action, and a running count that reads either *N still need a data type* or *All files have a data type*. Each row also has its own **Data type** cell. The actions along the bottom appear as they become relevant: **Clear**, **Cancel uploads** while an upload is running, **Review** to open the dialog and fill in what is missing, and **Create N objects**. Where an upload has stalled, **Upload N remaining** or **Retry N selected** appears. ## When part of a batch fails The objects are created by a background job, so **partial success is normal and expected**. Each object is created independently and a failure is recorded against the files it affects, with its own reason, rather than taking the batch down. The manifest is the record of what happened to each file. A file that breaks a rule never reaches storage at all: rules are checked when the upload is authorised, so its bytes are refused rather than uploaded and then rejected. The rest of the batch continues. ## Drop files anywhere on a page A page can be made a drop target in its own right, so files can be dropped without aiming at the widget. See [Pages](https://auclio.com/documentation/pages/). Dragging files over such a page raises a panel reading *Drop files here to upload*; the page's Upload widget governs the rules if one is named. ## Sizing on the grid An Upload widget is added thirty-four rows tall and about two thirds of the grid's width on a large screen, full width on a phone or small tablet. It cannot be made shorter than ten rows. Give it the height it asks for. Below the drop area sit the classification controls, a counter row, and the file list -- a list squeezed into three rows stops being a list. Unlike the Table, Text Grid, Form, and Chart widgets, an Upload widget can be placed in a page's header or footer as well as its main area. ## Recommendations When using Upload widgets: - prefer a fixed data type where the page is already about one thing -- it is simpler for the person uploading and it is what **Create the objects automatically** needs; - set default values for everything a user should not have to type, and hide those properties; - leave **Objects per batch** on **Auto** unless the data type's own file cap gives the wrong answer; - set the overrides only where this drop area genuinely needs to be stricter than its data type, and remember they cannot loosen anything; - switch **Suggest the dataset automatically** on only where files really are of mixed kinds, and keep **Auto-classify at most** low enough to be worth the calls; - tell users in the widget description what the area is for, since a drop area with no context invites anything.