# FileInput

A standalone file picker with optional drag-and-drop, validation limits, and presentational drop-zone content.

## Usage

Use standalone, or inside `FileField`.
```svelte
<FileInput {...props}>Drop files</FileInput>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole">
  <div class="aux" conditional>{aux}</div>
  <label class="middle" data-dragover>
    <input class="main" {...rest} type="file" style="sr-only" aria-invalid aria-errormessage />
    {children}
  </label>
  <div class="aux" conditional>{aux}</div>
</div>
```

Drag-over renders the local variant as `active`. `children` must be presentational; place interactive remove or clear controls in `aux`. `accept` is re-checked by the primitive because drag-and-drop bypasses the native picker filter.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children*` | `Snippet` | - | Required presentational content for the drop zone; receives files, drag-over state, and variant |
| `files` | `File[]` | - | Bindable selected files |
| `multiple` | `boolean` | `false` | Allows selecting more than one file |
| `accept` | `string` | - | Accepted file types for committed files |
| `maxSize` | `number` | - | Maximum file size in bytes |
| `maxFiles` | `number` | - | Maximum number of committed files |
| `droppable` | `boolean` | `false` | Enables drag-and-drop on the drop zone |
| `rejectBy` | `<enum>[]` | - | Bindable list of reject reasons from the most recent add attempt |
| `flip` | `boolean` | `false` | Renders `aux` before the drop zone instead of after it |
| `aux` | `Snippet` | - | External snippet for interactive controls such as remove buttons |
| `events` | `FileInputEvents` | - | Functions that can filter which added or removed files are committed |
| `attach` | `Attachment` | - | Svelte attachment on the input |
| `element` | `HTMLInputElement` | - | Bindable input element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant |
`*` required. Other `HTMLInputAttributes` are passed to `<input>` via rest props; `class` is merged onto the control.

Input attributes such as `disabled`, `required`, and `name` are passed at the top level.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

During drag-over, the local variant is forced to `active`. Otherwise there is no automatic switching.

### Default Class Name

`svs-file-input`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Input (`main` `<input type="file">`): `aria-describedby`, `aria-invalid`, and `aria-errormessage` from the field-validation wiring and current error-message id.

Provide an accessible name yourself because there is no built-in visible label. Pass `aria-label` or `aria-labelledby` through the rest props, or associate a `<label>` with the file input.

### Standards Basis

FileInput is built on a native `<input type="file">`, so keyboard and assistive-technology support follows the browser standard for file inputs. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach. Drag-and-drop is a pointer enhancement over the always-present native control.

## Exports

### Types

```ts
interface FileInputEvents extends Omit<CollectionEvents<File>, "onadd"> {
  onadd?: (detail: { values: File[]; added: File[]; rejected: FileRejection[] }) => File[] | void;
}
interface FileRejection {
  file: File;
  reason: FileRejectReason;
}
type FileRejectReason = "accept" | "maxSize" | "maxFiles";
interface FileInputProps extends Omit<HTMLInputAttributes, "type" | "value" | "files" | "size" | "multiple" | "accept" | "children"> {
  children: Snippet<[File[], boolean, string]>; // required; Snippet<[files,dragover,variant]>; zone content, presentational only
  files?: File[]; // bindable
  multiple?: boolean; // (false)
  accept?: string;
  maxSize?: number; // bytes
  maxFiles?: number;
  droppable?: boolean; // (false)
  rejectBy?: ("accept" | "maxSize" | "maxFiles")[]; // bindable
  flip?: boolean; // (false) - render aux before the zone instead of after
  aux?: Snippet<[File[], (file: File) => void, string]>; // Snippet<[files,remove,variant]>; rendered outside the label
  events?: FileInputEvents;
  attach?: Attachment<HTMLInputElement>;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // class & other HTMLInputAttributes are passed to <input> via ...rest (class is merged onto the control)
}
type FileInputReqdProps = "children";
type FileInputBindProps = "files" | "rejectBy" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=FileInputBasic.svelte
<script lang="ts">
  import { FileInput } from "svseeds";

  let files = $state<File[]>([]);
  const styling = {
    whole: "w-full max-w-80",
    middle:
      "flex min-h-32 cursor-pointer flex-col items-center justify-center rounded-md border-2 border-dashed p-6 text-center outline-hidden data-[dragover]:border-teal-600 data-[dragover]:bg-teal-50 dark:data-[dragover]:bg-teal-950",
    aux: "mt-3 flex flex-wrap gap-2",
  };
  const myProps = {
    multiple: true,
    accept: "image/*,.pdf",
    maxFiles: 4,
    droppable: true,
    styling,
  };
</script>

<FileInput bind:files {...myProps}>
  {#snippet children(files, dragover)}
    <span class="font-bold">{dragover ? "Drop to add files" : "Drop files here or browse"}</span>
    <span class="mt-1 text-sm text-gray-400">{files.length ? `${files.length} selected` : "Images or PDFs, up to 4 files"}</span>
  {/snippet}
  {#snippet aux(files, remove)}
    {#each files as file}
      <button class="rounded-md border px-2 py-1 text-sm cursor-pointer hover:text-red-500" type="button" onclick={() => remove(file)}
        >{file.name}</button
      >
    {/each}
  {/snippet}
</FileInput>
```
### With Interactive Variant

**Code**

```svelte src=FileInputPract.svelte
<script lang="ts">
  import { FileInput } from "svseeds";
  import FileUp from "@lucide/svelte/icons/file-up";
  import Trash2 from "@lucide/svelte/icons/trash-2";

  let { variant = $bindable() } = $props();
  let files = $state<File[]>([]);
  const variantStyle = {
    neutral: "stroke-gray-400",
    active: "stroke-teal-500",
    inactive: "stroke-red-500",
    blue: "stroke-blue-500",
    yellow: "stroke-yellow-500",
    sky: "stroke-sky-500",
  };
  const styling = {
    whole: "flex w-fit flex-col items-center",
    middle: {
      base: "size-fit cursor-pointer outline-hidden",
      ...variantStyle,
    },
    aux: "mt-3 flex flex-nowrap gap-2",
  };
  const myProps = {
    accept: "text/plain",
    maxSize: 1_000_000,
    styling,
  };
</script>

<FileInput bind:files {variant} {...myProps}>
  <FileUp class="size-12 stroke-inherit" />
  {#snippet aux(files, remove, variant)}
    {#each files as file}
      <button
        class="flex items-center gap-1 text-sm border-b hover:text-red-500 cursor-pointer"
        data-variant={variant}
        type="button"
        onclick={() => remove(file)}
      >
        {file.name}
        <Trash2 class="size-4 hover:stroke-red-500" />
      </button>
    {/each}
  {/snippet}
</FileInput>
```