Chunkify Uploader

Styles

Customize the uploader to match your design. Use of CSS overrides, CSS variables, Tailwind CSS, and CSS Modules.

Chunkify Uploader web component is built to be fully customizable to match you project design. It comes with sub components that you will need to use to and style.

You can and must override all components CSS except the progress bar where you must use the CSS variables provided to customize it.

By default the main component <chunkify-uploader> is just a flex box with a flex direction sets to column.

Configure the upload provider first, as shown in setup. The examples below use the same createUpload function. For HTML examples, assign document.querySelector('chunkify-uploader').upload = createUpload after rendering the element.

The uploading state includes session preparation and completion. The progress text remains a percentage and stays at 100% until completion succeeds or fails.

Chunkify Uploader Components List

Name	Description	CSS Override	Displayed When
`<chunkify-uploader>`	Main component	Yes	Always
`<chunkify-uploader-file-select>`	File selector button	Yes	Initial
`<chunkify-uploader-heading>`	Heading / Title	Yes	Initial
`<chunkify-uploader-progress-text>`	Progress Percent	Yes	Uploading
`<chunkify-uploader-progress-bar>`	Progress Bar	Use CSS variables	Uploading
`<chunkify-uploader-error>`	Error message	Yes	Upload Error
`<chunkify-uploader-retry>`	Reset to initital state button	Yes	Upload Error
`<chunkify-uploader-success>`	Success message	Yes	Upload Success

Name	Description	CSS Override	Displayed When
`<ChunkifyUploader>`	Main component	Yes	Always
`<ChunkifyUploaderFileSelect>`	File selector button	Yes	Initial
`<ChunkifyUploaderHeading>`	Heading / Title	Yes	Initial
`<ChunkifyUploaderProgressText>`	Progress Percent	Yes	Uploading
`<ChunkifyUploaderProgressBar>`	Progress Bar	Use CSS variables	Uploading
`<ChunkifyUploaderError>`	Error message	Yes	Upload Error
`<ChunkifyUploaderRetry>`	Reset to initital state button	Yes	Upload Error
`<ChunkifyUploaderSuccess>`	Success message	Yes	Upload Success

Custom display properties

Do not use display properties on the component itself, it may interfere with show/hide behavior during upload states.

When using custom display properties (like flex, grid, etc.) for internal layout, wrap your content in a div instead of applying the display class directly to the component.

This is ok:

<chunkify-uploader-file-select class="bg-blue-500 px-4 py-2 rounded">
    <div class="flex items-center gap-2">
        <svg>...</svg>
        Select File
    </div>
</chunkify-uploader-file-select>

This is not ok:

<chunkify-uploader-file-select
    class="bg-blue-500 px-4 py-2 rounded flex items-center gap-2"
>
    <svg>...</svg>
    Select File
</chunkify-uploader-file-select>

Examples

Minimalistic example

Here is a very basic uploader component example with just a button to upload a file.

<style>
    chunkify-uploader {
        width: 10%;
        align-items: center;
        justify-content: center;
    }

    chunkify-uploader-file-select {
        background: #007bff;
        color: white;
        border: none;
        padding: 4px;
        cursor: pointer;
        text-align: center;
        width: 100%;
    }

</style>

<script src="https://cdn.jsdelivr.net/npm/@chunkify/uploader"></script>

<chunkify-uploader>
    <chunkify-uploader-file-select>Select a File</chunkify-uploader-file-select>
    <chunkify-uploader-progress-text></chunkify-uploader-progress-text>
    <chunkify-uploader-error>Upload failed</chunkify-uploader-error>
    <chunkify-uploader-success>Upload successful!</chunkify-uploader-success>
</chunkify-uploader>
import {
    ChunkifyUploader,
    ChunkifyUploaderFileSelect,
    ChunkifyUploaderProgressText,
    ChunkifyUploaderError,
    ChunkifyUploaderSuccess,
} from '@chunkify/uploader/react';

