search

KingSora / OverlayScrollbars

A javascript scrollbar plugin that hides the native scrollbars, provides custom styleable overlay scrollbars, and preserves the native functionality and feel.
https://kingsora.github.io/OverlayScrollbars
MIT License
3.78k stars 214 forks source link

Is there an upgrade or troubleshooting guide? I had problems with display: block and align-items: center when upgrading v1 to v2 #579

Closed joeuhren closed 10 months ago

joeuhren commented 10 months ago

Hi, and thank you for the excellent scrollbar plugin that is OverlayScrollbars!

I'm writing to share with you that I recently had what I consider to be an unnecessarily difficult time upgrading from v1.13.3 to v2.3.2. Normally when upgrading these types of scripts it is common to have breaking changes which are usually well documented to prevent the types of pitfalls I fell into. I guess first of all, is there an upgrade guide of any kind to assist with moving from v1.x to v2.x? I couldn't find one. If there is one, I would strongly recommend putting that somewhere visible in the README and/or the documentation which already seems to cover all possible topics EXCEPT how to seamlessly upgrade.

Long story short, I discovered 2 separate css rules in my code that worked fine with v1 but broke v2. I had to strip down my code piece-by-piece to figure out what was wrong and in the end I got it down to such a basic level that I was able to easily put together some jsfiddles to demonstrate the issues which I hope will be helpful to others:

v1 test - WORKING v2 test - NOT WORKING

Both of the samples above use identical code except that the OverlayScrollbars scripts and definitions were swapped out for different versions + I added some text details in the html page about what I found to be wrong.

The 2 issues I stumbled upon were:

  1. The scrollbar no longer appears when I used display: block on the main scrollbar element
  2. The scrollbar also does not appear when I had align-items: center on the main scrollbar element

I didn't do exhaustive testing to see if there were other css rules that were conflicting with these, but I wanted to point this out so that hopefully you can add them to an upgrade guide or maybe even some kind of Troubleshooting section of the documentation or README since these same issues could happen to someone who is starting directly with v2.x.

Feel free to close this issue as I got it working in the end. I only wanted to report what I had found in hopes that this info can be made more easily available since it can be overwhelmingly difficult to solve these types of problems in a mature project without knowing exactly what is wrong. Having a troubleshooting section or some kind of Common Problems section in the README or docs would be so helpful so that others can more quickly solve their own problems by checking for these types of incompatible css rules in their own projects.

KingSora commented 10 months ago

@joeuhren Good day :)

I'm sorry you had this experience when upgrading OverlayScrollbars.. It was not supposed to be this way. There is no upgrade guide, but in the changelog are listed all the changes from v1 to v2: https://github.com/KingSora/OverlayScrollbars/blob/master/packages/overlayscrollbars/CHANGELOG.md#200

Funny enough the problem you had is not explicitly listed or explained in the changelog or anywhere else.. Thats because I somehow didn't think that this detail is so important since I personally try to avoid !important rules and didn't think about anyone overwriting the styles of the plugin.

Thanks for posting your solution!