# File Input

Choose files in a field that shows their names and ends with an Upload button, and send them with a form.

Company logo file input

[Complete TSX file](/examples/file-input/default.tsx)

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { FileInput } from "@/siteplane/components/file-input";

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Company logo</FieldLabel>
      <FileInput accept="image/svg+xml,image/png,image/jpeg" />
      <FieldDescription>SVG, PNG or JPG, up to 2 MB.</FieldDescription>
    </Field>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/file-input
```

With npm: `npx shadcn@4.18.0 add @siteplane/file-input`. [Registry JSON](/registry/file-input.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/form
```

Field is installed with Input.

## Usage

```tsx
import { FileInput } from "@/siteplane/components/file-input";

<FileInput accept="image/png,image/svg+xml" aria-label="Company logo" />;
```

## Choosing files

The field shows “Choose a file” until a file is chosen, then the file’s name, and the names of several files separated by commas. A click anywhere on the field opens the file dialog. Tab reaches the field’s text and the Upload button, and Enter or Space on either opens the dialog too. Names that are longer than the field end with an ellipsis, and hovering the field shows them in full.

A file input out of sight holds the chosen files. It takes `accept`, `multiple`, `name`, `form`, `required` and `disabled` as a native file input does, so a form around the field sends the files under its name. A file that is picked again is reported again, and a cancelled dialog keeps the files that were chosen before.

## Multiple files

`multiple` lets people choose several files at once. Each pick replaces the files chosen before.

Attachments that take several files

[Complete TSX file](/examples/file-input/multiple.tsx)

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { FileInput } from "@/siteplane/components/file-input";

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Attachments</FieldLabel>
      <FileInput multiple />
      <FieldDescription>Choose one file or several.</FieldDescription>
    </Field>
  );
}
```

## Loading

`loading` shows a spinner at the end of the field, for example while the chosen file uploads. The field and its button stay usable, so a person can choose another file. `onFilesChange` receives the files as soon as they are picked, which is where an upload can start.

Contract upload that starts when a file is picked

[Complete TSX file](/examples/file-input/loading.tsx)

```tsx
"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { FileInput } from "@/siteplane/components/file-input";
import { useEffect, useRef, useState } from "react";

export default function Example() {
  const [loading, setLoading] = useState(false);
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
  useEffect(() => () => clearTimeout(timer.current), []);

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Contract</FieldLabel>
      <FileInput
        accept=".pdf"
        loading={loading}
        onFilesChange={(files) => {
          if (!files) return;
          // Stands in for your upload.
          setLoading(true);
          clearTimeout(timer.current);
          timer.current = setTimeout(() => setLoading(false), 2000);
        }}
      />
      <FieldDescription>PDF, up to 10 MB.</FieldDescription>
    </Field>
  );
}
```

## In a form

Inside a Field, FieldLabel names the field, FieldDescription and FieldError describe it, and the Field’s `name`, `disabled` and `invalid` reach it. With `required`, Form checks on submit that a file is chosen, and FieldError explains a missing file. While the field is invalid, the alert icon of an [Input Group](/docs/components/input-group/#help-tooltip) stands after the names, before the Upload button. On submit, the form data holds the chosen files under the field’s name. Form’s `onFormSubmit` receives the names that the field shows, so read the files from the form data or from `onFilesChange`.

Expense form that requires a receipt

[Complete TSX file](/examples/file-input/form.tsx)

```tsx
"use client";

import { Button } from "@/siteplane/components/button";
import {
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@/siteplane/components/field";
import { FileInput } from "@/siteplane/components/file-input";
import { Form } from "@/siteplane/components/form";

export default function Example() {
  return (
    <Form
      className="grid w-full max-w-sm gap-4"
      onSubmit={(event) => event.preventDefault()}
    >
      <Field name="receipt" requiredIndicator>
        <FieldLabel>Receipt</FieldLabel>
        <FileInput accept=".pdf,image/png,image/jpeg" required />
        <FieldDescription>PDF, PNG or JPG.</FieldDescription>
        <FieldError>Choose the receipt of the expense.</FieldError>
      </Field>
      <Button className="justify-self-start" type="submit">
        Submit expense
      </Button>
    </Form>
  );
}
```

## Sizes

Omit `size` to take the provider’s control size. `sm` is 36 px high, `md` 40 px, `lg` 44 px and `xl` 48 px, as on Input, and the Upload button takes the same size.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | sm \| md \| lg \| xl | provider / sm | The control size of the field and its button. |
| placeholder | string | "Choose a file" | The text the field shows while no file is chosen. |
| buttonText | string | "Upload" | The label of the button at the end of the field. |
| accept | string | unset | The file types the dialog offers, as on a native file input. |
| multiple | boolean | false | Lets people choose several files at once. |
| name | string | unset | The name of the files in the form data. A Field’s name takes precedence. |
| form | string | unset | The id of the form the files belong to, for a field outside that form. |
| required | boolean | false | A form submits only once a file is chosen. |
| disabled | boolean | false | Disables the field and its button. A disabled Field does the same. |
| loading | boolean | false | Shows a spinner at the end of the field. |
| onFilesChange | (files: FileList \| null) => void | unset | Called with the chosen files after a pick, and with null when a reset of the form empties the field. |
| variant | default \| soft | default | The surface of the field, as on Input. |
| id, aria-label, aria-labelledby, aria-describedby | string | unset | Go to the field’s text, the control that people reach and that a label names. |
| aria-invalid | boolean | unset | Marks the field invalid. Inside a Field, set invalid on the Field instead. |

`FileInputProps` is exported. Other `div` props, such as `className`, go to the root, an Input Group with `data-slot="file-input"`. The button carries `data-slot="file-input-button"`. It is a segment of the group, a ghost Button after the field's divider, so it stays flat on the field as the copy action of an [Input Group](/docs/components/input-group/) does.

[Read the installed source](/source/file-input).

## Usage notes

Give the field a label with FieldLabel or `aria-label`, and name the accepted files in a FieldDescription. `accept` only filters the dialog, so check the type and the size of each file again where you receive it. The field uploads nothing and shows no preview of a file. To drop files or to show a list of uploads with their progress, use [File Upload](/docs/patterns/file-upload/). For the browser’s own file control, use [Input](/docs/components/input/#file-input) with `type="file"`.