export default function App() {
    const uploaderStyle = {
        width: '30%',
        alignItems: 'center',
        justifyContent: 'center',
    };

    const fileSelectStyle = {
        background: '#007bff',
        width: '100%',
        color: 'white',
        border: 'none',
        padding: '4px',
        cursor: 'pointer',
        textAlign: 'center',
    };

    return (
        <ChunkifyUploader
            style={uploaderStyle}
            upload={createUpload}
        >
            <ChunkifyUploaderFileSelect style={fileSelectStyle}>
                Select a file
            </ChunkifyUploaderFileSelect>
            <ChunkifyUploaderProgressText />
            <ChunkifyUploaderError>Upload Error</ChunkifyUploaderError>
            <ChunkifyUploaderSuccess>Upload Success!</ChunkifyUploaderSuccess>
        </ChunkifyUploader>
    );
}

Full components use HTML Example

<style>
    chunkify-uploader {
        width: 30%;
        height: 100px;
        margin: 0 auto;
        gap: 8px;
        align-items: center;
        justify-content: center;
        border: 2px dashed #ccc;
        padding: 8px;
    }

    chunkify-uploader[dragover] {
        border-color: #007bff;
        background: #e3f2fd;
    }

    chunkify-uploader-file-select {
        background: #007bff;
        width: 40%;
        color: white;
        padding: 12px;
        border-radius: 8px;
        cursor: pointer;
        font-size: 16px;
        align-self: center;
        text-align: center;
    }

    chunkify-uploader-retry {
        background: #dc3545;
        color: white;
        border-radius: 8px;
        cursor: pointer;
        width: 20%;
        padding: 8px;
        text-align: center;
        align-self: center;
    }
</style>
<script src="https://cdn.jsdelivr.net/npm/@chunkify/uploader"></script>

<chunkify-uploader
    drop
>
    <chunkify-uploader-heading> Drop your file here </chunkify-uploader-heading>
    <chunkify-uploader-file-select> Select File </chunkify-uploader-file-select>
    <chunkify-uploader-progress-text></chunkify-uploader-progress-text>
    <chunkify-uploader-progress-bar></chunkify-uploader-progress-bar>
    <chunkify-uploader-error> Error during upload </chunkify-uploader-error>
    <chunkify-uploader-retry> Retry </chunkify-uploader-retry>
    <chunkify-uploader-success> Upload successful </chunkify-uploader-success>
</chunkify-uploader>
import {
    ChunkifyUploader,
    ChunkifyUploaderHeading,
    ChunkifyUploaderFileSelect,
    ChunkifyUploaderProgressText,
    ChunkifyUploaderProgressBar,
    ChunkifyUploaderError,
    ChunkifyUploaderRetry,
    ChunkifyUploaderSuccess
} from '@chunkify/uploader/react';

export default function MyUploader() {
    const uploaderStyle = {
        width: '30%',
        height: '100px',
        margin: '0 auto',
        gap: '8px',
        alignItems: 'center',
        justifyContent: 'center',
        border: '2px dashed #ccc',
        padding: '8px'
    };

    const fileSelectStyle = {
        background: '#007bff',
        width: '40%',
        color: 'white',
        padding: '12px',
        borderRadius: '8px',
        cursor: 'pointer',
        fontSize: '16px',
        alignSelf: 'center',
        textAlign: 'center'
    };

    const retryStyle = {
        background: '#dc3545',
        color: 'white',
        borderRadius: '8px',
        cursor: 'pointer',
        width: '20%',
        padding: '8px',
        textAlign: 'center',
        alignSelf: 'center'
    };

    return (
        <ChunkifyUploader
            style={uploaderStyle}
            upload={createUpload}
            drop
        >
            <ChunkifyUploaderHeading>Drop your file here</ChunkifyUploaderHeading>
            <ChunkifyUploaderFileSelect style={fileSelectStyle}>
                Select File
            </ChunkifyUploaderFileSelect>
            <ChunkifyUploaderProgressText />
            <ChunkifyUploaderProgressBar />
            <ChunkifyUploaderError>Error during upload</ChunkifyUploaderError>
            <ChunkifyUploaderRetry style={retryStyle}>
                Retry
            </ChunkifyUploaderRetry>
            <ChunkifyUploaderSuccess>Upload successful</ChunkifyUploaderSuccess>
        </ChunkifyUploader>
    );
}

