FileInput

FileInput provides file upload with optional drag-and-drop support. Use it for single or multiple file selection with built-in validation for file type, size, and count. Pair with validation status for upload feedback.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

File Input

Prop	Type	Default	Description
label *	string		Accessible label for the file input.
value *	File \| File[] \| null		Currently selected file(s). Controlled component.
onChange *	(files: File \| File[] \| null) => void		Callback fired when files are selected or removed.
changeAction	(files: File \| File[] \| null) => Promise<void>		Async change action (React 19 transitions pattern). Use for immediate upload on file selection.
accept	string		Accepted file types. Uses the HTML accept attribute format (e.g. "image/*", ".pdf,.doc").
isMultiple	boolean	false	Whether multiple files can be selected. When true, value and onChange use File[] instead of File.
maxSize	number		Maximum file size in bytes. Files exceeding this are rejected with an error status.
maxFiles	number		Maximum number of files (only applies when isMultiple is true).
isLabelHidden	boolean	false	Visually hides the label while keeping it accessible to screen readers.
description	string		Description text displayed between the label and input.
isOptional	boolean	false	Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.
isRequired	boolean	false	Displays a "Required" indicator next to the label and adds a screen-reader-only "Required" description to the trigger (assistive tech does not reliably announce aria-required on the trigger). Mutually exclusive with isOptional.
isDisabled	boolean	false	Disables the input, preventing interaction and dimming the element.
disabledMessage	string		Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (opening the file picker stays blocked). Use this instead of wrapping a disabled FileInput in Tooltip; disabled controls swallow the hover events an external Tooltip needs.
isLoading	boolean	false	Puts the input in a loading state, showing a spinner and setting aria-busy.
placeholder	string	"Choose file" or "Choose files"	Placeholder text shown when no file is selected.
mode	'input' \| 'dropzone'	'input'	Visual mode. 'input' is a compact inline style; 'dropzone' is a larger area with drag-and-drop support.
status	{type: 'error' \| 'warning' \| 'success', message?: string}		Validation status: applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.
statusVariant	'attached' \| 'detached' \| 'tooltip'	'attached'	How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.
labelTooltip	string		Tooltip text displayed in an info icon at the end of the label.
width	SizeValue		Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
containerXstyle	StyleXStyles		StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.
containerClassName	string		Class name for the field container. Same targeting as `containerXstyle`.
containerStyle	CSSProperties		Inline styles for the field container. Same targeting as `containerXstyle`.
controlXstyle	StyleXStyles		StyleX styles for the visual control box: the element that paints the border and background and holds icons and end controls. Never the native input.
controlClassName	string		Class name for the visual control box.
controlStyle	CSSProperties		Inline styles for the visual control box.

Usage guidance

Always specify an accept prop to guide users toward valid file types.
Use maxSize and maxFiles to prevent oversized uploads; the component handles validation and error display automatically.
Add a description to communicate constraints like file size limits or accepted formats.
Use changeAction for immediate upload workflows that benefit from optimistic UI.
Avoid: Don't use FileInput for directory or folder uploads; that is not supported in v1.
Avoid: Don't avoid dropzone mode unless space is constrained; drag-and-drop is the expected interaction for file uploads.
Avoid: Don't wrap a disabled FileInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-file-input",
      "visualProps": [
        "mode",
        "status"
      ]
    },
    {
      "className": "astryx-file-input-icon",
      "visualProps": [
        "mode"
      ]
    }
  ]
}

Anatomy

Label: Text that identifies the field. Always rendered for accessibility even when visually hidden.
Description: Helper text between the label and the drop zone explaining accepted formats or size limits.
Drop zone: The clickable area for file selection. In dropzone mode, also accepts dragged files.
Upload icon: An upload-to-tray icon in the drop zone hinting at the upload action.
Placeholder: Hint text shown when no files are selected.
File name display: Shows the name(s) of selected files.
Clear button: A close button that removes selected files and returns focus to the input.
Spinner: Loading indicator that appears during async upload actions.
Status message: Validation feedback showing error, warning, or success with a message.

Examples

File Input:
FileInput — Basic: A controlled single-file upload with accepted types, a size limit, and helper text. Use for standard document upload fields in forms.