use CSS custom properties for theming (aka css vars/css variables)

[renatodeleao]

problem
Overriding styles require a manual investigation of how your CSS specificity is done for several interactive scenarios. So the current way is to inspect the source code, copy the selector and do the override.

OverlayScrollbars/packages/overlayscrollbars/src/styles/scrollbars.scss

Lines 139 to 141 in 309ddd7

	.os-theme-dark.os-scrollbar:hover > .os-scrollbar-track > .os-scrollbar-handle {
	background: rgba(0, 0, 0, 0.55);
	}

solution
Using CSS custom properties you could hide the CSS implementation details from consumers and just let them know what variables are available to tweak the same way you do with javascript config options. Peaking on the previous example:

+  .os-theme-dark {
+    --os-scrollbar-track-bg-hover: rgba(0, 0, 0, 0.55);
+ }

 .os-theme-dark.os-scrollbar:hover > .os-scrollbar-track > .os-scrollbar-handle { 
-   background: rgba(0, 0, 0, 0.55); 
+   background: var(--os-scrollbar-track-bg-hover);
 } 

On my app I just need to override this variable the same way I do with plugin javascript options:

// my component/app
.os-theme-dark {
    --os-scrollbar-track-bg-hover: lime;
} 

Codesandbox demo

proposal
From a quick look, we're looking at "map" more or less like this:

.os-scrollbar {
   --os-scrollbar-size: 10px;
   --os-scrollbar-padding: 2px;
   --os-scrollbar-handle-radius: var(--os-scrollbar-size);
   // https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties
   // for handle::before (could be calc based on scrollbar size if necessary)
   --os-scrollbar-handle-min-size: 30px;
   --os-scrollbar-handle-block-offset: -6px;
   --os-scrollbar-handle-inline-offset: -2px;
}

.os-theme-dark {
   --os-scrollbar-track-bg-color: rgba(0,0,0,0);
   --os-scrollbar-track-bg-color-hover: rgba(0,0,0, 0.1);

   --os-scrollbar-handle-bg-color: green;
   --os-scrollbar-handle-bg-color-hover: lime;
   --os-scrollbar-handle-bg-color-active: orange;
}

.os-theme-light {
   // same with different colors
}

additional comments
This solution is opt-in, as in, consumers can still use regular CSS to override their styles if they prefer that way.

---

Let me know if this is something you're interested in and thanks for the work on the plugin! ✌️

[KingSora]

Good day @renatodeleao

I've considered this and I'm already working with custom css properties in the code (here and here) and the env() function is also detecting the browser support so I know when to fall back to something else.

That beeing said, as I'm still supporting IE11 which isn't supporting css custom properties the default would be to keep the scrollbar styles without css custom props. However I would be open for providing a second css file which support css custom props for the scrollbar styles and the consumer can then choose what to use.

[renatodeleao]

Good day! Good to know that it is on the radar!

That being said, as I'm still supporting IE11 which isn't supporting css custom properties

Uhhh unusual these days 😛 If I remember that correctly, declaring the hardcoded prop: value pair as a fallback before the one with the var would still work in IE because it would ignore the latter as an "invalid property declaration" while supporting browsers would just proceed as normal (using the latest declaration of the property)

.test {
   --bg: red;
   
  background-color: red; // for IE
  background-color: var(--bg); // IE will ignore it, and since everyone else supports this will be applied instead
}

There's a couple of postCSS plugins that handle it (here - more limited and here - more features) but providing a second file is also an option, but a bit more work to maintain I guess.

Anyways thanks for the quick reply! Let me know If I can help with something!

[KingSora]

@renatodeleao that looks like a nice proposal. I'll see what I can do :)

[KingSora]

@renatodeleao I've published version 2.1.0 where I implemented a set of Custom CSS Properties:

.os-scrollbar {
  // The size of the scrollbar
  --os-size: 0;
  // The axis-perpedicular padding of the scrollbar (horizontal: padding-y, vertical: padding-x)
  --os-padding-perpendicular: 0;
  // The axis padding of the scrollbar (horizontal: padding-x, vertical: padding-y)
  --os-padding-axis: 0;
  // The border radius of the scrollbar track
  --os-track-border-radius: 0;
  // The background of the scrollbar track
  --os-track-bg: none;
  // The :hover background of the scrollbar track
  --os-track-bg-hover: none;
  // The :active background of the scrollbar track
  --os-track-bg-active: none;
  // The border of the scrollbar track
  --os-track-border: none;
  // The :hover background of the scrollbar track
  --os-track-border-hover: none;
  // The :active background of the scrollbar track
  --os-track-border-active: none;
  // The border radius of the scrollbar handle
  --os-handle-border-radius: 0;
  // The background of the scrollbar handle
  --os-handle-bg: none;
  // The :hover background of the scrollbar handle
  --os-handle-bg-hover: none;
  // The :active background of the scrollbar handle
  --os-handle-bg-active: none;
  // The border of the scrollbar handle
  --os-handle-border: none;
  // The :hover border of the scrollbar handle
  --os-handle-border-hover: none;
  // The :active border of the scrollbar handle
  --os-handle-border-active: none;
  // The min size of the scrollbar handle
  --os-handle-min-size: 33px;
  // The max size of the scrollbar handle
  --os-handle-max-size: none;
  // The axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
  --os-handle-perpendicular-size: 100%;
  // The :hover axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
  --os-handle-perpendicular-size-hover: 100%;
  // The :active axis-perpedicular size of the scrollbar handle (horizontal: height, vertical: width)
  --os-handle-perpendicular-size-active: 100%;
  // Increases the interactive area of the scrollbar handle.
  --os-handle-interactive-area-offset: 0;
}

Those can be set for both scrollbars at the same time or per scrollbar axis.

The default themes were adapted to use the variables, but to also have a fallback for IE11.

You can now also find a Styling section in the README which documents all css variables, class names and html markup of the scrollbars.

[renatodeleao]

@KingSora Thanks a lot! Works like a charm! 🎉

[sebastienbarre]

This sounds great but the "Styling in depth" documentation is not very clear as to where or how to use these properties. In a CSS file? Before including overlayscrollbars/overlayscrollbars.css? After?
Thanks

[KingSora]

@sebastienbarre I believe it doesn't really mater whether you use the custom css properties before or after including the css file (as long as you include it). If you are using other css properties in conjunction with the custom css properties I would place the styles after the css file because otherwise they might not overwrite defaults.

The workflow is like this:

1. Think about your theme and how it should look
2. Create a class selector with the name of your theme like described in "styling in depth". Here I'm using os-theme-custom:

// horizontal and vertical scrollbar are 10px 
.os-theme-custom {
  --os-size: 10px;
}

// horizontal scrollbar is 10px
.os-theme-custom.os-scrollbar-horizontal {
  --os-size: 10px;
}
// vertical scrollbar is 20px
.os-theme-custom.os-scrollbar-vertical {
  --os-size: 20px;
}

3. Use the theme by initializing OverlayScrollbars with you chosen class name:

OverlayScrollbars(document.body, {
  scrollbars: {
    theme: 'os-theme-custom'
  }
});