Use of CSS variables to customize the progress bar

The progress bar has a default appareance and color but some CSS variables are available to customize the component. This allows you to tweak the progress bar appearance:

Name	CSS Property	Description
`--progress-fill-color`	`background-color`	Color of the progress bar
`--progress-background`	`background-color`	Background color of the progress bar
`--progress-height`	`height`	Height of the progress bar
`--progress-width`	`width`	Width of the progress bar
`--progress-radius`	`border-radius`	Radius of the progress bar
`--progress-border`	`border`	Border of the progress bar

You can use them like this:

<style>
    chunkify-uploader {
        --progress-fill-color: red;
        --progress-background: blue;
        --progress-height: 10px;
    }
</style>

<chunkify-uploader>...</chunkify-uploader>

<ChunkifyUploader
    upload={createUpload}
    style={{
        '--progress-fill-color': 'red',
        '--progress-background': 'blue',
        '--progress-height': '10px',
    }}
>
</ChunkifyUploader>

Using Tailwind CSS

HTML : Include Tailwind CSS and use the class attribute

React : You can use Tailwind CSS with the classNameattribute.

<script src="https://cdn.tailwindcss.com"></script>

<chunkify-uploader
    class="
        h-1/2
        bg-white
        [&[dragover]]:bg-blue-100
        [&[uploading]]:bg-orange-100
        [--progress-fill-color:green]
    "
>
    <!-- Rest of components -->
</chunkify-uploader>
<ChunkifyUploader
    upload={createUpload}
    className="
            h-1/2
            bg-white
            [&[dragover]]:bg-blue-100
            [&[uploading]]:bg-orange-100
            [--progress-fill-color:green]
            "
    drop
>
   ...
</ChunkifyUploader>

Using CSS Modules

One way of styling in React is to use CSS-in-JS, for example, using CSS modules:

// file-upload.module.css

.uploader {
    width: 30%;
    height: 100px;
    margin: 0 auto;
    align-items: center;
    justify-content: center;
    border: 2px dashed #ccc;
    padding: 12px;
}


// Your App
import { ChunkifyUploader } from '@chunkify/uploader/react';
import styles from './file-upload.module.css';

export default function App() {
    return (
        <ChunkifyUploader
            className={styles.uploader}
            upload={createUpload}
        >
            ...
        </ChunkifyUploader>
    );
}

Enabling and customizing drag and drop UI

If you enable drag and drop uploads using the attribute / property drop, the drag and drop zone will be the entire <chunkify-uploader> component.

You can use the attribute dragoverto style your component appropriately.

In React you can use CSS-in-JS, for example, using CSS modules.

Here is a full example with drag and drop enabled.

<style>
    chunkify-uploader {
            ...
    }

    chunkify-uploader[dragover] {
            border-color: #007bff;
            background: #e3f2fd;
    }
</style>

<chunkify-uploader drop>
       ...
</chunkify-uploader>

// styles.modules.css
.uploader {
       ...
}

.uploader[dragover] {
        border-color: #007bff;
        background: #e3f2fd;
}

// Your app
import styles from './styles.modules.css';
import { ChunkifyUploader } from '@chunkify/uploader/react';
export default function App() {

    return (
        <ChunkifyUploader className={styles.uploader} upload={createUpload} drop>
            ...
        </ChunkifyUploader>
    )
}

Use attributes for state-driven customization

Chukify Uploader uses properties and attributes to manage different states changes during the upload process.

State	Attribute	Description
Initial	(none)	Initial status before a file is selected
Uploading	`uploading`	Upload in progress
Completed	`success`	Completion confirmed and Source created
Error	`error`	Error during the upload process

This allows to use attribute selectors for state-driven styling via CSS.

In React you can use CSS-in-JS, for example, using CSS modules.

Here is a basic example where we change the background color of the uploader when the upload is completed or in error:

<style>
    chunkify-uploader[success] {
        background: green;
    }

    chunkify-uploader[error] {
        background: red;
    }

</style>

<chunkify-uploader></chunkify-uploader>

// styles.modules.css
.uploader {
       ...
}

