Theming

Components use CSS custom properties (not Tailwind classes) so they work in any React project, not just Tailwind projects.

CSS custom properties

All visual properties are controlled by CSS variables. Override them on :root or any ancestor element to theme the components.

Token reference

Variable	Light default	Dark default	Controls
`--uk-primary`	`#0070f3`	`#0070f3`	Button background, dropzone border on hover, progress bar, focus rings
`--uk-primary-hover`	`#005bb5`	`#005bb5`	Button background on hover
`--uk-bg`	`#ffffff`	`#0a0a0b`	Component background
`--uk-bg-secondary`	`#fafafa`	`#141416`	File item backgrounds, icon container backgrounds
`--uk-border`	`#eaeaea`	`rgba(255,255,255,0.08)`	Borders and dividers
`--uk-text`	`#171717`	`#fafafa`	Primary text color
`--uk-text-secondary`	`#666666`	`#a1a1aa`	Secondary text, labels, hints
`--uk-success`	`#00c853`	`#00c853`	Success state (checkmark, button after upload)
`--uk-error`	`#dc2626`	`#dc2626`	Error state (X icon, button on failure, toast text)
`--uk-radius`	`12px`	`12px`	Border radius on buttons, dropzone, modal, file items
`--uk-font`	System UI stack	System UI stack	Font family for all component text
`--uk-transition`	`200ms ease-out`	`200ms ease-out`	Transition duration and easing

Overriding tokens

Set variables on :root to change them globally, or on a specific ancestor to scope them:

/* Global override */
:root {
  --uk-primary: #7c3aed;        /* Purple instead of blue */
  --uk-primary-hover: #6d28d9;
  --uk-radius: 8px;             /* Less rounded */
}

/* Scoped override — only affects components inside .upload-area */
.upload-area {
  --uk-primary: #059669;        /* Green for this section only */
}

Dark mode

Dark mode works in two ways:

Automatic (prefers-color-scheme): The background, border, and text tokens switch automatically based on the system preference. No code required.

Explicit (data-theme attribute): Set data-theme="dark" on <html> (or any ancestor) to force dark mode regardless of system preference:

app/layout.tsx

<html lang="en" data-theme="dark">

Or toggle dynamically:

document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');

The --uk-primary, --uk-success, and --uk-error tokens are the same in light and dark mode by default. Only the background, border, and text tokens change.

Full brand color override

:root {
  /* Primary — your brand color */
  --uk-primary: #7c3aed;
  --uk-primary-hover: #6d28d9;

  /* Softer radius for a more conservative look */
  --uk-radius: 6px;

  /* Custom font stack */
  --uk-font: 'Inter', -apple-system, sans-serif;
}

@media (prefers-color-scheme: dark) {
  :root {
    /* Lighten primary slightly for better contrast on dark bg */
    --uk-primary: #a78bfa;
    --uk-primary-hover: #8b5cf6;
  }
}

Tailwind integration

Use the className prop to add Tailwind utility classes to the outer wrapper, and the appearance prop to target inner elements:

<UploadButton
  route="imageUploader"
  className="w-full"
  appearance={{
    button: 'rounded-full font-semibold tracking-tight',
    progressBar: 'h-0.5',
    progressText: 'text-xs tabular-nums',
  }}
/>

<UploadDropzone
  route="imageUploader"
  className="border-dashed"
  appearance={{
    container: 'min-h-48 rounded-2xl',
    label: 'text-sm',
    icon: 'opacity-60',
    fileItem: 'bg-neutral-50 dark:bg-neutral-900/50',
  }}
/>

For deeper customization, override CSS variables in your Tailwind theme:

/* globals.css or your Tailwind CSS file */
@layer base {
  :root {
    --uk-primary: theme(colors.violet.600);
    --uk-primary-hover: theme(colors.violet.700);
    --uk-radius: theme(borderRadius.lg);
  }
}

Every rendered element in @uploadkitdev/react components has a data-uk-element attribute. You can use CSS attribute selectors to target and restyle specific elements without overriding CSS custom properties.

Element names

Attribute value	Element
`uk-button`	The upload button
`uk-dropzone`	The dropzone container
`uk-modal`	The modal dialog
`uk-file-list`	The list of staged/uploaded files
`uk-file-item`	A single file row
`uk-progress`	The progress bar track
`uk-overlay`	The modal backdrop

data-state values

Elements also carry a data-state attribute reflecting the current upload lifecycle:

Value	Meaning
`idle`	No upload in progress
`uploading`	Upload in progress
`complete`	Upload finished successfully
`error`	Upload failed

Direct CSS targeting

/* Style the button */
[data-uk-element="uk-button"] {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
  border-radius: 999px;
}

/* Style the dropzone when dragging */
[data-uk-element="uk-dropzone"][data-state="uploading"] {
  opacity: 0.6;
  pointer-events: none;
}

/* Style file items */
[data-uk-element="uk-file-item"] {
  background: #f8f9fa;
  border-radius: 8px;
}

Tailwind withUk wrapper

For Tailwind CSS users, @uploadkitdev/next ships a withUk plugin that generates Tailwind variants matching the data-uk-element and data-state attributes.

Setup

Add withUk to your Tailwind CSS config:

/* globals.css (Tailwind v4) */
@import "tailwindcss";
@plugin "@uploadkitdev/next/tailwind";

Or for Tailwind v3:

// tailwind.config.js
const { withUk } = require('@uploadkitdev/next/tailwind');

module.exports = withUk({
  content: ['./src/**/*.{ts,tsx}'],
  theme: { extend: {} },
  plugins: [],
});

Available variants

Variant	Targets
`uk-button:`	`[data-uk-element="uk-button"]`
`uk-dropzone:`	`[data-uk-element="uk-dropzone"]`
`uk-modal:`	`[data-uk-element="uk-modal"]`
`uk-file-list:`	`[data-uk-element="uk-file-list"]`
`uk-file-item:`	`[data-uk-element="uk-file-item"]`
`uk-progress:`	`[data-uk-element="uk-progress"]`
`uk-overlay:`	`[data-uk-element="uk-overlay"]`
`uk-idle:`	`[data-state="idle"]`
`uk-uploading:`	`[data-state="uploading"]`
`uk-complete:`	`[data-state="complete"]`
`uk-error:`	`[data-state="error"]`

Usage examples

<UploadButton
  route="imageUploader"
  className="uk-button:rounded-full uk-button:bg-violet-600 uk-uploading:opacity-50"
/>

<UploadDropzone
  route="imageUploader"
  className="uk-error:border-red-500 uk-error:bg-red-50"
/>

CSS custom properties (--uk-accent, --uk-radius, etc.) remain the recommended approach for color and spacing overrides. data-uk-element targeting is best suited for structural or layout changes that can't be expressed as token values.

CSS keyframes

The package defines these animations (used internally):

Keyframe	Used by
`uk-spin`	Spinning loader in `UploadButton` during upload
`uk-modal-enter`	Modal scale-in on open
`uk-modal-exit`	Modal scale-out on close
`uk-fade-in`	File item appearance, error toast appearance
`uk-progress-indeterminate`	Progress bar indeterminate state

Reduced motion

All component transitions and animations are gated on prefers-reduced-motion. When the user has enabled reduced motion in their OS, durations drop to 0.01ms — effectively instant with no flicker.

@media (prefers-reduced-motion: reduce) {
  .uk-button,
  .uk-dropzone,
  .uk-modal,
  /* ... all component elements */
  {
    transition-duration: 0.01ms !important;
    animation-duration: 0.01ms !important;
  }
}