arkyn

v3.0.1-beta.72

FileUpload

FileUpload is an advanced file upload component with drag-and-drop functionality, automatic validation, and integration with upload APIs. It offers an intuitive interface for selecting and uploading files with full visual feedback.

tsx

import { FileUpload } from "@arkyn/components";

Basic usage

Basic usage of FileUpload requires the name and action properties.

tsx

<FileUpload name="document" action="/api/upload" label="Select a file" />

Endpoint configuration

The endpoint provided in action must accept upload requests via POST and return a JSON file with the URL of the uploaded file or an error message.

tsx

// Success response example
{ "url": "https://yourdomain.com/uploads/filename.ext" }


// Error response example
{ "error": "File type not supported" }

Upload with validation

Configure accepted file types and automatic validation.

tsx

<FileUpload
  name="avatar"
  action="/api/upload/avatar"
  label="Profile Picture"
  showAsterisk
  acceptFile="image/*"
  selectFileButtonText="Choose Image"
  changeFileButtonText="Change Image"
  dropFileText="Drag your image here"
  onChange={(url) => console.log("Avatar uploaded:", url)}
/>

Specific file types

You can restrict uploads to specific file types using the acceptFile property.

tsx

// Upload PDF
<FileUpload
name="contract"
action="/api/upload/document"
label="Contract (PDF)"
acceptFile=".pdf"
selectFileButtonText="Select PDF"
dropFileText="Drag PDF file here"
/>


// Video Upload
<FileUpload
name="presentation"
action="/api/upload/video"
label="Presentation Video"
acceptFile="video/mp4,video/webm"
selectFileButtonText="Choose Video"
dropFileText="Drag video here (MP4 or WebM)"
/>


// Multiple Types
<FileUpload
name="media"
action="/api/upload/media"
label="Image or Video"
acceptFile="image/*,video/*"
selectFileButtonText="Select Media"
/>

Upload disabled

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

tsx

<FileUpload
  name="document"
  action="/api/upload"
  label="Upload Temporarily Unavailable"
  disabled
/>

Validation and errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.
Customizable Forms
For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

tsx

<FileUpload
  name="avatar"
  action="/api/upload/avatar"
  label="Profile Picture"
  showAsterisk
  acceptFile="image/*"
  errorMessage="Please upload a valid image"
  onChange={(url) => console.log("Avatar uploaded:", url)}
/>

Properties

name - string (required) Field name for form manipulation
action - string (required) URL of the endpoint where the file is located. The file will be uploaded.
disabled - boolean (default: false) If file upload is disabled.
label - string Label text to display above the upload area.
showAsterisk - boolean (default: false) Whether to display an asterisk in the label for required fields.
changeFileButtonText - string (default: "Change file") Button text to change/replace an already uploaded file.
selectFileButtonText - string (default: "Select file") Button text to select a file.
dropFileText - string (default: "Or drag and drop the file here") Text displayed in the drop zone.
method - string (default: "POST") HTTP method for the upload request
fileName - string (default: "file") Name of the field in the FormData for the file
fileResponseName - string (default: "url") Name of the property in the response object that contains the file URL
acceptFile - string (default: "*") File types accepted by the input (e.g., "image/*", ".pdf")
onChange - (url?: string) => void Callback function called when the upload is successful

Form integration

The component natively integrates with form management systems:
  • Display of contextual errors
  • Form state management
  • Support for separate or masked values
Customizable Forms
For more complex forms, we recommend using the Form Provider which offers native integration with all form tools at once.

Notes

  • Required Endpoint - Always set a valid URL in action
  • Response Format - API must return JSON with URL or error
  • Type Validation - Use acceptFile to restrict formats
  • Error Handling - Implement onChange callback for feedback
  • File Size - Validation must be done on the server-side
  • Security - Always validate files on the backend
  • Performance - For large files, consider progressive upload
  • FormData - Files are automatically uploaded via FormData
  • Visual States - Component provides automatic visual feedback
  • Accessibility - Full support for keyboard navigation and screen readers
On this page