diff --git a/docs/caveats.md b/docs/caveats.md index 43818e88..55f91aa8 100644 --- a/docs/caveats.md +++ b/docs/caveats.md @@ -1,19 +1,19 @@ # Caveats -Customizing scrollbars is always a controversial issue. On the one hand, it provides full control of scrollbars. But on the other hand, it degrades user experience because native behavior is unmatchable. As the author of this script, I don't really want you to use it unless you are sure about what you are doing. +Emulating scrollbars with JavaScript is always a controversial issue. On the one hand, it provides complete control of scrollbars. On the other hand, however, it degrades user experience because native behavior is unmatchable. As the author of this plugin, I don't really want you to use it unless you are sure about what you are doing. -If you just want to customize your scrollbars, you can try out something like [SimpleBar](https://github.com/Grsmto/simplebar) which follows native scrolling. +If you just want to customize your scrollbars, you can try something like [OverlayScrollbars](https://github.com/KingSora/OverlayScrollbars) which follows the native scrolling. -## Native behavior is unmatchable +## Native Behavior is Unmatchable -Although this script trys to make scrolling experience as smooth as the native one, it still behaves weirdly especially the inertial scrolling. You may upset your users who are using a trackpad or mobile device with touch screen. +Although this plugin tries to emulate the scrolling experience as close to the native one as possible, it still behaves weirdly especially with trackpads or touch screens, as the scrolling delta will be interpolated/smoothened twice: by the native inputs and by this plugin. Keep in mind that **native scrollbars are always the best ones**. -## Performance issues +## Performance Issues -This script is using `translate3d` to perform smooth scrolling. However, the larger the scrollable area is, the lower the performace will be. And scrolling may also be jittery on some old devices. +Back in the days that this plugin was created, [the native scrolling was quite slow](https://www.html5rocks.com/en/tutorials/speed/scrolling/) notably on touch devices. Therefore, I wrote this plugin using `translate3d` to improve scrolling performance. Now that modern browsers have done a lot improving native scrolling performance, I don't think you will need this one anymore. What's more, as the scrollable area grows, this plugin will consume a large amount of GPU resources, resulting in low performance. Also, scrolling may be jittery on some old devices that cannot render 3D transformations well. ## Incompatible with Pointer Event API -This script is calling `event.preventDefault()` on `touchmove` events to prevent native scrolling. But that breaks pointer event streams and result in some [unexpected consequence](https://github.com/idiotWu/smooth-scrollbar/issues/111). +This plugin is calling `event.preventDefault()` on `touchmove` events to prevent native scrolling. However, this breaks pointer event streams and gives some [unexpected consequences](https://github.com/idiotWu/smooth-scrollbar/issues/111#issuecomment-339243256).