Installation

Add @uploadkitdev/react to your project and wrap your app with UploadKitProvider.

@uploadkitdev/react provides styled upload components, a headless hook, and helper utilities for building file upload UIs. It requires @uploadkitdev/core as a peer dependency.

Install

pnpm add @uploadkitdev/react @uploadkitdev/core

npm install @uploadkitdev/react @uploadkitdev/core

yarn add @uploadkitdev/react @uploadkitdev/core

React 18 or 19 is required. If you are using Next.js, also install @uploadkitdev/next for the server-side route handler.

Wrap your app with UploadKitProvider

Add UploadKitProvider at the root of your component tree (or the nearest ancestor of your upload UI). Point the endpoint prop at your local Next.js Route Handler — the API key lives there on the server and never reaches the browser:

app/layout.tsx

import { UploadKitProvider } from '@uploadkitdev/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UploadKitProvider endpoint="/api/uploadkit">
          {children}
        </UploadKitProvider>
      </body>
    </html>
  );
}

The provider creates an upload client exactly once using useRef and makes it available to all child components and hooks via React context.

CSS is auto-imported

Component styles are bundled with the package. No manual stylesheet import is required — the CSS is injected automatically when you use any component.

If you need to override styles or apply custom theming, you can target the CSS custom properties directly. See the Theming guide.

UploadKitProvider props

Prop	Type	Required	Description
`endpoint`	`string`	Yes	The local API route that proxies requests to the UploadKit API. Example: `"/api/uploadkit"`. Your API key is held server-side in this route handler — never in the browser.
`children`	`ReactNode`	Yes	The component tree that should have access to upload functionality.

Never pass your API key directly to UploadKitProvider. Use the endpoint prop instead — it points to your server-side route handler which holds UPLOADKIT_API_KEY. This ensures the key is never included in the browser bundle.

Next steps

UploadButton — one-click file uploads
UploadDropzone — drag-and-drop with multi-file support
useUploadKit — headless hook for custom UIs
Theming — CSS custom properties reference