# FileField

A form control wrapper for file selection, shared field state, and file validation messages.

## Usage

Use standalone, or wrap `FileInput` to share state.
```svelte
<FileField {...props} />

<FileField {...props}>
  <FileInput {...props} />
</FileField>
```

## 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="top" conditional>
    <label class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </label>
    <span class="aux" conditional>{aux}</span>
  </div>
  <div class="middle">
    <span class="left" conditional>{left}</span>
    {#if children}{@render children()}{:else}<FileInput />{/if}
    <span class="right" conditional>{right}</span>
  </div>
  <div class="bottom" conditional>{bottom}</div>
</div>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `content*` | `Snippet` | - | Required presentational content for the default inner `FileInput`; receives files, drag-over state, and variant |
| `label` | `string` | - | Field label |
| `extra` | `string` | - | Extra text shown with the label |
| `aux` | `Snippet` | - | Auxiliary content; receives files, variant, and input element |
| `left` | `Snippet` | - | Content before the inner input; receives files, variant, and input element |
| `right` | `Snippet` | - | Content after the inner input; receives files, variant, and input element |
| `bottom` | `string` | - | Bottom message |
| `reserve` | `boolean` | `false` | Renders the bottom element even without a message to prevent layout shift |
| `files` | `File[]` | - | Bindable selected files |
| `multiple` | `boolean` | `false` | Allows selecting more than one file |
| `constraints` | `FileFieldConstraint[]` | - | Candidate-level functions used to reject files or supply rejection messages |
| `validations` | `FileFieldValidation[]` | - | Field-level functions used to validate the selected file list |
| `name` | `string` | - | The `name` attribute for form submission |
| `element` | `HTMLInputElement` | - | Bindable input element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
| `fileInput` | `FileInputProps` | - | Props for the default inner `FileInput`; ignored when `children` is supplied |
| `children` | `Snippet` | - | Use the compound form to provide a child `FileInput` that shares the field state |
`*` required.

When `reason` is set on a constraint context, the primitive already rejected the file and the constraint supplies a message only. When `reason` is undefined, a returned message also vetoes that candidate before commit.

## Styling

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

### Variant Management

In the initial state or while there are no files, `neutral` is applied. When files validate, the variant switches to `active`. If validation fails or a file add is rejected, `inactive` is applied. If the `variant` prop is specified, the specified value is used instead of `neutral`.

### Default Class Name

`svs-file-field`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Field (`whole` `<div>`): `role="group"` and `aria-labelledby` pointing to the label part when label text is present.

Provide `label` text for the field's accessible name; the component wires that label to the group instead of requiring an author-passed `aria-label`. With the default control, file-input validation ARIA is handled by [FileInput](/docs/file-input).

### Standards Basis

With the default FileInput, FileField 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.

## Exports

### Types

```ts
type FileFieldConstraint = (ctx: {
  file: File;
  files: File[];
  reason?: FileRejectReason;
  validity: ValidityState;
  element: HTMLInputElement;
}) => string | undefined | null;
type FileFieldValidation = SVSFieldValidation<File[]>;
interface FileFieldProps {
  content: Snippet<[File[], boolean, string]>; // Snippet<[files,dragover,variant]>
  label?: string;
  extra?: string;
  aux?: Snippet<[File[], string, HTMLInputElement | undefined]>; // Snippet<[files,variant,element]>
  left?: Snippet<[File[], string, HTMLInputElement | undefined]>; // Snippet<[files,variant,element]>
  right?: Snippet<[File[], string, HTMLInputElement | undefined]>; // Snippet<[files,variant,element]>
  bottom?: string;
  reserve?: boolean; // (false)
  files?: File[]; // bindable
  multiple?: boolean; // (false)
  constraints?: FileFieldConstraint[];
  validations?: FileFieldValidation[];
  name?: string;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  fileInput?: Omit<FileInputProps, FileInputReqdProps | FileInputBindProps | "multiple" | "name" | "variant" | "events">; // default <FileInput/> props
  children?: Snippet;
}
type FileFieldReqdProps = "content";
type FileFieldBindProps = "files" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

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

### Basic

**Code**

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

  const styling = {
    label: "font-bold",
    middle: "mt-1",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    label: "File Field",
    bottom: "Drop images or PDFs for review",
    multiple: true,
    reserve: true,
    styling,
  };
  const childStyle = {
    whole: "w-full max-w-96",
    middle:
      "flex min-h-32 cursor-pointer flex-col items-center justify-center rounded-sm border border-dashed p-6 text-center outline-hidden data-[dragover]:border-teal-500 data-[dragover]:bg-teal-50 dark:data-[dragover]:bg-teal-950",
    aux: "mt-3 flex flex-wrap gap-2",
  };
  const svsFileInput = {
    accept: "image/*,.pdf",
    maxFiles: 4,
    droppable: true,
    styling: childStyle,
  };
</script>

<FileField {...myProps} fileInput={svsFileInput}>
  {#snippet content(files, dragover)}
    <span class="font-bold">{dragover ? "Drop to attach" : "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}
</FileField>
```
### With Interactive Variant

**Code**

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

  let { variant = $bindable() } = $props();
  const constraints: FileFieldConstraint[] = [
    ({ file, reason }) => {
      if (reason === "accept") return "Only images and PDFs are allowed";
      if (reason === "maxFiles") return "Attach no more than 1 file";
      if (file.size > 1_000_000) return "Each file must be 1 MB or smaller";
    },
  ];
  const validations: FileFieldValidation[] = [({ value }) => (value.length > 1 ? "Attach an image or pdf 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 = {
    label: {
      base: "font-bold",
      inactive: "text-red-500",
    },
    middle: "mt-1",
    bottom: {
      base: "mt-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    label: "Favorite Fruits",
    bottom: "Attach an image or pdf file",
    reserve: true,
    constraints,
    validations,
    styling,
  };
  const childStyle = {
    whole: "flex items-center gap-1",
    middle: {
      base: "flex flex-nowrap items-center gap-1 cursor-pointer text-sm underline outline-hidden",
      ...variantStyle,
    },
    aux: "flex flex-nowrap items-center gap-1 text-sm underline stroke-gray-400",
  };
  const childProps = {
    accept: "image/*,.pdf",
    maxFiles: 1,
    maxSize: 1_000_000,
    styling: childStyle,
  };
</script>

<FileField bind:variant {...myProps}>
  <FileInput {...childProps}>
    {#snippet children(files)}
      {#if !files.length}
        <FileUp class="size-6 stroke-inherit" />
        <span>Attach a file</span>
      {/if}
    {/snippet}
    {#snippet aux(files, remove)}
      {#if files.length}
        {#each files as file}
          <button class="hover:stroke-red-500 cursor-pointer" type="button" onclick={() => remove(file)}>
            <Trash2 class="size-6 stroke-inherit hover:stroke-red-500" />
          </button>
          <span class="select-none">{file.name}</span>
        {/each}
      {/if}
    {/snippet}
  </FileInput>
</FileField>
```