Site color

Choose your site’s color palette.

Saved on this device.

DropFiles

DropFilesLocal file collection

Collect files with a familiar picker, drop gesture, or paste. Filter types, inspect selections, and remove individual files.

Forms & input

Collect project attachments

Add local text, image or PDF files, remove individual entries and inspect the total size. Nothing is uploaded. In single-file mode, the next accepted file replaces the selection.

DropFiles in contextCOMPOSITION

Choose, drop, or paste supported files. Selections stay in this browser; the demo does not upload them.

<RegorApp id="drop-files-demo" src="./playground.ts"/>
import {
  type DropFileItem,
  type DropFilesIconMap,
  defineButtonComponents,
  defineDropFilesComponents,
  defineFlexComponents,
  defineFormComponents,
  defineIconComponents,
} from '@purestack/ts-components'
import {
  lucide_cloud_upload,
  lucide_file,
  lucide_file_archive,
  lucide_file_image,
  lucide_file_text,
  lucide_trash,
} from '@purestack/ts-svg-icons'
import {
  type ComputedRef,
  computed,
  createApp,
  defineComponent,
  html,
  type Ref,
  ref,
  type SRef,
  sref,
} from 'regor'
import { mountFormAppearanceGalleries } from '../appearance'

export interface DropFilesExample {
  selectedFiles: SRef<DropFileItem[]>
  allowMany: Ref<boolean>
  locked: Ref<boolean>
  totalBytes: ComputedRef<number>
  clear: () => void
  referenceFiles: SRef<DropFileItem[]>
  fileIcons: DropFilesIconMap
  activity: Ref<string>
  filesChanged: (files: DropFileItem[]) => void
}

const dropFilesExampleTemplate = html`<Flex direction="column">
  <DropFiles
    label="Project attachments"
    hint="Text, images and PDF files. Files stay in this browser."
    accept="text/*,image/*,.pdf"
    :files="selectedFiles"
    :multiple="allowMany"
    :disabled="locked"/>
  <Flex wrap="true">
    <FormCheck
      id="files-multiple"
      label="Allow multiple files"
      :checked="allowMany"/>
    <FormCheck
      id="files-disabled"
      label="Lock file selection"
      :checked="locked"/>
    <Btn variant="link" :disabled="locked" @click="clear">Clear files</Btn>
  </Flex>
  <FormStatus>
    {{ selectedFiles.length }} files · {{ totalBytes }} bytes selected
  </FormStatus>
  <h3>Custom copy, icons, and change callback</h3>
  <DropFiles
    :files="referenceFiles"
    label="Design references"
    hint="Images and PDF files only."
    emptyTitle="Add your references"
    emptyText="Choose files, drop them, or paste."
    accept="image/*,.pdf"
    uploadIcon="lucide:file-image"
    fileIcon="lucide:file"
    removeIcon="lucide:trash"
    :iconMap="fileIcons"
    :context="{ onChange: filesChanged }"/>
  <FormStatus>{{ activity }}</FormStatus>
  <ul>
    <li r-for="file in referenceFiles">
      {{ file.name }} · {{ file.type || 'Unknown type' }} ·
      {{ file.sizeLabel }} · {{ file.icon }}
    </li>
  </ul>
</Flex>`

function createDropFilesExample(): DropFilesExample {
  const selectedFiles = sref<DropFileItem[]>([])
  const activity = ref(
    'Choose a reference to inspect onChange and file metadata.',
  )
  return {
    selectedFiles,
    allowMany: ref(true),
    locked: ref(false),
    totalBytes: computed(() =>
      selectedFiles().reduce((sum, item) => sum + item.size, 0),
    ),
    clear: () => selectedFiles([]),
    referenceFiles: sref<DropFileItem[]>([]),
    fileIcons: { 'image/*': 'lucide:file-image', '.pdf': 'lucide:file-text' },
    activity,
    filesChanged: (files) =>
      activity(`onChange: ${files.length} reference files selected`),
  }
}

const component = defineComponent<DropFilesExample>(dropFilesExampleTemplate, {
  context: createDropFilesExample,
})
const icons: Record<string, string> = {
  'lucide:cloud-upload': lucide_cloud_upload,
  'lucide:file': lucide_file,
  'lucide:trash': lucide_trash,
  'lucide:file-image': lucide_file_image,
  'lucide:file-text': lucide_file_text,
  'lucide:file-archive': lucide_file_archive,
}

