File Upload

Overview

The File Upload component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

File uploads are a common friction point in forms. A well-designed upload zone with drag-and-drop, file preview, and clear error states reduces user anxiety.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { useState } from 'react';
import { FileUpload, FileUploadList, FileUploadItem } from '@byteion/react';

export default function FileUploadDemo() {
  const [files, setFiles] = useState<File[]>([]);
  return (
    <div className="grid gap-4 p-6">
      <FileUpload
        accept="image/*"
        multiple
        onFiles={(list) => setFiles([...files, ...list])}
        hint="PNG or JPG up to 5MB"
      />
      <FileUploadList>
        {files.map((f) => (
          <FileUploadItem key={f.name} name={f.name} size={f.size} state="success" />
        ))}
      </FileUploadList>
    </div>
  );
}

<script setup lang="ts">
import { ref } from 'vue';
import { FileUpload, FileUploadList, FileUploadItem } from '@byteion/vue';

const files = ref<File[]>([]);
function onFiles(list: File[]) { files.value = [...files.value, ...list]; }
</script>

<template>
  <div class="grid gap-4 p-6">
    <FileUpload accept="image/*" multiple hint="PNG or JPG up to 5MB" @files="onFiles" />
    <FileUploadList>
      <FileUploadItem v-for="f in files" :key="f.name" :name="f.name" :size="f.size" state="success" />
    </FileUploadList>
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• idle — idle state.
• hover — Pointer is over the element — visual feedback via color or shadow.
• uploading — uploading state.
• complete — complete state.
• error — Validation failed — red border and error message.
• default — Resting appearance before interaction.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

Usage guidelines

• Accept drag-and-drop and click-to-browse.
• Validate file type and size before upload.
• Show a preview for image files.

Do and Don't

Accessibility

Hidden native input is triggered by clicking the zone. Zone must have a descriptive label.

Customization

Border and hover colors follow design tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myFileUpload = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myFileUpload>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myFileUpload = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myFileUpload({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Uses hidden native input. Zone is a styled label.

export interface FileUploadProps
  extends Omit<HTMLAttributes<HTMLLabelElement>, 'children' | 'onChange' | 'title'> {
  /** Fired when files are added via the picker or drop. */
  onFilesAdded?: (files: File[]) => void;
  /** Allow multiple files. */
  multiple?: boolean;
  /** Accept attribute (e.g. "image/*", ".pdf"). */
  accept?: string;
  /** Disable the upload zone. */
  disabled?: boolean;
  /** Visual variant. */
  variant?: 'default' | 'compact';
  /** Headline above the description. */
  title?: ReactNode;
  /** Sub-line shown beneath the title (e.g. "PNG, JPG, PDF up to 10 MB"). */
  description?: ReactNode;
  /** Optional id passed to the hidden input. */
  id?: string;
  /** Render any extra content inside the zone (replaces the default body). */
  children?: ReactNode;
}

export interface FileUploadProps {
  /** Allow multiple files. */
  multiple?: boolean;
  /** Accept attribute (e.g. "image/*", ".pdf"). */
  accept?: string;
  /** Disable the upload zone. */
  disabled?: boolean;
  /** Visual variant. */
  variant?: 'default' | 'compact';
  /** Headline above the description. */
  title?: string;
  /** Sub-line shown beneath the title. */
  description?: string;
  /** Optional id passed to the hidden input. */
  id?: string;
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Input
• Toast
• Progress