File Uploader styling

Starting from the v0.44.0, the theming CSS API is changed. See the migration guide for more details.
Before the v0.40.0, the icons were defined as CSS custom properties. See the migration guide for more details.
Before the v0.39.0, the styles was working through the shadow styles. See the migration guide for more details.

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. 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.

RGB fallback is also provided for older browsers.

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.

1<uc-file-uploader-regular
2  class="uc-dark"
3  ctx-name="my-uploader"
4></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 to convert colors.

1.my-theme {
2  --uc-primary-oklch-light: 59% 0.22 264;
3  --uc-primary-oklch-dark: 69% 0.1768 258.4;
4}
1<uc-file-uploader-regular
2  class="my-theme"
3  ctx-name="my-uploader"
4></uc-file-uploader-regular>

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:

1.my-theme {
2  --uc-background-light: oklch(100% 0 0);
3  --uc-background-dark: oklch(22% 0 0);
4}

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:

1.my-theme {
2  --uc-simple-btn-font-family: system-ui;
3  --uc-simple-btn-font-size: 14px;
4  --uc-simple-btn-padding: 7px 14px;
5
6  /* Light colors */
7  --uc-simple-btn-light: oklch(94% 0 0);
8  --uc-simple-btn-hover-light: oklch(92% 0 0);
9  --uc-simple-btn-foreground-light: oklch(20% 0 0);
10
11  /* Dark colors */
12  --uc-simple-btn-dark: oklch(26% 0 0);
13  --uc-simple-btn-hover-dark: oklch(29% 0 0);
14  --uc-simple-btn-foreground-dark: oklch(100% 0 0);
15}

Font and sizes

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

1.my-theme {
2  --uc-font-family: system-ui;
3  --uc-font-size: 14px;
4  --uc-line-height: normal;
5  --uc-button-size: 32px;
6  --uc-preview-size: 32px;
7  --uc-padding: 10px;
8  --uc-radius: 8px;
9  --uc-transition: 0.2s ease;
10  --uc-dialog-width: 430px;
11  --uc-dialog-max-width: 800px;
12  --uc-dialog-max-height: 600px;
13
14  /* SimpleBtn */
15  --uc-simple-btn-font-family: system-ui;
16  --uc-simple-btn-font-size: 14px;
17  --uc-simple-btn-padding: 7px 14px;
18}

Light colors

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

1.my-theme {
2  --uc-background-light: oklch(100% 0 0);
3  --uc-foreground-light: oklch(21% 0 0);
4  --uc-primary-oklch-light: 59% 0.22 264;
5  --uc-primary-light: oklch(var(--uc-primary-oklch-light));
6  --uc-primary-hover-light: oklch(var(--uc-primary-oklch-light) / 90%);
7  --uc-primary-transparent-light: oklch(var(--uc-primary-oklch-light) / 10%);
8  --uc-primary-foreground-light: oklch(100% 0 0);
9  --uc-secondary-light: oklch(21% 0 0 / 0.05);
10  --uc-secondary-hover-light: oklch(21% 0 0 / 0.08);
11  --uc-secondary-foreground-light: oklch(21% 0 0);
12  --uc-muted-light: oklch(97% 0 0);
13  --uc-muted-foreground-light: oklch(55% 0 0);
14  --uc-destructive-light: oklch(59% 0.235 28.5 / 0.05);
15  --uc-destructive-foreground-light: oklch(59% 0.235 28.5);
16  --uc-border-light: oklch(92% 0 0);
17  --uc-dialog-shadow-light: 0px 6px 20px oklch(0% 0 0 / 0.1);
18
19  /* SimpleBtn */
20  --uc-simple-btn-light: oklch(94% 0 0);
21  --uc-simple-btn-hover-light: oklch(92% 0 0);
22  --uc-simple-btn-foreground-light: oklch(20% 0 0);
23}

Dark colors

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

1.my-theme {
2  --uc-background-dark: oklch(22% 0 0);
3  --uc-foreground-dark: oklch(91% 0 0);
4  --uc-primary-oklch-dark: 69% 0.1768 258.4;
5  --uc-primary-dark: oklch(var(--uc-primary-oklch-dark));
6  --uc-primary-hover-dark: oklch(var(--uc-primary-oklch-dark) / 90%);
7  --uc-primary-transparent-dark: oklch(var(--uc-primary-oklch-dark) / 7.5%);
8  --uc-primary-foreground-dark: oklch(0% 0 0);
9  --uc-secondary-dark: oklch(91% 0 0 / 0.07);
10  --uc-secondary-hover-dark: oklch(91% 0 0 / 0.1);
11  --uc-secondary-foreground-dark: oklch(91% 0 0);
12  --uc-muted-dark: oklch(26% 0 0);
13  --uc-muted-foreground-dark: oklch(68% 0 0);
14  --uc-destructive-dark: oklch(67% 0.191 27.5 / 0.1);
15  --uc-destructive-foreground-dark: oklch(67% 0.191 27.5);
16  --uc-border-dark: oklch(36% 0 0);
17  --uc-dialog-shadow-dark: 0px 6px 20px oklch(0% 0 0 / 0.25);
18
19  /* SimpleBtn */
20  --uc-simple-btn-dark: oklch(26% 0 0);
21  --uc-simple-btn-hover-dark: oklch(29% 0 0);
22  --uc-simple-btn-foreground-dark: oklch(100% 0 0);
23}

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.

1@supports not (color: oklch(0 0 0)) {
2  .my-theme {
3    --uc-primary-rgb-light: 53.8 112 253;
4    --uc-background-light: rgb(255 255 255);
5
6    --uc-primary-rgb-dark: 80.5 153 255;
7    --uc-background-dark: rgb(27 27 27);
8  }
9}
10
11@supports (color: oklch(0 0 0)) {
12  .my-theme {
13    --uc-primary-oklch-light: 59% 0.22 264;
14    --uc-background-light: oklch(100% 0 0);
15
16    --uc-primary-oklch-dark: 69% 0.1768 258.4;
17    --uc-background-dark: oklch(22% 0 0);
18  }
19}

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

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:

1uc-file-uploader-regular
2  > uc-modal
3  > uc-upload-list
4  > .uc-toolbar
5  > .uc-cancel-btn.uc-secondary-btn {
6  display: none;
7}

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:

1<svg>
2  <symbol
3    fill="none"
4    xmlns="http://www.w3.org/2000/svg"
5    viewBox="0 0 24 24"
6    id="my-custom-upload-icon"
7  >
8    <path
9      fill="currentColor"
10      fill-rule="evenodd"
11      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"
12    ></path>
13  </symbol>
14</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:

1const config = document.querySelector('uc-config');
2
3config.iconHrefResolver = (iconName) => {
4  if(iconName === 'upload`) {
5    // If you inline the sprite, you can return the ID only like
6    // return '#my-custom-upload-icon'
7    return './my-custom-icons.svg#my-custom-upload-icon';
8  }
9}

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: