Skip to content

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:

html
<!-- 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:

html
<!-- 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:

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:

html
<!-- 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:

html
<!-- 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:

html
<!-- 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:

html
<!-- 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:

css
.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:

html
<!-- 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:

html
<!-- 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 ​

javascript
// 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 ​

OptionTypeDefaultDescription
typeString'standard'Uploader type: 'standard' or 'advanced'
srcStringundefinedOptional default media source URL

Available Data Attributes ​

AttributeTypeDefaultDescription
data-uploaderString'standard'Uploader type: 'standard' or 'advanced'
data-placeholderString'Drag and Drop your file to upload'Custom placeholder text
data-btnString'Browse'Text for the browse button (standard uploader only)
data-multipleBooleanfalseEnable multiple file selection (alternative to the 'multiple' attribute)

CSS Classes ​

The component uses these CSS classes for styling and functionality:

ClassDescription
px-uploaderMain container class for the uploader component
form-controlApplied to standard uploader for form styling
highlightAdded when dragging files over the uploader
image-modeAdded when an image file is selected (shows image preview)
video-modeAdded when a video file is selected (shows video player)
px-doneAdded 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:

javascript
// 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:

javascript
// 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.

Released under the MIT License.