createApp(
  {
    components: {
      DropFilesExample: component,

      ...defineDropFilesComponents(),
      ...defineFlexComponents(),
      ...defineFormComponents(),
      ...defineButtonComponents(),
      ...defineIconComponents((name) => icons[name] ?? ''),
    },
  },
  { selector: 'app#drop-files-demo', template: html`<DropFilesExample/>` },
)

mountFormAppearanceGalleries()

A clearly disabled drop zone

Use a hint to explain why selection is unavailable.

Attachments
Attachments are locked Finish the current review to add files. Read-only example
<DropFiles
  label="Attachments"
  emptyTitle="Attachments are locked"
  emptyText="Finish the current review to add files."
  hint="Read-only example"
  :disabled="true"
/>

All semantic tones

All ten tones are visible at once. The control’s label and content explain the intent independently of color.

All ten semantic tonesCOMPOSITION

Each sample is interactive and keeps its own local state. Switch the site theme to compare both palettes.

All visual variants

All eighteen supported treatments, shown in accent. Tone and variant are independent, so any treatment can be combined with a semantic tone.

All eighteen visual variantsCOMPOSITION

Each sample is interactive and keeps its own local state. Switch the site theme to compare both palettes.

File collection features

Feature How to try it
Picker, drop, paste All three add local File objects to the same selection.
accept The main demo accepts text, images, and PDF; filtering applies to every entry path.
multiple Toggle multiple files; single mode retains one accepted selection.
disabled Lock the collector; adding and removal are unavailable.
File metadata Each item includes id, file, name, type, size, formatted size, lastModified, and icon.
Remove and clear Remove individual files with their button, or clear the demo list.
Empty copy label, hint, emptyTitle, and emptyText describe the collector before files are added.
Icons uploadIcon, fileIcon, removeIcon, and iconMap choose registered symbols.
onChange Receives the updated selection; this component does not upload files.
<DropFiles label="Reference files" hint="Images and PDF only"
  emptyTitle="Add your references" emptyText="Choose files, drop them, or paste."
  accept="image/*,.pdf" :multiple="true" :disabled="locked" :files="files"
  uploadIcon="lucide:cloud-upload" fileIcon="lucide:file" removeIcon="lucide:trash"
  :iconMap="fileIcons" :context="{ onChange: filesChanged }"/>

Behavior and accessibility

The drop zone opens the native picker with Enter or Space. File acceptance is a client-side convenience, not server validation. Duplicates are identified from file metadata. onChange runs when the component changes the selection; assigning the files ref yourself is application state management.

API reference

DropFiles contract

Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.

files

SRef<DropFileItem[]>
Default
sref([])

Writable shallow ref of DropFileItem[]. Each item retains its File plus id, name, type, size, sizeLabel, lastModified and icon.

accept

RefOrValue<string> | string[]
Default
all files, or iconMap keys

Comma-separated MIME types, wildcards or extensions; arrays are also accepted. An explicit accept list takes precedence over iconMap keys.

iconMap

DropFilesIconMap | SRef<DropFilesIconMap>
Default
built-in type icons

MIME/extension-to-icon map merged with the defaults. When accept is omitted, a supplied map also determines accepted types.

label

RefOrValue<string>
Default
not set

Visible label. Use language that describes the control or value in its surrounding context.

hint

RefOrValue<string>
Default
not set

Supporting text beneath the drop-zone instructions.

emptyTitle

RefOrValue<string>
Default
Add files

Drop-zone heading, shown even when files are selected.

emptyText

RefOrValue<string>
Default
Click, tap, paste, or drag files here.

Drop-zone instructions.

disabled

RefOrValue<boolean>
Default
false

Disables interaction. Use a bound boolean, for example :disabled="isLocked".

multiple

RefOrValue<boolean>
Default
true

false accepts the first matching file and replaces the current list.

tone

RefOrValue<SemanticTone>
Default
inherited

Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.

variant

RefOrValue<ComponentVariant>
Default
surfaceAlt

Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.

uploadIcon

RefOrValue<string>
Default
lucide:cloud-upload

Drop-zone icon.

fileIcon

RefOrValue<string>
Default
lucide:file

Fallback file icon when no type-specific mapping matches.

removeIcon

RefOrValue<string>
Default
lucide:trash

Icon on each remove button.

onChange

(files: DropFileItem[]) => void
Default
not set

Callback receiving the updated DropFileItem[] after a component-driven change.

Composition

No slots. Register defineDropFilesComponents and its icons. Use addDropFiles when another input path needs the same filtering, metadata and deduplication behavior.