formsfile-upload

FileUpload

Drag-and-drop file upload component with progress tracking and file list management.

Import#

import { FileUpload } from 'moraine'

Slot Structure#

Upload control and optional file preview list.

Upload area#

root
└── control (dropzone or trigger button)
    └── wrapper
        ├── icon (Icon)
        ├── label (optional)
        └── description (optional)

File preview list#

root
└── files
    └── file (×n)
        ├── filePreview
        ├── fileMeta
        │   ├── fileName
        │   └── fileSize
        └── fileRemove

Examples#

Single Upload#

Basic single-file mode with a live readout from onValueChange.

1
function SingleUpload() {
2
  type FileUploadValue = FileUploadT.Value
3

4
  function fileNames(value: FileUploadValue): string {
5
    if (value === null) {
6
      return 'none'
7
    }
8

9
    if (Array.isArray(value)) {
10
      return value.length > 0 ? value.map((file) => file.name).join(', ') : 'none'
11
    }
12

13
    return value.name
14
  }
15

16
  const [singleValue, setSingleValue] = createSignal<FileUploadValue>(null)
17

18
  return (
19
    <div class="max-w-xl space-y-3">
20
      <FileUpload
21
        label="Upload one file"
22
        description="PNG, JPG, PDF up to your browser limit."
23
        accept="image/*,.pdf"
24
        onValueChange={setSingleValue}
25
      />
26
      <p class="text-xs text-muted-foreground">Selected file: {fileNames(singleValue())}</p>
27
    </div>
28
  )
29
}

Multiple + Max Files#

Append files across selections, reject overflow, and show selected names.

1
function MultipleMaxFiles() {
2
  function fileCount(value: FileUploadValue): number {
3
    if (value === null) {
4
      return 0
5
    }
6

7
    if (Array.isArray(value)) {
8
      return value.length
9
    }
10

11
    return 1
12
  }
13

14
  function fileNames(value: FileUploadValue): string {
15
    if (value === null) {
16
      return 'none'
17
    }
18

19
    if (Array.isArray(value)) {
20
      return value.length > 0 ? value.map((file) => file.name).join(', ') : 'none'
21
    }
22

23
    return value.name
24
  }
25

26
  const [multiValue, setMultiValue] = createSignal<FileUploadValue>([])
27

28
  const [rejectedCount, setRejectedCount] = createSignal(0)
29

30
  type FileUploadValue = FileUploadT.Value
31

32
  return (
33
    <div class="max-w-xl space-y-3">
34
      <FileUpload
35
        multiple
36
        maxFiles={3}
37
        accept="image/*,.pdf"
38
        label="Upload up to 3 files"
39
        description="Drop or select multiple files."
40
        onValueChange={setMultiValue}
41
        onFileReject={(files) => setRejectedCount(files.length)}
42
      />
43
      <p class="text-xs text-muted-foreground">Selected count: {fileCount(multiValue())}</p>
44
      <p class="text-xs text-muted-foreground">Selected names: {fileNames(multiValue())}</p>
45
      <p class="text-xs text-muted-foreground">Last reject batch size: {rejectedCount()}</p>
46
    </div>
47
  )
48
}

Sizes#

Size scale from xs to xl for trigger height, spacing, and file list density.

1
function Sizes() {
2
  const SIZES: FileUploadSize[] = ['xs', 'sm', 'md', 'lg', 'xl']
3

4
  return (
5
    <div class="max-w-xl space-y-3">
6
      <For each={SIZES}>
7
        {(size) => (
8
          <FileUpload
9
            size={size}
10
            dropzone={false}
11
            preview={false}
12
            label={`Upload (${size})`}
13
            description="Click to choose files."
14
          />
15
        )}
16
      </For>
17
    </div>
18
  )
19
}

Trigger Mode (No Dropzone)#

Use button-style trigger behavior by disabling dropzone interaction.

1
function TriggerModeNoDropzone() {
2
  return (
3
    <div class="max-w-xl">
4
      <FileUpload
5
        dropzone={false}
6
        label="Select file"
7
        description="Click to choose files."
8
        preview={false}
9
      />
10
    </div>
11
  )
12
}

