MUIFileUploader
MUIFileUploader is a flexible file upload component which supports:
- Single and multiple file uploads
- Drag-and-drop uploads
- Existing server-side files
- File type validation
- File size validation
- Upload count limits
- Custom upload button rendering
- Custom file item rendering
- Custom drop zone styling and behavior
Usage
import MUIFileUploader, { MUIFileUploaderProps } from '@nish1896/mui-components/mui/file-uploader';Here is a basic example of the component configured to accept a single file.
const [file, setFile] = useState<File | null>(null);
<MUIFileUploader
fieldName="resume"
value={file}
onValueChange={({ newValue, event }) => setFile(newValue)}
/>You can also pass multiple prop to allow selection of multiple files.
value is a single File, or null when empty, and a File[] when multiple
is set. Removing the last file yields null for a single-file field and []
for a multi-file field. onValueChange receives { newValue, event }, where
event is the input change, drop or remove-button click that caused the change.
The component only manages the files. It doesn't list them, so render the
selected files with renderFileItem and the server-side ones with
existingFiles and renderExistingFileItem props(see below).
A file object has the following properties:
{
lastModified: 1738870405923,
lastModifiedDate: "Fri Feb 07 2025 01:03:25 GMT+0530 (India Standard Time)",
name: "Picture.png",
size: 860146,
type: "image/png",
webkitRelativePath: ""
}When uploading files through an API, send them in a FormData object.
async function onFormSubmit(formValues: FormSchema) {
const formData = new FormData();
const { resume, pictures } = formValues;
/* resume can be null, so handle the null check */
resume && formData.append('resume', resume);
Array.isArray(pictures) && pictures.forEach(file => {
formData.append('pictures', file);
});
await sendFormData(url, formData);
}On a Node.js Express server, you can handle this incoming data with the Multer middleware.
See:
Drag and Drop
Drag-and-drop uploads are enabled by default, but can be disabled
using the disableDragAndDrop prop.
<MUIFileUploader
fieldName="documents"
disableDragAndDrop
/>Custom Drop Zone
Customize the drop zone appearance and behavior using dropZoneProps.
<MUIFileUploader
fieldName="documents"
dropZoneProps={({ isDragging, disabled, error }) => ({
sx: {
borderColor: error
? 'error.main'
: isDragging
? 'primary.main'
: 'grey.400',
opacity: disabled ? 0.5 : 1
}
})}
/>Where:
type FileUploaderDropZoneState = {
/** Whether a file is currently being dragged over the drop zone. */
isDragging: boolean;
/** Whether the uploader is disabled. */
disabled: boolean;
/** Whether the uploader is currently displaying a validation error. */
error: boolean;
};Custom Upload Button
Use renderUploadButton to provide a fully custom upload control.
<MUIFileUploader
fieldName="documents"
renderUploadButton={fileInput => (
<Button
component="label"
variant="contained"
startIcon={<UploadFileIcon />}
>
Upload Documents
{fileInput}
</Button>
)}
/>Render Uploaded File
Use renderFileItem to customize how newly uploaded files are displayed.
<MUIFileUploader
fieldName="documents"
multiple
renderFileItem={({ file, index, removeFile }) => (
<Stack
direction="row"
justifyContent="space-between"
alignItems="center"
>
<Typography>
{index + 1}. {file.name}
</Typography>
<IconButton onClick={removeFile}>
<DeleteIcon />
</IconButton>
</Stack>
)}
/>The renderer receives:
{
file: File;
index: number;
removeFile: (
event: MouseEvent<HTMLButtonElement>
) => void;
}Existing Files
Use existingFiles to display files that have already been uploaded and stored
on the server.
<MUIFileUploader
fieldName="documents"
existingFiles={[
{
name: 'contract.pdf',
url: '/uploads/contract.pdf',
size: 102400
},
{
name: 'invoice.pdf',
url: '/uploads/invoice.pdf'
}
]}
/>Existing files are rendered separately from newly uploaded files and are counted
toward the maxFiles limit.
Existing files are rendered only when renderExistingFileItem is provided. They
are not part of value, and the component never removes them, so handle
deletion in your own renderer and update existingFiles yourself.
Custom Existing File Rendering
Use renderExistingFileItem to customize how server-side files are displayed.
<MUIFileUploader
fieldName="documents"
existingFiles={[
{
name: 'contract.pdf',
url: '/uploads/contract.pdf'
}
]}
renderExistingFileItem={({ file, index }) => (
<Link
href={file.url}
target="_blank"
rel="noopener noreferrer"
>
{index + 1}. {file.name}
</Link>
)}
/>The renderer receives:
{
file: {
name: string;
url: string;
size?: number;
};
index: number;
}Neither the selected files nor the existing files are listed unless you provide
the matching renderer. Both lists are rendered below the helper text, with the
existing files first. Style their wrapper Box with existingFileListProps and
uploadedFileListProps:
<MUIFileUploader
fieldName="documents"
multiple
existingFiles={existingFiles}
renderExistingFileItem={({ file }) => <Typography>{file.name}</Typography>}
renderFileItem={({ file }) => <Typography>{file.name}</Typography>}
existingFileListProps={{ sx: { mt: 2 } }}
uploadedFileListProps={{ sx: { mt: 2, display: 'grid', gap: 1 } }}
/>Validation
MUIFileUploader can be configured to:
- Accept multiple files
- Restrict file types using
accept - Limit file size using
maxSize - Limit uploaded file count using
maxFiles - Handle upload validation errors
- Render custom upload buttons
- Render custom file items
const [files, setFiles] = useState<File[] | null>(null);
<MUIFileUploader
fieldName="pictures"
value={files}
onValueChange={({ newValue }) => setFiles(newValue)}
multiple
accept="image/*"
maxFiles={3}
maxSize={5 * 1024 * 1024}
onUploadError={(errors) => {
alert(`${errors.length} file(s) were rejected.`);
}}
/>Every incoming file, whether it is picked from the dialog or dropped, is checked on its own:
acceptis a comma-separated list of MIME types (image/png), wildcards (image/*) and extensions (.pdf). Matching ignores case, and the same list also filters the browser's file dialog. An extension is compared with the part of the name after the last dot, so.gzmatchesarchive.tar.gzbut.tar.gzdoesn't.maxSizeis in bytes, so5 * 1024 * 1024is 5 MB.maxFilescaps the total. Files fromexistingFiles, files that are already selected and the incoming batch all count towards it, and only the excess files are rejected.
Rejected files are never added to value, while the valid files from the same
batch still are. With multiple, accepted files are appended to the current
ones. Without it, a valid file replaces the current one, and a rejected file
leaves the current one in place. In that mode the selected file isn't counted by
maxFiles, since it is replaced.
Handling upload errors
onUploadError is called with one FileUploadErrorDetails entry per rejected
file: { file, errors }. errors lists the FileUploadError values that
apply, and a file can fail more than one check:
| Value | Reported when |
|---|---|
FileUploadError.sizeExceeded ('FILE_SIZE_EXCEEDED') | The file is larger than maxSize |
FileUploadError.invalidExtension ('FILE_TYPE_NOT_ALLOWED') | The file doesn't match accept |
FileUploadError.limitExceeded ('FILE_LIMIT_EXCEEDED') | The file exceeds maxFiles |
The callback isn't called when every file is accepted. Use it to set
errorMessage.
onUploadError runs just before onValueChange in the same event, and
onValueChange is still called when every file was rejected, with the unchanged
value. Clearing the message there unconditionally would remove it right after it
is set, so remember whether the batch had rejections, as in this example:
import MUIFileUploader, {
FileUploadError,
type FileUploadErrorDetails
} from '@nish1896/mui-components/mui/file-uploader';
const [uploadError, setUploadError] = useState<string[]>();
const hadRejections = useRef(false);
function handleUploadError(rejected: FileUploadErrorDetails[]) {
hadRejections.current = true;
setUploadError(rejected.map(({ file, errors }) => {
if (errors.includes(FileUploadError.sizeExceeded)) {
return `${file.name} is larger than 5 MB`;
}
if (errors.includes(FileUploadError.invalidExtension)) {
return `${file.name} is not an image`;
}
return `${file.name} was not added: too many files`;
}));
}
<MUIFileUploader
fieldName="pictures"
value={files}
onValueChange={({ newValue }) => {
setFiles(newValue);
if (!hadRejections.current) {
setUploadError(undefined);
}
hadRejections.current = false;
}}
multiple
accept="image/*"
maxFiles={3}
maxSize={5 * 1024 * 1024}
onUploadError={handleUploadError}
errorMessage={uploadError}
/>API
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
fieldName* | string | Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components. |
value | File | File[] | null | Currently selected file(s). undefined/null are treated as no files selected. |
onValueChange* | ({ newValue, event }) => void | Called with the accepted file value after every upload, removal, or clear action — File, File[], or null when cleared. |
accept | string | Comma-separated list of accepted file types, e.g. image/* or .pdf,.doc,.docx. |
multiple | boolean | When true, allows selecting multiple files. |
maxSize | number | Maximum file size (in bytes) eligible for upload. Larger files are rejected and reported through onUploadError. |
maxFiles | number | Maximum number of files that can be uploaded. Excess files are rejected and reported through onUploadError. Files in existingFiles count against the limit. |
onUploadError | (errors: FileUploadErrorDetails[]) => void | Callback fired when uploaded files fail type, size, or count validation. Receives one { file, errors } entry per rejected file, where errors lists FileUploadError enum values. Rejected files are never added to value. |
fullWidth | boolean | When true, the component expands to fill its container width.Default: false |
dropZoneProps | BoxProps | state => BoxProps | Props applied to the drag-and-drop wrapper Box. Pass an object, or a callback receiving { isDragging, disabled, error }. Ignored when disableDragAndDrop is true. |
disableDragAndDrop | boolean | Disable drag-and-drop and only allow file selection via the upload button. Default: false |
renderUploadButton | (fileInput: ReactNode) => ReactNode | Custom upload button renderer. Receives the hidden file input as children/content. |
existingFiles | ExistingUploadedFile[] | Pre-existing server-side files, displayed separately from new uploads via renderExistingFileItem. |
renderExistingFileItem | ({ file, index }) => ReactNode | Custom renderer for each file passed through existingFiles. These files are not part of value and are not removed automatically. |
renderFileItem | ({ file, index, removeFile }) => ReactNode | Custom renderer for each newly selected file. Call the provided removeFile(event) from your remove button to delete the file from the value. |
existingFileListProps | BoxProps | Props applied to the wrapper Box containing existing files. |
uploadedFileListProps | BoxProps | Props applied to the wrapper Box containing new uploads. |
inputRef | Ref<HTMLInputElement> | Ref for the hidden file <input type="file"> element, for example to open the file dialog from your own control. |
onBlur | (event: FocusEvent<HTMLInputElement>) => void | Callback fired when the hidden file <input> loses focus, which is handy for "touched" state in form libraries. |
disabled | boolean | When true, disables the field and associated controls. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | When true, renders the field label above the form field in the FormLabel component, instead of inside or beside it. Takes precedence over allLabelsAboveFields from the ConfigProvider, so false keeps the label inside this field even when the config places every label above its field. |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
errorMessage | string | string[] | Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered. |
renderError | (errors: string[]) => ReactNode | Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
helperText | ReactNode | Content displayed in the FormHelperText component below the field when there is no visible validation error. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
customIds | { field, label, helperText, error } | Overrides the default field, label, helper text, and error IDs used for accessibility. |
Playground
Driven by plain React state — a single-image uploader with accept / maxSize
and an onUploadError handler, plus a multi-file uploader with maxFiles,
fullWidth and drag-and-drop.
Source Code
View the full implementation of this component on GitHub.