FileField
A form control wrapper for file selection, shared field state, and file validation messages.
Usage
Use standalone, or wrap FileInput to share state.
<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.
<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.
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"andaria-labelledbypointing 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.
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 for the library's approach.
Exports
Types
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.