Swiff meets Ajax for powerful and elegant uploads. FancyUpload is a file-input replacement which features an unobtrusive, multiple-file selection menu and queued upload with an animated progress bar. It is easy to setup, is server independent, completely styleable via CSS and XHTML and uses MooTools to work in all modern browsers.
- Attach a File A reduced and snappier interface (preview).
- Queued Photo Uploader Showcase with converted FancyUpload.
- Single File Button A simple implementation of the Swiff.Uploader class
- Select and upload multiple files
- Filter files by type in the select dialog
- A lot of possible Events to add your own behaviour
- Show and filter useful file information before the upload starts
- Limit uploads by file count, type or size
- Platform and server independent, just needs Flash 9+ (> 95% penetration)
- Graceful Degradation, since the element is replaced after the Flash is loaded successfully
- Cancel running uploads, add files during upload
- Everything is optional, documented and easy editable
- New in 2.0
- Get the server response after upload for showing additional informations or previewing the image, etc.
- Shows the current upload speed and the time left
- Send additional request data via GET or POST variables
- Set the filename for the upload request
- New in 3.0 (Completely rewritten API)
- Fully Flash 9 and 10 compatible and an additional IFrame-based uploader
- Browse-button can be an invisible overlay or an interactive image sprite
- Event based Flash communication, future-proof und more stable
- File-specific options for setting url, data and method, intelligently merged
- Append cookies automatically to the request data
- Relative URLs are converted automatically
How to use
The available showcases show off documented code snippets with various use cases.
var uploader = new Swiff.Uploader([options]);
- options - (object, optional) See options below. Also inherited are all the options from Swiff.
- (object|false) - New Swiff.Uploader instance.
- path - (string: defaults to “Swiff.Uploader.swf”) The relative or absolute path to the Flash movie (Swiff.Uploader.swf) on the server
- height: (number: defaults to 30) Only needed if you use buttonImage, otherwise its handled positioned over the target.
- width: (number: defaults to 100) Only needed if you use buttonImage, otherwise its handled positioned over the target.
- typeFilter: (object|string: defaults to null) Key/value pairs are used as filters for the dialog. Possible pair would be
'Images (*.jpg, *.jpeg, *.gif, *.png)': '*.jpg; *.jpeg; *.gif; *.png'.
- multiple: (boolean: defaults to true) If true, the browse-dialog allows multiple-file selection.
- queued: (number: defaults to 1) Maximum of currently running files. If this is false, all files are uploaded at once.
- verbose: (boolean: defaults to false) Debug mode, logs messages and all events from Flash during development (using console.info).
- target: (element: defaults to null) If given, the browse-element is overlayed with a transparent movie. The Events click/mouseenter/mouseleave/disabled are fired as events on target.
- zIndex: (number: defaults to 9999) Only used if a target is given, this sets the z-index for the overlay.
- buttonImage: (string: defaults to null) Sprite for the upload button, has to have 4 states vertically aligned: Normal, hovered, clicked and disabled. Make sure to adapt the options width and height.
- policyFile: (string: defaults to null) Location the cross-domain policy file. See Flash Security.loadPolicyFile.
- url: (string: defaults to null) URL to the server-side script (relative URLs are changed automatically to absolute paths).
- method: (string: defaults to ‘post’) If the method is ‘get’, data is appended as query-string to the URL. The upload will always be a POST request.
- data: (object|string: defaults to null) Key/data values that are sent with the upload requests.
- mergeData: (boolean: defaults to true) If true, the data option from uploader and file is merged (prioritised file data).
- fieldName: (string: defaults to “Filedata”) The key of the uploaded file on your server, similar to name in a file-input. Linux Flash ignores it, better avoid it.
- fileSizeMin: (number: defaults to 1) Validates the minimal size of a selected file byte.
- fileSizeMax: (number: defaults to 0) Validates the maximal size of a selected file (official limit is 100 MB for FileReference, I tested up to 2 GB)
- allowDuplicates: (boolean: defaults to false) Validates that no duplicate files are added.
- timeLimit: (number: default 30, 0 for linux) Timeout in seconds. If the upload is without progress, it is cancelled and event
completegets fired (with error string
timeout). Occurs usually when the server sends an empty response (also on redirects).
- fileList: (boolean: defaults to false) Validates that no duplicate files are added.
- fileListMax: (number: defaults to 0) Validates the overall file count.
- fileListSizeMax: (number: defaults to 0) Validates the overall file size in byte.
- instantStart: (boolean: defaults to false) If true, the upload starts right after a successful file selection.
- appendCookieData: (boolean|string: defaults to false) If this is not false, the cookies of the browser are merged into the given options data. If a string is given, it is used as key for the data.
- fileClass: (class: defaults to Swiff.Uploader.File) An instance of this class is created for every selected file.
The options url, method, data and mergeData are also available in
If you don’t set them per-file, they default to the options in your
To change them during runtime, simply use
setOptions and it does all the magic for you.
- load - (function) Function to execute when the Flash movie is initialised.
- fail - (function) Function to execute when the loading is prevented. First argument is the error type and can be:
flash- Flash is not installed or the Flash version did not meet the requirements.
blocked- The user has to enable the movie manually because of Flashblock, no refresh required.
empty- The Flash movie failed to load, check if the file exists and the
hidden- Adblock Plus blocks hides the movie, the user has enable it and refresh.
- start - (function) Function to execute when the upload starts.
- queue - (function) Function to execute when the queue statistics are updated.
- complete - (function) Function to execute when all files are uploaded (or stopped).
- browse - (function) Function to execute when the browse-dialog opens.
- disabledBrowse - (function) Function to execute when the user tries to open the browse-dialog, but the uploader is disabled.
- cancel - (function) Function to execute when the user closes the browse-dialog without a selection.
- select - (function) Function to execute when the user selected files in the dialog. Preferred events are selectSuccess and selectFail!
- successFiles - (array|null) Raw file data for successfully added files.
- failFiles - (array|null) Raw file data for invalid files that were not added.
- selectSuccess - (function) Function to execute when files were selected and validated successfully.
- successFiles - (array|null) Added file instances (see option fileClass).
- selectFail - (function) Function to execute when files were selected and failed validation.
- failFiles - (array|null) Dismissed file instances (see option fileClass).
- reposition - (function) Function to execute when
repositionmethod is called on uploader (usually on window-resize).
- beforeStart - (function) Function to execute when
startmethod is called on uploader.
- beforeStop - (function) Function to execute when
stopmethod is called on uploader.
- beforeRemove - (function) Function to execute when
removemethod is called on uploader.
- buttonEnter - (function) Function to execute when the mouse enters the browse button.
- buttonLeave - (function) Function to execute when the mouse leave the browse button.
- buttonDown - (function) Function to execute when the mouse clicks the browse button.
- buttonDisable - (function) Function to execute when the script disables the browse button.
- fileStart - (function) Function to execute when flash initialised the upload for a file.
- fileStop - (function) Function to execute when a file got stopped manually.
- fileRequeue - (function) Function to execute when a file got added back to the queue after being stopped or completed.
- fileOpen - (function) Function to execute when the file is accessed before for upload.
- fileProgress - (function) Function to execute when the upload reports progress.
- fileComplete - (function) Function to execute when a file is uploaded or failed with an error.
- fileRemove - (function) Function to execute when a file got removed.
Every Event starting with
file is also called on the
Swiff.Uploader.File class, without prepended
Swiff.Uploader Method: start
Starts the upload process. Also available in
Swiff.Uploader Method: stop
Stops all running files. Also available in
Swiff.Uploader Method: remove
Remove all files from the list. Also available in
Swiff.Uploader Method: reposition
Updates the position for the movie overlay, if you use option
- coordinates - (object, optional) New coordinates (left/top/width/height), automatically detected from the current target.
Swiff.Uploader Method: setEnabled
Enables or disables the browse button.
- status - (boolean, optional) Toggles the current status if no value if provided, otherwise updates the status to the given value.
Swiff.Uploader Property: target
The target Element from the options, override it if you switch your browser button.
Swiff.Uploader Property: uploading
The number of running uploads.
Swiff.Uploader Property: size
The overall size of all files in the list in byte.
Swiff.Uploader Property: bytesLoaded
The overall loaded size of running and completed files in the list in byte.
Swiff.Uploader Property: bytesLoaded
The overall loaded percentage of running and completed files in the list.
Swiff.Uploader Property: rate
The overall rate of running files in the list in bytes/second.
Mirrors several methods and events from the documentation above. Custom
file classes usually extends it and are given to
Swiff.Uploader via the
FAQ, Tips, Tricks, Quirks
- How do I access the uploaded files?
Every upload, even with multiple files, results in one request. Access the uploaded file via
- PHP: $_FILES[‘Filedata’]
- Perl: $main::cgi->param(‘Filedata’); … example
- Rails: params[:Filedata] … example
- ASP: Fancy Upload and Classic ASP
Filedata is the default value for the option
fieldName, so you can change it. The submitted
content-typeheader is always
application/octet-stream, so don’t trust it when you validate the file.
- Flash-request forgets cookies and session ID
appendCookieData. Flash FileReference is not an intelligent upload class, the request will not have the browser cookies, Flash saves his own cookies. When you have sessions, append them as get-data to the the URL (e.g. “upload.php?SESSID=123456789abcdef”). Of course your session-name can be different.
- Are cross-domain uploads possible?
For uploading and downloading operations, a SWF file can access files only within its own domain, including any domains that are specified by a cross-domain policy file. If the SWF that is initiating the upload or download doesn’t come from the same domain as the file server, you must put a policy file on the file server. More on security and link to cross-domain policies
- FancyUpload does not load, the input element gets not replaced
Check in Firebug in Net/Flash that the SWF file loads correctly. If not double check your given options.
- Uploads fail with 404 error code
Check your URL and better use an absolute upload URL.
IE takes the upload url relative to the swf, all other browsers relative to the html/current file. So the best solution is an absolute path for the option url or rather the form action. If you have problems with failed upload and 404 error codes, try an absolute url, in your form-action or url option when creating your FancyUpload instance.
- Uploads fail with 406/403 error
From the swfupload documentation (it applies to all Flash scripts depending on
If you are using Apache with mod_security this will not work, you need to put the following in your .htaccess file to disable mod_security:
SecFilterEngine Off SecFilterScanPOST Off
Disabling mod_security isn’t allowed on some shared hosts, and only do this if you know what you are doing. This is due to a bug in the way that flash sends the headers back to the server according to the Flash 8 documentation
- Uploads fail with 403/500 error
Check your server config, there must be something wrong. Also see 404, double check the upload URL.
- Uploads and Basic Authentication
Flash does not care about authenticated Browsers. Firefix/Win/Flash 9 can handle it, IE too, Mac can’t handle it. Anyways, Flash will ask for its own access username and password.
It does not depend on any server-side architecture or language.
You can include MooTools via Google AJAX Libraries API, follow the link for more information and why it can be good for your site.
- DomReady (facultative)
Don’t use compressed code during development to simplify debugging.
- Working FancyUpload Installation - The package that everybody waited for, a working FancyUpload to unpack and start play.
- Sources including Showcases - The source and all showcases from this page in one package, the package for web craftsmen ;).
- Swiff.Uploader.js - Flash based uploader, energizer for all possible upload interfaces
- Swiff.Uploader.swf - The movie used by the uploader class. Use right-click/save-as!
- FancyUpload2.js - The famous & fancy interface, converted to the new 3.0 API.
- Uploader.js - IFrame based class with the same API, but without progress.
- Fx.ProgressBar.js - Class to create and animate progress-bars.
- The images from the showcases are also downloadable.
- MooTools Forum: “Fancy Upload by digitarald” with 15 pages
- Jason: Flash Upload Progress for Rails with FancyUpload for mootools
- FileReference (flash.net.FileReference) - Version 9
- Ben Newton: Fancy Upload and Classic ASP
- 3.0 (2009-05-25)
- Added: Option timeLimit (default 30s, 0 for linux). Prevents frozen upload when server fails, after timeout the upload is cancelled and the complete event fired (with “timeout” error).
- Added: Option policyFile, custom location for the cross-domain policy.
- Added: Events beforeStart/Stop/Remove for more control over the upload process (e.g. setting data from inputs).
- Changed: 1s delay for onFail, prevents failing on slow connections.
- Fixed: data is not correctly merged between uploader options and file-specific options.
- Fixed: Removed debugging behaviour on progress bars.
- 3.0 rc1 (2009-05-05)
- Added: New showcase attach-a-file including first iteration of the class Attach.
- Added: New event
reposition, fired when the box is moved.
- Changed: More converted placeholder-units for validation errors.
- Fixed: remove event did not fire correctly, broke option
- Fixed: Example script.php did not clear log file correctly.
- Fixed: I really missed a console.log in FancyUpload2.js, sorry!
- 3.0 rc0 (2009-04-30)
- Added: Total rewrite of
- Added: Event based interactions from Flash to JS
- Added: File-based list handling for easy implementation
- Added: IFrame fallback class
Uploader.js, mirroring the
- Added: Several new options like
buttonImageand various validations
- Fixed: All known bugs (case-sensitive typeFilter, sending data, Mac problems, load events, …)
- Added: Total rewrite of
- 2.0 (2008-12-05)
- Added: Flash 10 support
- Added: removeFile now returns the new global progress status, to refresh numbers
- Fixed: Clickable overlay for Flash 10, define your target element with option “target”
- Fixed: Encoding problems fixed, JS calls failed due to ExternalInterface bugs (Kudos to SwfUpload for their short and efficient fix)
- Fixed: Cancelling a running file starts the next file
- Fixed: Enabled cross domain upload
- 2.0 beta 4 (2008-05-09)
- Fixed: Fixed
fileUploadto return changed options, fixes overriding options.
- Fixed: Fixed
- 2.0 beta 3 (2008-05-06)
- Added: Optional events for every callback (e.g. onSelect, onComplete, etc.) are added automatically for more control
- Added: Option
limitSize(default false) to limit file size (in bytes) of a single selected file
- Added: Option
limitFiles(default true) to limit queue length, ignores finished files
- Added: Option
allowDuplicates(default false) to disable duplicate files in queue (checking name and size)
- Added: Option
validateFileas custom callback validator (default returns always true). Should return true or false.
- Added: Optional callbacks for handling the file updates, allowing to control the behaviour and layout of the file elements:
fileInvalid: called for invalid files with error stack as 2nd argument
fileCreate: creates file element after select (see
FancyUpload2::fileCreatefor default method)
fileUpload: called when file is opened for upload, allows to modify the upload options (data, url, method, fieldName) for every upload.
fileComplete: updates the file element to completed state and gets the response (2nd argument) (see
FancyUpload2::fileCompletefor default method)
fileRemove: removes the element (see
FancyUpload2::fileRemovefor default method)
- Fixed: callback options are added as events , so they don’t break FancyUpload callbacks
- 2.0 preview 2 (2008-04-24)
- Fixed: Removed overflow auto from the lists to fix scrollbars.
- Fixed: Fixed overall progress file size for removed files.
- Fixed: New time left calculation, still needs some tweaks for the internal AS3 calculation.
- 2.0 preview (2008-04-21)
Refactored JS and ActionScript, it is not compatible with previous FancyUpload but a lot better!
- Added: New Interface using all the new features (will change in the future for easier customization)
- Added: Get the server response for uploaded files in onComplete, no longer error-catching with header status codes
- Added: Get the current states of uploads like time left, bytes upload, for the current file and per queue … for supreme progress bars
- Added: Set POST and GET data for the upload request
- Added: Set the file-name for the upload request, default Filedata, like before.
- Added: Set request options for every file, modify upload options with onBeforeOpen
- Added: New events: onAllSelect, onBeforeOpen and onAllComplete
- Changed: Update to MooTools 1.2 trunk and the modified Swiff Class
- Changed: Updated to Flash 9 + ActionScript 3 for a stable API with more features
- Fixed: Cache bug for IE, thanks to Flash 9
- Fixed: Scroll into view bug for Firefox, fixed wmode
- Fixed: Flash 9 works fine on Linux/Firefox
- 1.0.2 (2008-04-20)
- Fixed: Fixed IE errors when unloading the page by removing the element in Swiff.Base.js
- Fixed: Scroll into view bug for Firefox, fixed wmode
- 1.0.1 (2007-07-04)
- Added: Events onError and onCancel for files
- Change: Added better behaviour for onComplete and onAllComplete, now you can trust them
- Change: Removed internal empty onCancel, since Flash makes it useless and some other clean-ups
- Fixed: limitFiles works now and allowDuplicates is default true
- Fixed: Swiff.Uploader.js: Added anti-cache fix for IE and small improvements for parameters
- Fixed: FancyUpload.js: Fixed options in FancyUpload to work with MooTools 1.2dev
- 1.0 (2007-05-31)
- Changed: Added more checks to make SWF-JS communication more stable
- Changed: Swiff.Uploader options, swf is now the url to the swf and url the upload url
- Fixed: Fixed a bug with multiple uploaders on one page, they all work with one injected swf
- 1.0 pre (2007-05-23)
- Initial official Release
All files are © 2008-2009 by Harald Kirschner and available under the MIT License.
Contact & Discussion
For asking questions, requesting features, filing bugs or contributing other thoughts on this project use the support forum below. Before posting a new question, read through the documentation and the contributed notes for an answer. For problem reports make sure to add enough details like browser, version and a link or the relevant code.
You can contact me for non-support related notes.
I am available for hire if you look for professional and swift help. I can come to your rescue for installation, customization or extending the existing source for your needs.
Please use the support forums for discussing the project, asking questions or posting bug-fixes!