API Reference

Complete API reference for @uploadkitdev/react — all components, hooks, and types.

UploadKitProvider

Context provider. Wrap your app (or upload UI) with this to make the SDK client available to all child components and hooks.

function UploadKitProvider(props: UploadKitProviderProps): JSX.Element

UploadKitProviderProps

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

useUploadKit

Headless upload state machine hook. Must be used inside <UploadKitProvider>.

function useUploadKit(route: string): {
  upload: (file: File, metadata?: Record<string, unknown>) => Promise<void>;
  abort: () => void;
  reset: () => void;
  status: 'idle' | 'uploading' | 'success' | 'error';
  progress: number;
  error: Error | null;
  result: UploadResult | null;
  isUploading: boolean;
}

Return	Type	Description
`upload`	`(file: File, metadata?) => Promise<void>`	Upload a file. Aborts any existing in-progress upload first.
`abort`	`() => void`	Cancel the current upload and reset to idle.
`reset`	`() => void`	Reset state to idle.
`status`	`'idle' \| 'uploading' \| 'success' \| 'error'`	Current upload lifecycle state.
`progress`	`number`	Progress percentage (0–100).
`error`	`Error \| null`	Last error. Null when not in error state.
`result`	`UploadResult \| null`	Last upload result. Null when not in success state.
`isUploading`	`boolean`	`status === 'uploading'`.

UploadButton

const UploadButton: React.ForwardRefExoticComponent<UploadButtonProps & React.RefAttributes<HTMLButtonElement>>

UploadButtonProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types for the file input.
`maxSize`	`number`	—	Max file size in bytes (client-side validation).
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(result: UploadResult) => void`	—	Called after successful upload.
`onUploadError`	`(error: Error) => void`	—	Called on upload failure.
`variant`	`'default' \| 'outline' \| 'ghost'`	`'default'`	Visual style variant.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size variant.
`disabled`	`boolean`	`false`	Disables the button.
`className`	`string`	—	CSS class(es) for the outer wrapper.
`appearance`	`Partial<Record<'button' \| 'progressBar' \| 'progressText', string>>`	—	CSS class overrides for inner elements.
`config`	`{ mode?: 'auto' \| 'manual' }`	`{ mode: 'auto' }`	Controls when the upload begins after file selection. `auto` uploads immediately; `manual` stages files for user confirmation.
`onBeforeUploadBegin`	`(files: File[]) => File[] \| Promise<File[]>`	—	Transform or filter files before upload. Return empty array to cancel.
`uploadProgressGranularity`	`'coarse' \| 'fine' \| 'all'`	`'coarse'`	How frequently `onUploadProgress` is called during upload.
`children`	`ReactNode`	—	Custom button label.

UploadDropzone

const UploadDropzone: React.ForwardRefExoticComponent<UploadDropzoneProps & React.RefAttributes<HTMLDivElement>>

UploadDropzoneProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types. Wildcards supported: `'image/*'`.
`maxSize`	`number`	—	Max file size in bytes (client-side validation).
`maxFiles`	`number`	—	Max number of files per drop or selection.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(results: UploadResult[]) => void`	—	Called after all files upload successfully.
`onUploadError`	`(error: Error) => void`	—	Called when any file upload fails.
`disabled`	`boolean`	`false`	Disables the dropzone.
`className`	`string`	—	CSS class(es) for the outer wrapper.
`config`	`{ mode?: 'auto' \| 'manual' }`	`{ mode: 'manual' }`	Controls when the upload begins after file selection. `manual` stages files with a confirm button; `auto` uploads immediately on drop or selection.
`onBeforeUploadBegin`	`(files: File[]) => File[] \| Promise<File[]>`	—	Transform or filter files before upload. Return empty array to cancel.
`uploadProgressGranularity`	`'coarse' \| 'fine' \| 'all'`	`'coarse'`	How frequently `onUploadProgress` is called during upload.
`appearance`	`Partial<Record<'container' \| 'label' \| 'icon' \| 'fileItem' \| 'progressBar' \| 'button', string>>`	—	CSS class overrides for inner elements.

UploadDropzoneGlass

const UploadDropzoneGlass: React.ForwardRefExoticComponent<UploadDropzoneGlassProps & React.RefAttributes<HTMLDivElement>>

Premium variant inspired by Vercel and Linear. Frosted glass, hairline borders, indigo glow halo on drag-over. See UploadDropzoneGlass for the full guide.

UploadDropzoneGlassProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types. Wildcards supported.
`maxSize`	`number`	—	Max file size in bytes.
`maxFiles`	`number`	—	Max number of files per drop.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(results: UploadResult[]) => void`	—	Called after all files upload.
`onUploadError`	`(error: Error) => void`	—	Called once per failed file.
`disabled`	`boolean`	`false`	Disables drag, click, and the file input.
`className`	`string`	—	CSS class(es) for the outer wrapper.
`children`	`ReactNode`	—	Custom heading.

UploadDropzoneAurora

const UploadDropzoneAurora: React.ForwardRefExoticComponent<UploadDropzoneAuroraProps & React.RefAttributes<HTMLDivElement>>

Animated conic-gradient mesh with a cursor-follow specular highlight. See UploadDropzoneAurora.

UploadDropzoneAuroraProps

Same shape as UploadDropzoneGlassProps (route, accept, maxSize, maxFiles, metadata, onUploadComplete, onUploadError, disabled, className, children).

UploadDropzoneTerminal

const UploadDropzoneTerminal: React.ForwardRefExoticComponent<UploadDropzoneTerminalProps & React.RefAttributes<HTMLDivElement>>

Monospace terminal-style dropzone with a blinking cursor and tail-style log. See UploadDropzoneTerminal.

UploadDropzoneTerminalProps

Same shape as UploadDropzoneGlassProps.

UploadDropzoneBrutal

const UploadDropzoneBrutal: React.ForwardRefExoticComponent<UploadDropzoneBrutalProps & React.RefAttributes<HTMLDivElement>>

Neobrutalist dropzone with thick borders, a hard shadow offset, and a stamp-down animation. See UploadDropzoneBrutal.

UploadDropzoneBrutalProps

Same shape as UploadDropzoneGlassProps.

UploadButtonShimmer

const UploadButtonShimmer: React.ForwardRefExoticComponent<UploadButtonShimmerProps & React.RefAttributes<HTMLButtonElement>>

CTA upload button with a shimmer sweep and indigo glow on hover. See UploadButtonShimmer.

UploadButtonShimmerProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types for the file input.
`maxSize`	`number`	—	Max file size in bytes.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(result: UploadResult) => void`	—	Called after successful upload.
`onUploadError`	`(error: Error) => void`	—	Called on upload failure.
`disabled`	`boolean`	`false`	Disables the button.
`className`	`string`	—	CSS class(es) for the button.
`children`	`ReactNode`	—	Custom label.

UploadButtonMagnetic

const UploadButtonMagnetic: React.ForwardRefExoticComponent<UploadButtonMagneticProps & React.RefAttributes<HTMLButtonElement>>

Pill-shaped upload button that attracts toward the cursor with a Motion spring. See UploadButtonMagnetic.

UploadButtonMagneticProps

Same shape as UploadButtonShimmerProps.

UploadAvatar

const UploadAvatar: React.ForwardRefExoticComponent<UploadAvatarProps & React.RefAttributes<HTMLDivElement>>

Circular avatar uploader with blur-up preview and an SVG progress ring. See UploadAvatar.

UploadAvatarProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	`['image/*']`	MIME types.
`maxSize`	`number`	—	Max file size in bytes.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`initialSrc`	`string`	—	Initial avatar image URL.
`size`	`number`	`96`	Width and height in pixels.
`onUploadComplete`	`(result: UploadResult) => void`	—	Called after successful upload.
`onUploadError`	`(error: Error) => void`	—	Called on upload failure.
`className`	`string`	—	CSS class(es) for the outer wrapper.

UploadInlineChat

const UploadInlineChat: React.ForwardRefExoticComponent<UploadInlineChatProps & React.RefAttributes<HTMLDivElement>>

ChatGPT-style composer with a paperclip attach button and animated file chips. See UploadInlineChat.

UploadInlineChatProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types. Wildcards supported.
`maxSize`	`number`	—	Max file size in bytes.
`maxFiles`	`number`	—	Max number of files per selection.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(results: UploadResult[]) => void`	—	Called after all files upload.
`onUploadError`	`(error: Error) => void`	—	Called once per failed file.
`placeholder`	`string`	`'Send a message...'`	Placeholder for the message field.
`className`	`string`	—	CSS class(es) for the outer wrapper.

All eight premium variants above depend on motion as an optional peerDependency. Without it they render a static fallback; install it with pnpm add motion to enable the full animation set.

Motion & Progress variants

Eight motion-forward upload affordances shipped in quick task 260410-kw3. All use CSS custom properties for theming, respect prefers-reduced-motion, and expose full ARIA progress semantics.

UploadProgressRadial

const UploadProgressRadial: React.ForwardRefExoticComponent<UploadProgressRadialProps & React.RefAttributes<HTMLDivElement>>

Activity-ring style radial progress with pathLength fill and a success splash. See UploadProgressRadial.

UploadProgressRadialProps

Prop	Type	Default	Description
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	MIME types.
`maxSize`	`number`	—	Max file size in bytes.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`size`	`number`	`120`	Diameter of the ring in pixels.
`strokeWidth`	`number`	`6`	Ring stroke width.
`label`	`string`	`'Upload'`	Center label when idle.
`onUploadComplete`	`(result: UploadResult) => void`	—	Called after successful upload.
`onUploadError`	`(error: Error) => void`	—	Called on upload failure.
`className`	`string`	—	CSS class(es) for the outer wrapper.

UploadProgressBar

const UploadProgressBar: React.ForwardRefExoticComponent<UploadProgressBarProps & React.RefAttributes<HTMLDivElement>>

Horizontal progress bar with shimmer sweep, indeterminate state, and a bounce-check on success. See UploadProgressBar.

UploadProgressBarProps

Prop	Type	Default	Description
`route`	`string`	—	Required.
`accept`	`string[]`	—	MIME types.
`maxSize`	`number`	—	Max file size in bytes.
`metadata`	`Record<string, unknown>`	—	Forwarded metadata.
`indeterminate`	`boolean`	`false`	Force indeterminate sliding state.
`showPercent`	`boolean`	`true`	Show percent label.
`buttonLabel`	`string`	`'Select file'`	CTA label.
`onUploadComplete`	`(result: UploadResult) => void`	—	Success callback.
`onUploadError`	`(error: Error) => void`	—	Failure callback.
`className`	`string`	—	CSS class(es).

UploadProgressStacked

const UploadProgressStacked: React.ForwardRefExoticComponent<UploadProgressStackedProps & React.RefAttributes<HTMLDivElement>>

Multi-file vertical progress list where completed rows float to the top. Inspired by iOS AirDrop. See UploadProgressStacked.

UploadProgressStackedProps

Same shape as UploadDropzoneGlassProps (route, accept, maxSize, maxFiles, metadata, onUploadComplete, onUploadError, className, children).

UploadProgressOrbit

const UploadProgressOrbit: React.ForwardRefExoticComponent<UploadProgressOrbitProps & React.RefAttributes<HTMLDivElement>>

Circular orbit of satellites that collapse to the center as each upload completes. See UploadProgressOrbit.

UploadProgressOrbitProps

Same shape as UploadProgressStackedProps, plus radius?: number (default 80).

UploadCloudRain

const UploadCloudRain: React.ForwardRefExoticComponent<UploadCloudRainProps & React.RefAttributes<HTMLDivElement>>

Cloud icon that fills as progress advances, with droplets raining down as files are picked. See UploadCloudRain.

UploadCloudRainProps

Same shape as UploadProgressStackedProps.

UploadBento

const UploadBento: React.ForwardRefExoticComponent<UploadBentoProps & React.RefAttributes<HTMLDivElement>>

CSS grid bento layout — every third cell spans 2 columns. Inspired by Apple iPadOS widgets. See UploadBento.

UploadBentoProps

Same shape as UploadProgressStackedProps (minus children), plus columns?: number (default 3).

UploadParticles

const UploadParticles: React.ForwardRefExoticComponent<UploadParticlesProps & React.RefAttributes<HTMLDivElement>>

Constellation of particles converging to the center as upload progress advances. Pure CSS transforms. See UploadParticles.

UploadParticlesProps

Same shape as UploadProgressStackedProps (minus children), plus particleCount?: number (default 40).

UploadStepWizard

const UploadStepWizard: React.ForwardRefExoticComponent<UploadStepWizardProps & React.RefAttributes<HTMLDivElement>>

5-stage single-file upload wizard (select → preview → confirm → upload → done). See UploadStepWizard.

UploadStepWizardProps

Same shape as UploadAvatarProps (minus accept default, initialSrc, size).

All eight motion & progress variants use CSS fallbacks for their animations — motion is only required for the smooth layout reorders in UploadProgressStacked and UploadBento, and the AnimatePresence-driven transitions in UploadStepWizard.

UploadModal

function UploadModal(props: UploadModalProps): JSX.Element

UploadModalProps

Prop	Type	Default	Description
`open`	`boolean`	—	Required. Controls modal visibility.
`onClose`	`() => void`	—	Required. Called on ESC or backdrop click.
`route`	`string`	—	Required. Route name from the file router.
`accept`	`string[]`	—	Accepted MIME types.
`maxSize`	`number`	—	Max file size in bytes.
`maxFiles`	`number`	—	Max number of files.
`metadata`	`Record<string, unknown>`	—	Metadata forwarded to the server.
`onUploadComplete`	`(results: UploadResult[]) => void`	—	Called after all files upload successfully.
`onUploadError`	`(error: Error) => void`	—	Called when any upload fails.
`className`	`string`	—	CSS class(es) for the `<dialog>` element.
`title`	`string`	—	Heading text and `aria-label` for the dialog.
`appearance`	`Partial<Record<'modal' \| 'backdrop' \| 'content' \| 'container' \| 'label' \| 'icon' \| 'fileItem' \| 'progressBar' \| 'button', string>>`	—	CSS class overrides for inner elements.

FileList

function FileList(props: FileListProps): JSX.Element

FileListProps

Prop	Type	Required	Description
`files`	`UploadResult[]`	Yes	Array of upload results to display.
`onDelete`	`(fileKey: string) => void`	No	Delete button handler. Hidden when not provided.
`className`	`string`	No	CSS class(es) for the list wrapper.
`appearance`	`Partial<Record<'list' \| 'item' \| 'preview' \| 'name' \| 'size' \| 'deleteButton', string>>`	No	CSS class overrides for inner elements.

FilePreview

function FilePreview(props: FilePreviewProps): JSX.Element

FilePreviewProps

Prop	Type	Required	Description
`file`	`File \| UploadResult`	Yes	File to preview.
`className`	`string`	No	CSS class(es) for the container.
`appearance`	`Partial<Record<'container' \| 'image' \| 'icon', string>>`	No	CSS class overrides.

useDragState

Hook for drag-and-drop state management. Uses an integer counter (not boolean) to prevent flickering on child element drag events.

function useDragState(
  onDrop: (files: File[]) => void
): {
  isDragging: boolean;
  handlers: {
    onDragEnter: (e: React.DragEvent) => void;
    onDragLeave: (e: React.DragEvent) => void;
    onDragOver: (e: React.DragEvent) => void;
    onDrop: (e: React.DragEvent) => void;
  };
}

useAutoDismiss

Hook that manages a list of items with auto-removal after a delay.

function useAutoDismiss<T extends { id: string }>(
  delay: number
): [items: T[], add: (item: T) => void, remove: (id: string) => void]

useThumbnail

Hook that generates a thumbnail URL for a File using URL.createObjectURL (images) or canvas frame capture (videos). Defers generation until the container is visible using IntersectionObserver.

function useThumbnail(
  file: File,
  containerRef: React.RefObject<HTMLElement | null>
): {
  thumbnailUrl: string | null;
  isGenerating: boolean;
}

generateReactHelpers

Type-safe factory that narrows the route prop to the literal keys of your file router.

function generateReactHelpers<TRouter extends FileRouter>(): {
  UploadButton: React.ComponentType<Omit<UploadButtonProps, 'route'> & { route: keyof TRouter & string }>;
  UploadDropzone: React.ComponentType<Omit<UploadDropzoneProps, 'route'> & { route: keyof TRouter & string }>;
  UploadModal: React.ComponentType<Omit<UploadModalProps, 'route'> & { route: keyof TRouter & string }>;
  useUploadKit: (route: keyof TRouter & string) => ReturnType<typeof useUploadKit>;
}

Usage:

import { generateReactHelpers } from '@uploadkitdev/react';
import type { AppFileRouter } from '@/app/api/uploadkit/[...uploadkit]/route';

export const { UploadButton, UploadDropzone, UploadModal, useUploadKit } =
  generateReactHelpers<AppFileRouter>();

CSS custom properties

See the full Theming reference for all CSS variables, their defaults in light and dark mode, and what they control.

Variable	Light	Dark	Controls
`--uk-primary`	`#0070f3`	`#0070f3`	Buttons, borders, focus rings
`--uk-primary-hover`	`#005bb5`	`#005bb5`	Hover states
`--uk-bg`	`#ffffff`	`#0a0a0b`	Component backgrounds
`--uk-bg-secondary`	`#fafafa`	`#141416`	Secondary backgrounds
`--uk-border`	`#eaeaea`	`rgba(255,255,255,0.08)`	Borders
`--uk-text`	`#171717`	`#fafafa`	Primary text
`--uk-text-secondary`	`#666666`	`#a1a1aa`	Secondary text
`--uk-success`	`#00c853`	`#00c853`	Success states
`--uk-error`	`#dc2626`	`#dc2626`	Error states
`--uk-radius`	`12px`	`12px`	Border radius
`--uk-font`	System UI	System UI	Font family
`--uk-transition`	`200ms ease-out`	`200ms ease-out`	Transitions

VERSION

import { VERSION } from '@uploadkitdev/react';
// '0.1.0'

API Reference

On this page