react

@medialit/react

A drop-in upload component and hook for MediaLit. Files go straight from the browser to MediaLit over the resumable tus protocol, so your API key stays on your server.

Install

npm install @medialit/react medialit

1. Add a signature route

The browser needs a short-lived upload signature from your backend. With Next.js:

// app/api/medialit/signature/route.ts
import { createSignatureHandler } from "medialit";
import { getSession } from "@/lib/auth"; // your app's auth

export const POST = createSignatureHandler({
    // Reads MEDIALIT_API_KEY and MEDIALIT_ENDPOINT from the environment.
    // Anyone who passes this check can upload to your MediaLit app.
    authorize: async (request) => !!(await getSession(request)),
});

Return { group: "..." } from authorize to put the files in a group.

2. Render the uploader

"use client";

import { MediaLitUploader } from "@medialit/react";
import "@medialit/react/styles.css";

export function AvatarUpload() {
    return (
        <MediaLitUploader
            signatureEndpoint="/api/medialit/signature"
            access="public"
            accept="image/*"
            maxFileSize={5 * 1024 * 1024}
            onUploadComplete={(media) => saveAvatar(media.mediaId)}
        />
    );
}

3. Seal the upload

Uploads are temporary and MediaLit deletes them after a while unless they are sealed. Seal on your server when the user saves, so files from abandoned forms are cleaned up for you:

import { MediaLit } from "medialit";

await new MediaLit().seal(mediaId);

Props

Prop	Type	Description
signatureEndpoint	string	Your route that returns { signature, endpoint }.
getSignature	() => Promise<{ signature, endpoint }>	Use instead of signatureEndpoint to fetch it yourself.
access	"public" | "private"	Defaults to private.
caption	string	Stored with the file.
accept	string	Same format as <input accept>. Also checked for drops.
maxFileSize	number	Bytes. MediaLit enforces your plan's limit as well.
chunkSize	number	Bytes per request. Defaults to one request.
onUploadComplete	(media) => void	Called with the uploaded media.
onUploadError	(error) => void	Called with a MediaLitUploadError.
labels	Partial<MediaLitUploaderLabels>	Replace any text, for example to translate it.
disabled	boolean
className	string	Added to the root element.

Styling

styles.css is optional. It styles the .medialit-uploader classes and follows the system's light or dark mode. Override its variables to match your app:

.medialit-uploader {
    --medialit-accent: #0f766e;
    --medialit-radius: 6px;
}

The root element has data-status set to idle, uploading, success, or error.

Build your own UI

useMediaLitUpload has the same upload logic without any markup:

import { useMediaLitUpload } from "@medialit/react";

function UploadButton() {
    const { upload, cancel, status, progress, error } = useMediaLitUpload({
        signatureEndpoint: "/api/medialit/signature",
    });

    if (status === "uploading") {
        return (
            <button onClick={cancel}>Cancel ({Math.round(progress)}%)</button>
        );
    }
    return (
        <>
            <input
                type="file"
                onChange={(e) =>
                    e.target.files?.[0] && upload(e.target.files[0])
                }
            />
            {error && <p>{error.message}</p>}
        </>
    );
}

upload(file) resolves to the media, or null if the upload failed or was cancelled. It never rejects.

For a framework other than React, use @medialit/uploader.