> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# File Uploader styling

> Create a custom look and feel for your File Uploader with easy-to-use styling customizations. Explore various options and basic CSS variables.

The File Uploader is designed to be easily customizable. We're using global CSS
styles and CSS variables to make it simple to change the look and feel of the
components. You can customize the File Uploader to match your brand's design by
changing the color scheme, fonts, icons, and other visual elements.

We use
[OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch). It
allows changing colors without compromising accessibility and has a wider color
range than RGB or HLS. OKLCH is supported in modern browsers; here is the
support table: [Can I use OKLCH](https://caniuse.com/mdn-css_types_color_oklch).

RGB fallback is also provided for older browsers.

> **Warning**
>
> **Warning:** Starting from the v0.44.0, the theming CSS API is changed. See the [migration guide](/docs/file-uploader/migration-to-0.44.0/) for more details.

> **Note**
>
> **Note:** Before the v0.40.0, the icons were defined as CSS custom properties. See the
> [migration guide](/docs/file-uploader/migration-to-0.40.0/) for more details.

> **Note**
>
> **Note:** Before the v0.39.0, the styles was working through the shadow styles. See the
> [migration guide](/docs/file-uploader/migration-to-0.39.0/) for more details.

## Quick customization

You can easily customize the File Uploader by switching between light and dark
themes. You can also change the primary color to match your brand's color.

### Theme (light/dark)

By default, it conforms to user preference through the media query. To force a
color scheme, apply the `uc-light` or the `uc-dark` class to the File Uploader.

```html
<uc-file-uploader-regular
  class="uc-dark"
  ctx-name="my-uploader"
></uc-file-uploader-regular>
```

### Primary color

Change these variables to represent your brand's color. The numbers stand for
Lightness, Chroma, and Hue, respectively. Don't change the Lightness value to
maintain the contrast level. We recommend using [oklch.com](http://oklch.com/)
to convert colors.

```css
.my-theme {
  --uc-primary-oklch-light: 59% 0.22 264;
  --uc-primary-oklch-dark: 69% 0.1768 258.4;
}
```

```html
<uc-file-uploader-regular
  class="my-theme"
  ctx-name="my-uploader"
></uc-file-uploader-regular>
```

### Upload button text

To override the upload button text, use `localeDefinitionOverride` option:

```js
<script type="module">
  const config = document.querySelector('uc-config');
  config.localeDefinitionOverride = {
    en: {
      'upload-file': 'New upload button text',
    }
  };
</script>
```

Learn more about [`localeDefinitionOverride` option](https://uploadcare.com/docs/file-uploader/localization/#locale-definition-override).

## Deep customization

You can customize variables like colors, fonts, and sizes. They are defined as
custom CSS properties.

All color values come in two variants with `-light` and `-dark` suffixes. For
example:

```css
.my-theme {
  --uc-background-light: oklch(100% 0 0);
  --uc-background-dark: oklch(22% 0 0);
}
```

### Upload button

`SimpleBtn` component is the default way to open the uploader dialog. It's
styled independently. Here are the available variables with their default
values:

```css
.my-theme {
  --uc-simple-btn-font-family: system-ui;
  --uc-simple-btn-font-size: 14px;
  --uc-simple-btn-padding: 7px 14px;

  /* Light colors */
  --uc-simple-btn-light: oklch(94% 0 0);
  --uc-simple-btn-hover-light: oklch(92% 0 0);
  --uc-simple-btn-foreground-light: oklch(20% 0 0);

  /* Dark colors */
  --uc-simple-btn-dark: oklch(26% 0 0);
  --uc-simple-btn-hover-dark: oklch(29% 0 0);
  --uc-simple-btn-foreground-dark: oklch(100% 0 0);
}
```

### Font and sizes

Here are the default values for fonts and sizes that you can customize using CSS
variables:

```css
.my-theme {
  --uc-font-family: system-ui;
  --uc-font-size: 14px;
  --uc-line-height: normal;
  --uc-button-size: 32px;
  --uc-preview-size: 32px;
  --uc-padding: 10px;
  --uc-radius: 8px;
  --uc-transition: 0.2s ease;
  --uc-dialog-width: 430px;
  --uc-dialog-max-width: 800px;
  --uc-dialog-max-height: 600px;

  /* SimpleBtn */
  --uc-simple-btn-font-family: system-ui;
  --uc-simple-btn-font-size: 14px;
  --uc-simple-btn-padding: 7px 14px;
}
```

### Light colors

Here are the default light colors that you can customize using CSS variables:

```css
.my-theme {
  --uc-background-light: oklch(100% 0 0);
  --uc-foreground-light: oklch(21% 0 0);
  --uc-primary-oklch-light: 59% 0.22 264;
  --uc-primary-light: oklch(var(--uc-primary-oklch-light));
  --uc-primary-hover-light: oklch(var(--uc-primary-oklch-light) / 90%);
  --uc-primary-transparent-light: oklch(var(--uc-primary-oklch-light) / 10%);
  --uc-primary-foreground-light: oklch(100% 0 0);
  --uc-secondary-light: oklch(21% 0 0 / 0.05);
  --uc-secondary-hover-light: oklch(21% 0 0 / 0.08);
  --uc-secondary-foreground-light: oklch(21% 0 0);
  --uc-muted-light: oklch(97% 0 0);
  --uc-muted-foreground-light: oklch(55% 0 0);
  --uc-destructive-light: oklch(59% 0.235 28.5 / 0.05);
  --uc-destructive-foreground-light: oklch(59% 0.235 28.5);
  --uc-border-light: oklch(92% 0 0);
  --uc-dialog-shadow-light: 0px 6px 20px oklch(0% 0 0 / 0.1);

  /* SimpleBtn */
  --uc-simple-btn-light: oklch(94% 0 0);
  --uc-simple-btn-hover-light: oklch(92% 0 0);
  --uc-simple-btn-foreground-light: oklch(20% 0 0);
}
```

### Dark colors

Here are the default dark colors that you can customize using CSS variables:

```css
.my-theme {
  --uc-background-dark: oklch(22% 0 0);
  --uc-foreground-dark: oklch(91% 0 0);
  --uc-primary-oklch-dark: 69% 0.1768 258.4;
  --uc-primary-dark: oklch(var(--uc-primary-oklch-dark));
  --uc-primary-hover-dark: oklch(var(--uc-primary-oklch-dark) / 90%);
  --uc-primary-transparent-dark: oklch(var(--uc-primary-oklch-dark) / 7.5%);
  --uc-primary-foreground-dark: oklch(0% 0 0);
  --uc-secondary-dark: oklch(91% 0 0 / 0.07);
  --uc-secondary-hover-dark: oklch(91% 0 0 / 0.1);
  --uc-secondary-foreground-dark: oklch(91% 0 0);
  --uc-muted-dark: oklch(26% 0 0);
  --uc-muted-foreground-dark: oklch(68% 0 0);
  --uc-destructive-dark: oklch(67% 0.191 27.5 / 0.1);
  --uc-destructive-foreground-dark: oklch(67% 0.191 27.5);
  --uc-border-dark: oklch(36% 0 0);
  --uc-dialog-shadow-dark: 0px 6px 20px oklch(0% 0 0 / 0.25);

  /* SimpleBtn */
  --uc-simple-btn-dark: oklch(26% 0 0);
  --uc-simple-btn-hover-dark: oklch(29% 0 0);
  --uc-simple-btn-foreground-dark: oklch(100% 0 0);
}
```

### RGB fallback

We provide RGB fallback for older browsers. When you update the primary color
using OKLCH, the RGB fallback values remain the same as the default ones.

If you want to change the primary color for RGB fallback values too, you need to
place them in the separate `@supports` selector.

```css
@supports not (color: oklch(0 0 0)) {
  .my-theme {
    --uc-primary-rgb-light: 53.8 112 253;
    --uc-background-light: rgb(255 255 255);

    --uc-primary-rgb-dark: 80.5 153 255;
    --uc-background-dark: rgb(27 27 27);
  }
}

@supports (color: oklch(0 0 0)) {
  .my-theme {
    --uc-primary-oklch-light: 59% 0.22 264;
    --uc-background-light: oklch(100% 0 0);

    --uc-primary-oklch-dark: 69% 0.1768 258.4;
    --uc-background-dark: oklch(22% 0 0);
  }
}
```

There are two special CSS variables for the RGB primary color fallback:
`--uc-primary-rgb-light` and `--uc-primary-rgb-dark`.

### Files view

The File Uploader supports two views: `list` and `grid`. The default view is `list`.
However you can change it to `grid` using the [`filesViewMode`](/docs/file-uploader/options#files-view-mode) attribute.

```css
.my-theme {
  --uc-grid-col: 3; /* Number of columns in the grid */
  --uc-grid-preview-image-height: auto; /* Height of preview images */
  --uc-grid-gap: calc(var(--uc-padding) / 2); /* Gap between grid items */
  --uc-grid-aspect-ratio: 1 / 1; /* Aspect ratio of grid items */
}
```

## Specific elements customization

To customize some specific elements, you must find them using the browser
developer tools and apply custom CSS rules.

For example, to hide the "Clear" button in the upload list, you can use the
following CSS rule:

```css
uc-file-uploader-regular
  > uc-modal
  > uc-upload-list
  > .uc-toolbar
  > .uc-cancel-btn.uc-secondary-btn {
  display: none;
}
```

> **Warning**
>
> **Warning:** Internal DOM structure, attributes, CSS class names (like `.uc-toolbar`,
> `.uc-cancel-btn`, etc.) are **not part of the public API**. We may change them
> in minor or patch releases without a major version bump.
>
> We try to minimize such changes, but they can happen. After updating the
> package, verify that your custom styles and DOM-dependent logic still work as
> expected.
>
> Check the [Migration guides](/docs/file-uploader/migration/) for details on
> breaking changes in each release, and the
> [Changelog](https://github.com/uploadcare/file-uploader/blob/main/CHANGELOG.md)
> for a full history.
>
> This does not apply to the [Plugin API](/docs/file-uploader/plugins/) public
> selectors, which follow semver.

## Icons \[#icons]

We're using SVG sprites to display icons. All the default icons are bundled in
the package and injected into the DOM as a hidden SVG element on the
initialization stage.

To customize the icons, you can use the `iconHrefResolver` option. It's a
function that resolves the icon sprite URL by its name. The function receives
the icon name as an argument and should return the URL of the icon sprite.
Returned URL will be used as a `href` attribute of the `<use>` element in the
SVG icon.

Type definition: `(iconName: string) => (string | undefined)`

So, for example, we want to replace the `upload` icon with a custom one. To
achieve this, we need to create a custom icon sprite:

```html
<svg>
  <symbol
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
    id="my-custom-upload-icon"
  >
    <path
      fill="currentColor"
      fill-rule="evenodd"
      d="m11.5014.392135c.2844-.253315.7134-.253315.9978 0l6.7037 5.971925c.3093.27552.3366.74961.0611 1.05889-.2755.30929-.7496.33666-1.0589.06113l-5.4553-4.85982v13.43864c0 .4142-.3358.75-.75.75s-.75-.3358-.75-.75v-13.43771l-5.45427 4.85889c-.30929.27553-.78337.24816-1.0589-.06113-.27553-.30928-.24816-.78337.06113-1.05889zm-10.644466 16.336765c.414216 0 .749996.3358.749996.75v4.9139h20.78567v-4.9139c0-.4142.3358-.75.75-.75.4143 0 .75.3358.75.75v5.6639c0 .4143-.3357.75-.75.75h-22.285666c-.414214 0-.75-.3357-.75-.75v-5.6639c0-.4142.335786-.75.75-.75z"
    ></path>
  </symbol>
</svg>
```

Here we've created a custom icon sprite with the `my-custom-upload-icon` ID. Now
we need to host this sprite somewhere or inline it into the page.

Let's go with the hosting option. Place the sprite on your server and name it
`my-custom-icons.svg`. Now we can use the `iconHrefResolver` option to replace
the default `upload` icon with our custom one:

```js
const config = document.querySelector('uc-config');

config.iconHrefResolver = (iconName) => {
  if(iconName === 'upload') {
    // If you inline the sprite, you can return the ID only like
    // return '#my-custom-upload-icon'
    return './my-custom-icons.svg#my-custom-upload-icon';
  }
}
```

Now the File Uploader will use the custom icon for the upload button.

So how to know the name of the icon you want to replace? You could find the
needed `uc-icon` tag in the DOM and check the `name` attribute.

All available icons are listed in the repository:

* [File Uploader icons](https://github.com/uploadcare/file-uploader/tree/main/src/blocks/themes/uc-basic/icons)
* [Cloud Image Editor icons](https://github.com/uploadcare/file-uploader/tree/main/src/blocks/CloudImageEditor/src/icons)