.uploader[success] {
        background: green;
}

.uploader[error] {
        background: red;
}

// Your app
import styles from './styles.modules.css';
import { ChunkifyUploader } from '@chunkify/uploader/react';
export default function App() {

    return (
        <ChunkifyUploader className={styles.uploader} upload={createUpload}>
            ...
        </ChunkifyUploader>
    )
}

Using Events to customize UI

You can further customize UI by using events. For example, you can write a custom common error message that will display when an upload error occurs but you can fine tune it depending on the detail of the event. Here a basic example of how to do that :

<chunkify-uploader>
    <chunkify-uploader-file-select>Select a File</chunkify-uploader-file-select>
    <chunkify-uploader-progress-text></chunkify-uploader-progress-text>
    <chunkify-uploader-error> Error during the upload</chunkify-uploader-error>
    <chunkify-uploader-success>Upload Success!</chunkify-uploader-success>
</chunkify-uploader>

<script>
    const uploader = document.querySelector('chunkify-uploader');
    const errorMsg = document.querySelector('chunkify-uploader-error');

    uploader.addEventListener('upload-error', (e) => {
              if (e.detail.status === 404) {errorMsg.textContent = "Upload URL not found"};
        });
</script>

import { useState } from 'react';
import {
    ChunkifyUploader,
    ChunkifyUploaderFileSelect,
    ChunkifyUploaderProgressText,
    ChunkifyUploaderError,
    ChunkifyUploaderSuccess,
} from '@chunkify/uploader/react';

export default function UploadForm() {
    const [errorMessage, setErrorMessage] = useState('Error during the upload');

    return (
        <ChunkifyUploader
            upload={createUpload}
            onUploadError={(e) => {
                setErrorMessage(e.detail.status === 404
                    ? 'Upload URL not found'
                    : 'Error during the upload');
            }}
        >
            <ChunkifyUploaderFileSelect>Select a File</ChunkifyUploaderFileSelect>
            <ChunkifyUploaderProgressText />
            <ChunkifyUploaderError>{errorMessage}</ChunkifyUploaderError>
            <ChunkifyUploaderSuccess>Upload Success!</ChunkifyUploaderSuccess>
        </ChunkifyUploader>
    );
}

So here the error message will be "Error during the upload" except if the status code is 404 in which case it will display "Upload URL not found".

There are two ways to work with events you can learn more about it in the Events Handling section.

Displaying file information

When your user select a file or when the upload completes successfully, you have access to the File object through the event.

Here is an example on how you can display these infos during the upload and on upload success.

You will need to to use the uploading attribute to display the info only during the upload process.

<style>
    .my-file-info {
        color: #666;
        font-size: 16px;
        margin: 10px 0;
        font-style: italic;
        display: none;
    }

    chunkify-uploader[uploading] .my-file-info {
        display: block;
    }
</style>

<chunkify-uploader drop>
    <chunkify-uploader-heading class="my-title">Drop your file here</chunkify-uploader-heading>
    <chunkify-uploader-file-select>Select File</chunkify-uploader-file-select>
    <div class="my-file-info"></div>
    <chunkify-uploader-progress-text class="my-progress-text"></chunkify-uploader-progress-text>
    <chunkify-uploader-progress-bar></chunkify-uploader-progress-bar>
    <chunkify-uploader-error class="my-error">Error during upload</chunkify-uploader-error>
    <chunkify-uploader-success class="my-success">Upload successful</chunkify-uploader-success>
</chunkify-uploader>

<script>
     const uploader = document.querySelector('chunkify-uploader');

    // Use to display file info during the upload
     uploader.onFileSelected = (e) => {
            const fileInfo = document.querySelector('.my-file-info');
            const sizeInMB = (e.detail.file.size / (1024 * 1024)).toFixed(2);
            fileInfo.textContent = `Uploading: ${e.detail.file.name} (${sizeInMB} MB)`;
        }

    // Use to display file info on upload success
    uploader.onUploadSuccess = (e) => {
            const success = document.querySelector('chunkify-uploader-success');
            success.textContent = `Upload successful for ${e.detail.file.name}`;
        }
</script>