@mux/mux-uploader
Advanced tools
An uploader elements to be used with Mux Direct Uploads
<mux-uploader> is web component for uploading files to Mux.
<mux-uploader-drop> is an optional supporting container-style web component for drag and drop. You can always configure your own drag and drop with <mux-uploader>.
If you are looking for a direct upload interface and a progress bar, you're in the right place.
If you're using npm or yarn, install that way:
yarn add @mux/mux-uploader
or
npm i @mux/mux-uploader
Then, import the library into your application with either import or require:
import '@mux/mux-uploader';
or
require('@mux/mux-uploader');
Alternatively, use the CDN hosted version of this package:
<script src="https://unpkg.com/@mux/mux-uploader"></script>
If you are using ECMAScript modules, you can also load the mux-uploader.mjs file with type=module:
<script type="module" src="https://unpkg.com/@mux/mux-uploader/dist/mux-uploader.mjs"></script>
<body>
<!-- Upload button by itself with default drag an drop scoped to the space it takes up. Displays upload progress in text as percentage.-->
<mux-uploader url="authenticated-url" type="bar" status></mux-uploader>
<!-- Upload button by itself with drag an drop disabled. Does not display text percentage.-->
<mux-uploader url="authenticated-url" type="bar" disable-drop></mux-uploader>
<!-- Upload button with access to optional supplentary drag and drop features..-->
<mux-uploader-drop mux-uploader="uploader" overlay overlay-text="Show this while dragging file over me">
<mux-uploader id="uploader" url="authenticated-url"></mux-uploader>
<div>Other stuff you want in the mux-uploader-drop drop zone container</div>
</mux-uploader-drop>
</body>
<mux-uploader-drop> is available for drag and drop functionality. It works like a <div> or other "container" element in the sense that you can style it and populate it with whatever children you see fit (including but not necessarily a <mux-uploader>). Similar to <input> and <label> relationships, you associate a <mux-uploader-drop> with its corresponding <mux-uploader> via id using the mux-uploader attribute (See example above). When a file is dropped, this will dispatch a custom file-ready event to the corresponding <mux-uploader> with the relevant file.
This also means you can implement your own drag and drop (or other) components for specific use cases, so long as you dispatch a custom file-ready event when you need to upload. <mux-uploader> will handle the upload upon receiving the event.
<script>
const muxUploader = document.querySelector('mux-uploader');
// Dispatch custom event to trigger upload
muxUploader.dispatchEvent(
new CustomEvent('file-ready', {
composed: true,
bubbles: true,
detail: file,
})
);
</script>
<mux-uploader>| Attribute | Type | Description | Default |
|---|---|---|---|
url | string | The authenticated URL that your file will be uploaded to. Check out the direct uploads docs for how to create one. Required. | undefined |
id | string | An ID that allows mux-uploader-drop to locate mux-uploader. Required if you use mux-uploader-drop. | N/A |
type | "bar" | Specifies the visual type of progress bar. A radial type is in-progress. | "bar" |
upload-in-progress | boolean | (Read-only) Toggles visual status of progress bar while upload is in progress. Can be targeted with CSS if you want to control styles while in progress i.e. mux-uploader[upload-in-progress]. | false |
upload-error | boolean | (Read-only) Toggles visual status of progress bar when upload encounters an error. Can be targeted with CSS if you want to control styles when an error occurs i.e. mux-uploader[upload-error]. | false |
status | boolean | Toggles text status visibility of progress bar. The text that is displayed is a percentage by default. If you prefer just the progress bar with no text upload status, don't include this attribute. | false |
<mux-uploader-drop>| Attribute | Type | Description | Default |
|---|---|---|---|
overlay | boolean | Toggles showing an overlay on dragover. | false |
overlay-text | boolean | Optional text to display on dragover when overlay is on. | '' |
mux-uploader | string | Must match the id on MuxUploader. Required. | N/A |
<mux-uploader>| Attribute | Type | Description | Default |
|---|---|---|---|
formatProgress | function | A function that accepts numeric percent and is expected to return a string. Allows for customizing how the progress should be rendered. | A function the yields a percent progress string |
<mux-uploader><mux-uploader> has a handful of events to monitor uploading state.
| Event | Description |
|---|---|
error | Fired when an error occurs in the chunked upload process. |
progress | Fired whenever a chunk of the file has successfully completed uploading. |
success | Fired when the entire file has successfully completed uploading. |
<mux-uploader> and <mux-uploader-drop> can be styled with standard CSS, but also includes these CSS variables for "under the hood" styling.
<mux-uploader>| Name | CSS Property | Default Value | Description | Notes |
|---|---|---|---|---|
--uploader-font-family | font-family | Arial | font family of the component | Applies to other elements as well: upload status and error status |
--uploader-font-size | font-size | 16px | font size for text within the component | Also applies to <mux-uploader-drop> i.e. overlay text |
--uploader-background-color | background-color | inherit | background color of area surrounding the upload | |
--button-background-color | background | #fff | background color of upload button | |
--button-border-radius | border-radius | 4px | border ardius of the upload button | |
--button-hover-text | color | #fff | text color of upload button on button hover | |
--button-hover-background | background | #404040 | background color of upload button on button hover | |
--button-active-text | color | #fff | color of upload button text when button is active | |
--button-active-background | background | #000000 | background color of upload button when button is active | Applied via :active pseudo selector |
--progress-bar-fill-color | background | #000000 | background color for progress bar div | |
--progress-radial-fill-color | stroke | black | stroke color for circle SVG (wip) |
<mux-uploader-drop/>| Name | CSS Property | Default Value | Description | Notes |
|---|---|---|---|---|
--overlay-background-color | background-color | rgba(226, 253, 255, 0.95) | background color of the overlay div | Visible only when component has fullscreen attribute |
FAQs
An uploader elements to be used with Mux Direct Uploads
The npm package @mux/mux-uploader receives a total of 3,163 weekly downloads. As such, @mux/mux-uploader popularity was classified as popular.
We found that @mux/mux-uploader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.