@nish1896/rhf-mui-components/mui/file-uploader/index.d.ts

A suite of 25+ production-ready react-hook-form components built with material-ui. Fully typed, tree-shakable, and optimized for enterprise-grade forms.

import { CustomComponentIds, CustomOnChangeProps } from "../../types/common.js";
import { FormHelperTextProps, FormLabelProps } from "../../types/mui.js";
import { ChangeEvent, DragEvent, JSX, MouseEvent, ReactNode, Ref } from "react";
import { Control, FieldValues, Path, RegisterOptions } from "react-hook-form";
import { BoxProps } from "@mui/material/Box";

//#region src/mui/file-uploader/index.d.ts
declare enum FileUploadError {
  sizeExceeded = "FILE_SIZE_EXCEEDED",
  invalidExtension = "FILE_TYPE_NOT_ALLOWED",
  limitExceeded = "FILE_LIMIT_EXCEEDED"
}
type FileUploadErrorDetails = {
  /** File that failed upload validation. */file: File; /** Validation errors reported for the file. */
  errors: FileUploadError[];
};
/**
 * Metadata for a file that has already been uploaded and is being
 * passed as initial value for the field in the file uploader component.
 */
type ExistingUploadedFile = {
  /** Displayed file name. */name: string; /** URL used as the href on the file name link. */
  url: string; /** Optional file size in bytes. */
  size?: number;
};
type RHFFileUploaderOnValueChangeProps = {
  /** New form value after a successful upload, removal, or clear action. */newValue: File | File[] | null; /** Event that triggered the value change. */
  event: ChangeEvent<HTMLInputElement> | DragEvent<HTMLDivElement> | MouseEvent<HTMLButtonElement>;
};
/**
 * State passed to `dropZoneProps` when it is provided as a callback.
 */
