Styles

Style the uploader to match your application with CSS, Tailwind CSS, or CSS Modules.

Style the uploader and its child components with your application's CSS. The same interface works for single PUT and multipart uploads.

The uploader provides layout and state visibility. Style the child components directly, and use the documented CSS variables for the progress bar.

By default, <chunkify-uploader> uses a flex layout with flex-direction: column.

Configure the upload provider as shown in Get started. The examples use its createUpload function. For HTML, assign it to the element's upload property after rendering.

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

Keep a Start over control available for expired sessions and non-recoverable errors, as shown in Get started. The Retry component continues the retained attempt and only appears for recoverable errors.

Uploader components

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>`	Continue the failed attempt	Yes	Recoverable 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>`	Continue the failed attempt	Yes	Recoverable error
`<ChunkifyUploaderSuccess>`	Success message	Yes	Upload Success

Custom display properties

Setting display on a component can interfere with how it shows or hides during an upload.

For a flex or grid layout, wrap the component's content in a div and apply the display style to that wrapper.

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

Minimal example

This example shows an uploader with a single upload button.

<style>
    chunkify-uploader {
        width: min(100%, 28rem);
        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: 'min(100%, 28rem)',
        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>
    );
}

Complete interface

<style>
    chunkify-uploader {
        width: min(100%, 28rem);
        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: 'min(100%, 28rem)',
        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>
    );
}

Customize the progress bar

Use these CSS variables to change the progress bar's appearance and color:

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>

Use Tailwind CSS

In HTML, include Tailwind CSS and use the class attribute.

In React, apply Tailwind classes through className.

<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>

Use CSS Modules

In React, import your CSS module and pass its class through className:

// file-upload.module.css

.uploader {
    width: min(100%, 28rem);
    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>
    );
}

Style drag and drop

Enable drop to make the entire <chunkify-uploader> component a drop zone.

Use the dragover attribute to style the component while a file is dragged over it.

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

Chunkify Uploader exposes attributes that reflect its current upload state.

State	Attribute	Description
Initial	(none)	Initial status before a file is selected
Uploading	`uploading`	Session preparation, transfer, or completion
Completed	`success`	Completion confirmed and Source created
Error	`error`	Error during the upload process
Retry available	`error` and `retryable`	The failed step can continue with the retained file and session.

Use CSS attribute selectors to style each state.

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>
    )
}

Use events to customize the interface

Use upload-error to choose a message for your application. Custom error content takes priority over the uploader's fallback messages for transfer and completion errors.

<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>
    );
}

The example displays "Upload URL not found" for a 404 response and "Error during the upload" for other errors.

See Events for the available event handlers.

Displaying file information

File selection and upload success events give you access to the selected File object.

This example displays file information during the upload and after it succeeds.

Use the uploading attribute to show information only while the upload is in progress.

<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>