Siteplane UI

File Input

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

Markdown

SVG, PNG or JPG, up to 2 MB.

"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

pnpm dlx shadcn@4.18.0 add @siteplane/form

Field is installed with Input.

Usage

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.

Choose one file or several.

"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.

PDF, up to 10 MB.

"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 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.

PDF, PNG or JPG.

"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

Component properties
PropTypeDefaultDescription
sizesm | md | lg | xlprovider / smThe control size of the field and its button.
placeholderstring"Choose a file"The text the field shows while no file is chosen.
buttonTextstring"Upload"The label of the button at the end of the field.
acceptstringunsetThe file types the dialog offers, as on a native file input.
multiplebooleanfalseLets people choose several files at once.
namestringunsetThe name of the files in the form data. A Field’s name takes precedence.
formstringunsetThe id of the form the files belong to, for a field outside that form.
requiredbooleanfalseA form submits only once a file is chosen.
disabledbooleanfalseDisables the field and its button. A disabled Field does the same.
loadingbooleanfalseShows a spinner at the end of the field.
onFilesChange(files: FileList | null) => voidunsetCalled with the chosen files after a pick, and with null when a reset of the form empties the field.
variantdefault | softdefaultThe surface of the field, as on Input.
id, aria-label, aria-labelledby, aria-describedbystringunsetGo to the field’s text, the control that people reach and that a label names.
aria-invalidbooleanunsetMarks 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 does.

Read the installed source.

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. For the browser’s own file control, use Input with type="file".