type RHFFileUploaderDropZoneState = {
  /** 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;
};
type RHFFileUploaderDropZoneProps = Omit<BoxProps, 'children'> | (({
  isDragging,
  disabled,
  error
}: RHFFileUploaderDropZoneState) => Omit<BoxProps, 'children'>);
type RenderExistingFileItemProps = {
  file: ExistingUploadedFile; /** Zero-based index of the existing file. */
  index: number;
};
type RenderFileItemProps = {
  file: File; /** Zero-based index of the newly selected file. */
  index: number; /** Removes this newly selected file from the RHF field value. */
  removeFile: (event: MouseEvent<HTMLButtonElement>) => void;
};
type RHFFileUploaderProps<T extends FieldValues> = {
  /**
   * Name/path of the React Hook Form field this component controls.
   */
  fieldName: Path<T>;
  /**
   * React Hook Form control object returned by `useForm`.
   */
  control: Control<T>;
  /**
   * Validation rules passed to React Hook Form for this field.
   */
  registerOptions?: RegisterOptions<T, Path<T>>;
  /**
   * When true, marks the field as required in the UI and accessibility attributes.
   */
  required?: boolean;
  /**
   * Comma-separated list of accepted file types.
   *
   * Examples:
   * - `image/*`
   * - `.pdf,.doc,.docx`
   * - `image/png,image/jpeg`
   */
  accept?: string;
  /**
   * When true, allows selecting multiple files.
   */
  multiple?: boolean;
  /**
   * Maximum file size (in bytes) eligible for upload.
   * Files exceeding this size will be rejected and trigger an error callback.
   *
   * For example, to set a maximum file size of 5 MB:
   * `maxSize={5 * 1024 * 1024}`
   */
  maxSize?: number;
  /**
   * Maximum number of files that can be uploaded.
   *
   * When the limit is exceeded, additional files are rejected and
   * reported through the error callback.
   */
  maxFiles?: number;
  /**
   * Disables the file input and prevents file selection.
   *
   * @default false
   */
  disabled?: boolean;
  /**
   * Props applied to the drag-and-drop wrapper `Box`.
   *
   * Pass an object for static props, or a callback to style/render from the current
   * drop-zone state. The returned `sx` is merged after the default drop-zone styles,
   * and drag/drop handlers are composed with the internal handlers.
   *
   * This prop is ignored when `disableDragAndDrop` is `true`.
   */
  dropZoneProps?: RHFFileUploaderDropZoneProps;
  /**
   * Disable drag-and-drop functionality and only allow file selection via the upload button.
   * @default false
   */
  disableDragAndDrop?: boolean;
  /**
   * Custom upload button renderer. Receives the hidden file input as children/content.
   */
  renderUploadButton?: (fileInput: ReactNode) => ReactNode;
  /**
   * Pre-existing server-side files.
   *
   * Use `renderExistingFileItem` to render these files in the file list.
   * Existing files are displayed separately from newly uploaded files, and
   * their count is deducted from `maxFiles` during validation.
   */
  existingFiles?: ExistingUploadedFile[];
  /**
   * Custom renderer for each file passed through `existingFiles`.
   *
   * Use this to render server-side files that were uploaded before the
   * current form session. The callback receives the file metadata and its
   * zero-based index.
   *
   * Existing files are not stored in the RHF field value and this component
   * does not remove them automatically. Handle deletion in your own renderer
   * if server-side files need to be removed.
   *
   * When omitted, existing files are not rendered.
   */
  renderExistingFileItem?: ({
    file,
    index
  }: RenderExistingFileItemProps) => ReactNode;
  /**
   * Props applied to the wrapper Box that contains pre-existing server-side files.
   */
  existingFileListProps?: Omit<BoxProps, 'children'>;
  /**
   * Props applied to the wrapper Box that contains newly selected/uploaded files.
   */
  uploadedFileListProps?: Omit<BoxProps, 'children'>;
  /**
   * Custom renderer for each newly selected file stored in the RHF field value.
   *
   * The callback receives the `File`, its zero-based index, and a `removeFile`
   * helper. Call `removeFile(event)` from your remove/delete button to remove
   * that file from the RHF value. Removal also triggers `onValueChange` unless
   * `customOnChange` is provided.
   *
   * When omitted, newly selected files are not rendered.
   */
  renderFileItem?: ({
    file,
    index,
    removeFile
  }: RenderFileItemProps) => ReactNode;
  /**
   * Overrides the default file uploader change handling.
   * Receives the accepted file value and the input/drop event that produced it.
   * Call `rhfOnChange` with the `File`, `File[]`, or `null` value that should be stored; else the form value will not be updated.
   *
   * @param rhfOnChange - React Hook Form field change handler for the uploaded file value.
   * @param newValue - Accepted file, accepted file array, or `null` when cleared.
   * @param event - Input or drop event that changed the file value.
   */
  customOnChange?: ({
    rhfOnChange,
    newValue,
    event
  }: CustomOnChangeProps<RHFFileUploaderOnValueChangeProps, File | File[] | null>) => void;
  /**
   * Called after the default file uploader handler stores the accepted file value in React Hook Form.
   *
   * ⚠️ Important:
   * This callback is not called when `customOnChange` is used.
   *
   * @param newValue - Accepted file, accepted file array, or `null` when cleared.
   * @param event - Input or drop event that changed the file value.
   */
  onValueChange?: ({
    newValue,
    event
  }: RHFFileUploaderOnValueChangeProps) => void;
  /**
   * Callback fired when uploaded files fail type, size, or count validation.
   */
  onUploadError?: (errors: FileUploadErrorDetails[]) => void;
  /**
   * Label content shown for the field. Defaults to a label generated from `fieldName`.
   */
  label?: ReactNode;
  /**
   * When true, renders the field label above the form field instead of inside or beside it.
   */
  showLabelAboveFormField?: boolean;
  /**
   * Props forwarded to the internal `FormLabel`. The `id` is managed by the component.
   */
  formLabelProps?: Omit<FormLabelProps, 'id'>;
  /**
   * When true, hides the rendered field label while preserving accessible labeling where possible.
   */
  hideLabel?: boolean;
  /**
   * Helper text shown below the field when there is no visible validation error.
   */
  helperText?: ReactNode;
  /**
   * If true, hides the error message text while keeping the field in an error state.
   */
  hideErrorMessage?: boolean;
  /**
   * Props forwarded to the internal `FormHelperText`. The `id` is managed by the component.
   */
  formHelperTextProps?: Omit<FormHelperTextProps, 'id'>;
  /**
   * When true, the component expands to fill its container width.
   */
  fullWidth?: boolean;
  /**
   * Custom ids for generated field, label, helper text, and error elements.
   */
  customIds?: CustomComponentIds;
};
declare const RHFFileUploader: <T extends FieldValues>(props: RHFFileUploaderProps<T> & {
  ref?: Ref<HTMLInputElement>;
}) => JSX.Element;
//#endregion
export { ExistingUploadedFile, FileUploadError, FileUploadErrorDetails, RHFFileUploaderProps, RHFFileUploader as default };