Form Integration#

Submit to validate a required attachment with Form + FormField.

1
function FormIntegration() {
2
  const [formState, setFormState] = createSignal({
3
    attachment: null as File | null,
4
  })
5

6
  const updateFormAttachment = (value: FileUploadValue) => {
7
    const next = Array.isArray(value) ? (value[0] ?? null) : value
8
    setFormState((prev) => ({ ...prev, attachment: next }))
9
  }
10

11
  type FileUploadValue = FileUploadT.Value
12
  const form = createForm({
13
    schema: v.object({ attachment: v.file('Please upload one attachment.') }),
14
    initialInput: { attachment: undefined },
15
  })
16

17
  return (
18
    <Form of={form}>
19
      <div class="max-w-xl space-y-4">
20
        <FormField
21
          name="attachment"
22
          label="Attachment"
23
          description="Upload at least one file before submit."
24
          required
25
        >
26
          <FileUpload id="demo-attachment-upload" onValueChange={updateFormAttachment} />
27
        </FormField>
28
        <div class="flex gap-3 items-center">
29
          <Button type="submit" variant="secondary" size="sm">
30
            Validate
31
          </Button>
32
          <p class="text-xs text-muted-foreground">
33
            Current attachment: {formState().attachment?.name ?? 'none'}
34
          </p>
35
        </div>
36
      </div>
37
    </Form>
38
  )
39
}

API Reference#

Attributes#

Slotroot3 attributes

Upload component container that owns dropzone, file input, and file list.

Data Attributes

Data Attribute	Description
data-disabled	Present when the component or item is disabled.
data-readonly	Present when the field is read-only.

ARIA Attributes

ARIA Attribute	Description
role	Defines the semantic role exposed to assistive technology.

Props#

Prop	Type	Default	Description
accept	`string \| undefined`	`*`	Accepted file types (e.g., ".jpg,.png", "image/*").
as	`"div" \| undefined`	`div`	The HTML element or component to render as.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`FileUploadT.Classes \| undefined`	—	—
description	`JSX.Element`	—	Description text for the upload area.
disabled	`boolean \| undefined`	`false`	Whether the input is disabled.
dropzone	`boolean \| undefined`	`true`	Whether to enable drag and drop.
fileIcon	`IconT.Name`	`icon-file`	Icon to show for individual files when no preview is available.
icon	`IconT.Name`	`icon-upload`	Icon to show in the upload area.
id	`string \| undefined`	—	The ID of the input element.
label	`JSX.Element`	—	Label for the upload area.
maxFiles	`number \| undefined`	—	Maximum number of files allowed.
maxSize	`number \| undefined`	—	Maximum accepted file size in bytes.
minSize	`number \| undefined`	—	Minimum accepted file size in bytes.
multiple	`boolean \| undefined`	`false`	Whether multiple files can be uploaded.
name	`string \| undefined`	—	The name of the input element, used for form submission.
onClick	`JSX.EventHandlerUnion<HTMLElement, MouseEvent> \| undefined`	—	Click handler for the upload control.
onDragLeave	`JSX.EventHandlerUnion<HTMLElement, DragEvent> \| undefined`	—	Drag-leave handler for the upload dropzone.
onDragOver	`JSX.EventHandlerUnion<HTMLElement, DragEvent> \| undefined`	—	Drag-over handler for the upload dropzone.
onDrop	`JSX.EventHandlerUnion<HTMLElement, DragEvent> \| undefined`	—	Drop handler for the upload dropzone.
onFileReject	`((files: FileRejection[]) => void) \| undefined`	—	Callback when files are rejected (e.g., due to type or count).
onKeyDown	`JSX.EventHandlerUnion<HTMLElement, KeyboardEvent> \| undefined`	—	Keyboard handler for the upload control.
onValueChange	`((value: FileUploadT.Value) => void) \| undefined`	—	Callback when the selected files change.
preview	`boolean \| undefined`	`true`	Whether to show file previews.
readOnly	`boolean \| undefined`	`false`	Whether the input is read-only.
ref	`JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
required	`boolean \| undefined`	`false`	Whether the input is required.
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`FileUploadT.Styles \| undefined`	—	—