# FileInput

- Page: https://jiguang132.com/resources/astryx/docs/file-input
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## File Input

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.

| 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt