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.