Files Upload

Overview

The Files Upload component in the Phenix Design System provides an enhanced file input experience with features like drag-and-drop, preview capabilities, and customizable styling. It's designed to make file uploads more intuitive and user-friendly compared to standard HTML file inputs.

Basic Usage

The Files Upload component offers two main types: standard and advanced. The type is defined by the data-uploader attribute or through the JavaScript initialization options.

Standard Uploader

To create a standard file upload component:

<!-- Standard Uploader (default) -->
<div class="px-uploader" data-uploader="standard" data-placeholder="File Upload" data-btn="Browse">
    <input type="file">
</div>

The standard uploader inherits styles from the .form-control class and displays:

• A text area showing the file name or placeholder text
• A "Browse" button (or custom text specified by data-btn)

Advanced Uploader (Drag and Drop)

For a more interactive drag-and-drop experience:

<!-- Advanced Uploader -->
<div class="px-uploader" data-uploader="advanced" data-placeholder="Drag and Drop your file to upload">
    <input type="file">
</div>

Initialize the components with JavaScript:

// Initialize with default options (type will be determined by data-uploader attribute)
Phenix('.px-uploader').uploader();

// Or specify the type explicitly
Phenix('.px-uploader').uploader({ type: 'standard' });
// For advanced mode
Phenix('.px-uploader').uploader({ type: 'advanced' });

Features

Multiple File Upload

Enable multiple file selection by adding the multiple attribute to the input or using the data-multiple attribute on the container:

<!-- Advanced Uploader with Multiple Files -->
<div class="px-uploader" data-uploader="advanced" data-placeholder="Drag and Drop your files to upload">
    <input type="file" multiple>
</div>

<!-- Alternative with data-multiple -->
<div class="px-uploader" data-uploader="advanced" data-placeholder="Drag and Drop your files to upload" data-multiple="true">
    <input type="file">
</div>

The component will handle multiple file selections based on these attributes.

File Type Restrictions

Restrict the types of files that can be uploaded using the standard HTML accept attribute:

<!-- Standard Uploader for Images Only -->
<div class="px-uploader" data-uploader="standard" data-placeholder="Select an Image" data-btn="Browse">
    <input type="file" accept="image/*">
</div>

Custom Placeholder Text

Set custom placeholder text using the data-placeholder attribute:

<!-- Advanced Uploader with Custom Placeholder -->
<div class="px-uploader" data-uploader="advanced" data-placeholder="Drop your files here or click to browse">
    <input type="file">
</div>

Preview Modes

The advanced uploader automatically adds preview capabilities for images and videos:

<!-- Advanced Uploader with Preview -->
<div class="px-uploader" data-uploader="advanced" data-placeholder="Upload an image or video">
    <input type="file" accept="image/*,video/*">
</div>

When an image is selected, the component adds the image-mode class and sets a background image. For videos, it adds the video-mode class and creates a video player.

Customization

CSS Variables

The uploader component inherits CSS variables from the form controls system, which you can customize:

.px-uploader {
  /* Size variables */
  --padding: 15px;
  --height: 42px;
  --text-size: 14px;
  
  /* Color variables */
  --color: var(--component-tx-lvl-1);
  --background: var(--component-bg-lvl-1);
  --border-size: 1px;
  --border-color: rgba(0, 0, 0, 0.1);
}

Size Variants

You can use size modifier classes that come from the form control system:

<!-- Small uploader -->
<div class="px-uploader small" data-uploader="standard" data-placeholder="Small uploader" data-btn="Browse">
  <input type="file">
</div>

<!-- Large uploader -->
<div class="px-uploader large" data-uploader="standard" data-placeholder="Large uploader" data-btn="Browse">
  <input type="file">
</div>

Status Colors

You can use status color classes to indicate different states:

<!-- Success state -->
<div class="px-uploader success" data-uploader="standard" data-placeholder="File uploaded successfully" data-btn="Browse">
  <input type="file">
</div>

<!-- Error state -->
<div class="px-uploader error" data-uploader="standard" data-placeholder="Upload failed" data-btn="Browse">
  <input type="file">
</div>

JavaScript API

The Files Upload component must be manually initialized. The component will handle the file upload interface based on the specified type and options.

Initialization

// Basic initialization (uses data-uploader attribute to determine type)
Phenix('.px-uploader').uploader();

// With explicit type option
Phenix('.px-uploader').uploader({
  type: 'standard' // or 'advanced'
});

// With source URL (for pre-populated media)
Phenix('.px-uploader').uploader({
  type: 'advanced',
  src: '/path/to/media.jpg'
});

Available Options

Option	Type	Default	Description
type	String	'standard'	Uploader type: 'standard' or 'advanced'
src	String	undefined	Optional default media source URL

Available Data Attributes

Attribute	Type	Default	Description
data-uploader	String	'standard'	Uploader type: 'standard' or 'advanced'
data-placeholder	String	'Drag and Drop your file to upload'	Custom placeholder text
data-btn	String	'Browse'	Text for the browse button (standard uploader only)
data-multiple	Boolean	false	Enable multiple file selection (alternative to the 'multiple' attribute)

CSS Classes

The component uses these CSS classes for styling and functionality:

Class	Description
px-uploader	Main container class for the uploader component
form-control	Applied to standard uploader for form styling
highlight	Added when dragging files over the uploader
image-mode	Added when an image file is selected (shows image preview)
video-mode	Added when a video file is selected (shows video player)
px-done	Added after initialization to prevent re-initialization

Handling File Selection

The component automatically handles basic file selection events. For standard uploaders, it updates the placeholder with the selected file name. For advanced uploaders, it creates a file list and handles image/video previews.

You can also listen for file selection events:

// Listen for file selection
Phenix('.px-uploader input[type="file"]').on('change', (event) => {
  const files = event.target.files;
  if (files.length > 0) {
    console.log(`Selected ${files.length} file(s)`);
    
    // Access file information
    Array.from(files).forEach(file => {
      console.log(`File: ${file.name}, Size: ${file.size}, Type: ${file.type}`);
    });
  }
});

Custom File Upload with AJAX

Implement custom file upload with AJAX:

// Custom AJAX upload
Phenix('.px-uploader input[type="file"]').on('change', async (event) => {
  const files = event.target.files;
  if (files.length > 0) {
    const formData = new FormData();
    
    // Add files to form data
    Array.from(files).forEach(file => {
      formData.append('files[]', file);
    });
    
    // Get the uploader container
    const uploader = Phenix(event.target).ancestor('.px-uploader');
    
    try {
      // Send files to server
      const response = await fetch('/upload-endpoint', {
        method: 'POST',
        body: formData
      });
      
      const result = await response.json();
      console.log('Upload successful:', result);
    } catch (error) {
      console.error('Upload failed:', error);
    }
  }
});

Accessibility

The Files Upload component maintains accessibility features:

• Keyboard navigation for file selection
• Proper labeling for screen readers
• Focus states for keyboard users

Browser Compatibility

The Files Upload component is compatible with all modern browsers that support the File API and JavaScript ES6 features.