From 0bf6108fc294610e642d4e45842f03e81e96d93f Mon Sep 17 00:00:00 2001 From: Julien Marcou Date: Sat, 10 Jul 2021 21:17:51 +0200 Subject: [PATCH] Improve README --- README.md | 304 +++++++++++++++++++++++++++++------------------------- 1 file changed, 164 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 4385d04..2cb4c5d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ![No Dependency](https://img.shields.io/badge/dependencies-none-%23872a84) ![MIT License](https://img.shields.io/npm/l/scrollable-component) -Scrollable Component is a custom element (Web Component) made to handle native scrolling with a custom scrollbar, which means it is not trying to mimic or override the viewport's native scrolling, but instead, uses the viewport's native scrolling to mimic a custom scrollbar +Scrollable Component is a custom element (Web Component) made to handle native scrolling with a custom scrollbar, which means it is not trying to mimic or override the viewport's native scrolling, but instead, uses the viewport's native scrolling to mimic a custom scrollbar. ```html @@ -17,9 +17,9 @@ Scrollable Component is a custom element (Web Component) made to handle native s ## Demo -You can check out some examples [here](https://scrollable.julien-marcou.fr/) +You can check out some examples [here](https://scrollable.julien-marcou.fr/). -And here is a screenshot of a native scrollbar (on Windows 10) vs the default scrollbar provided by Scrollable Component +And here is a screenshot of a native scrollbar (on Windows 10) vs the default scrollbar provided by Scrollable Component : ![Native vs Custom scrollbar](https://github.com/Julien-Marcou/scrollable-component-demo/raw/main/native-vs-custom.png) @@ -31,92 +31,82 @@ npm install scrollable-component ``` -## Import +## Usage + +This NPM package uses the ECMAScript Modules system, so the easiest way to use it, is with a Bundler (like WebPack), so you don't have to worry about how to make it available and import it. -### TypeScript +### With a Bundler -As it is a self-defined custom element, you must import it in your main entry file so it's available everywhere +As it is a self-defined custom element, you must import it only once in your main entry file so it's available everywhere : ```javascript import 'scrollable-component'; ``` -In addition to the previous import, if you want to extend or use the typing of the `ScrollableComponentElement`, you can import it where you need it +In addition to the previous import, if you are using TypeScript, and want the typing of the `ScrollableComponentElement`, you can import it where you need it : -```javascript +```typescript import { ScrollableComponentElement } from 'scrollable-component'; ``` -### JavaScript +### Without a Bundler + +If you are not using a bundler, you'll have to expose the `scrollable-component/index.js` file so it is accessible from the web, and import it in your HTML using a `module` script. -If you are not using Webpack, you can directly import it in your HTML using a `module` script +#### Using the full path ```html - -``` + -Or import it in your JavaScript + -```javascript -import 'path-to-scrollable-component-vendor/index.js'; + ``` +#### Using Import Maps -## Usage +[Import Maps](https://wicg.github.io/import-maps/) can be very useful when you have several dependencies between different modules, as it allows you to import modules using their names instead of their full path. -The `ScrollableComponentElement` will automatically add custom scrollbars if the content overflows the height/width of the viewport, so you just have to constrain its size (using height, max-height, or whatever you want) +But they are not implemented in any browser yet, so you'll have to use a polyfill : ```html - - - - - + } + + ``` -## Why use Scrollable Component ? +## Documentation -### Perks - -Simple, performant, modern, it probably outpasses a lot of old custom scrollbar packages - -- It's built for raw performance by using modern features from browsers, which also allow for better customization & cleaner code -- It does not override the viewport's native behaviors (Mouse Wheel scrolling, Swipe scrolling, Page Down/Up keys, Arrow keys, Middle Mouse Button's auto-scrolling, Scroll snapping, JavaScript API...) -- It uses the [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) specs, making it act like a black box from the outside (encapsulating HTML, CSS & JS) and leaving the DOM untouched, without extraneous `
` -- It's simple to use (you just need to add the `` tag around the content you want the custom scrollbars on) -- It's easy to customize (it uses CSS variables, like `--scrollbar-width: 16px;`) +The `ScrollableComponentElement` will automatically add custom scrollbars if the content overflows the height/width of the viewport, so you just have to constrain its size (using height, max-height, or whatever you want) : -### Quirks - -This package is not intended to replace all the scrollbars of your website, especially not the body's one. Tampering with native behaviors is always at risk, especially for the Web Accessibility - -It's recommended to only use it sparingly, on small parts of your website (like modal boxes, chats, sidebars, dropdowns...) to enhance the user's experience through a cleaner UI - -- It only works on modern browsers -- It will never be as fast as native scrollbars -- It sacrifices some native functionalities (like Google Chrome's search result highlights in the scrollbar) -- The custom scrollbars are absolutely positioned above the native viewport, which means scrolling when the pointer directly interacts with them instead of the viewport, is in fact, handled with some JavaScript and not natively - - -## Browser compatibility - -Firefox, Chromium-based browsers (Chrome, Edge, Opera, ...) & WebKit-based browsers (Safari, ...) - - -## Customization +```html + -![Native vs Custom scrollbar](https://raw.githubusercontent.com/Julien-Marcou/scrollable-component-demo/main/customization.png) + + + +``` By default, the scrollbar only appears when hovering the viewport, but you can force the scrollbar to always be visible by setting the `scrollbar-visibility` attribute to `always` ```html - + ``` @@ -124,7 +114,7 @@ You can put the vertical scrollbar on the left of the viewport by setting the `v ```html - + ``` @@ -132,7 +122,7 @@ You can put the horizontal scrollbar on the top of the viewport by setting the ` ```html - + ``` @@ -141,84 +131,22 @@ By default, the viewport's content will overflow in both directions, if you have ```css /* No horizontal scrolling */ scrollable-component { - --viewport-overflow-x: hidden; + --viewport-overflow-x: hidden; } /* No vertical scrolling */ scrollable-component { - --viewport-overflow-y: hidden; + --viewport-overflow-y: hidden; } ``` -You can also change the transitions, the scrolling behaviors and the look of the scrollbars using CSS properties - -Here is the list of all the default CSS properties you can override - -```css -scrollable-component { - /* Transitions */ - --fade-in-transition-duration: 150ms; - --fade-out-transition-duration: 800ms; - --fade-out-transition-delay: 300ms; - --fill-color-transition-duration: 150ms; - - /* Overflow behaviors */ - --viewport-overflow-x: auto; - --viewport-overflow-y: auto; - - /* Scrolling behaviors */ - --viewport-scroll-snap-type: none; - --viewport-scroll-behavior: auto; - --viewport-overscroll-behavior: auto; - - /* Scrollbar look */ - --scrollbar-width: 16px; - --scrollbar-padding: 2px; - --scrollbar-fill-color: transparent; - --scrollbar-fill-color-hover: transparent; - --scrollbar-border: 0 none; - --scrollbar-border-radius: 0; - --scrollbar-box-shadow: none; - --vertical-scrollbar-background: none; - --vertical-scrollbar-background-size: auto; - --horizontal-scrollbar-background: none; - --horizontal-scrollbar-background-size: auto; - - /* Scrollbar's track look */ - --scrollbar-track-fill-color: transparent; - --scrollbar-track-fill-color-hover: transparent; - --scrollbar-track-border: 0 none; - --scrollbar-track-border-radius: 0; - --scrollbar-track-box-shadow: none; - --vertical-scrollbar-track-background: none; - --vertical-scrollbar-track-background-size: auto; - --horizontal-scrollbar-track-background: none; - --horizontal-scrollbar-track-background-size: auto; - - /* Scrollbar's thumb look */ - --scrollbar-thumb-fill-color: #ccc; - --scrollbar-thumb-fill-color-hover: #aaa; - --scrollbar-thumb-border: 0 none; - --scrollbar-thumb-border-radius: var(--scrollbar-width); - --scrollbar-thumb-box-shadow: none; - --vertical-scrollbar-thumb-background: none; - --vertical-scrollbar-thumb-background-size: auto; - --horizontal-scrollbar-thumb-background: none; - --horizontal-scrollbar-thumb-background-size: auto; - - /* Content padding */ - /* (You probably want to use this instead of setting the padding directly on the scrollable-component) */ - --content-padding: 0; -} -``` - -If you need to access the native viewport of the scrollable-component +If can access the native viewport of a scrollable-component like this : ```javascript const scrollableComponent = document.querySelector('scrollable-component'); scrollableComponent.viewport.addEventListener('scroll', (event) => { - // Your code + // Your code }); ``` @@ -226,30 +154,126 @@ Each scrollable-component is defining its own `--viewport-width` & `--viewport-h ```html -
-
Slide 1
-
Slide 2
-
Slide 3
-
Slide 4
-
Slide 5
-
Slide 6
-
+
+
Slide 1
+
Slide 2
+
Slide 3
+
Slide 4
+
Slide 5
+
Slide 6
+
``` +## Customization + +You can change the transitions, the scrolling behaviors and the look of the scrollbars using CSS properties. + +![Native vs Custom scrollbar](https://raw.githubusercontent.com/Julien-Marcou/scrollable-component-demo/main/customization.png) + +Here is the list of all the default CSS properties you can override : + +```css +scrollable-component { + /* Transitions */ + --fade-in-transition-duration: 150ms; + --fade-out-transition-duration: 800ms; + --fade-out-transition-delay: 300ms; + --fill-color-transition-duration: 150ms; + + /* Overflow behaviors */ + --viewport-overflow-x: auto; + --viewport-overflow-y: auto; + + /* Scrolling behaviors */ + --viewport-scroll-snap-type: none; + --viewport-scroll-behavior: auto; + --viewport-overscroll-behavior: auto; + + /* Scrollbar look */ + --scrollbar-width: 16px; + --scrollbar-padding: 2px; + --scrollbar-fill-color: transparent; + --scrollbar-fill-color-hover: transparent; + --scrollbar-border: 0 none; + --scrollbar-border-radius: 0; + --scrollbar-box-shadow: none; + --vertical-scrollbar-background: none; + --vertical-scrollbar-background-size: auto; + --horizontal-scrollbar-background: none; + --horizontal-scrollbar-background-size: auto; + + /* Scrollbar's track look */ + --scrollbar-track-fill-color: transparent; + --scrollbar-track-fill-color-hover: transparent; + --scrollbar-track-border: 0 none; + --scrollbar-track-border-radius: 0; + --scrollbar-track-box-shadow: none; + --vertical-scrollbar-track-background: none; + --vertical-scrollbar-track-background-size: auto; + --horizontal-scrollbar-track-background: none; + --horizontal-scrollbar-track-background-size: auto; + + /* Scrollbar's thumb look */ + --scrollbar-thumb-fill-color: #ccc; + --scrollbar-thumb-fill-color-hover: #aaa; + --scrollbar-thumb-border: 0 none; + --scrollbar-thumb-border-radius: var(--scrollbar-width); + --scrollbar-thumb-box-shadow: none; + --vertical-scrollbar-thumb-background: none; + --vertical-scrollbar-thumb-background-size: auto; + --horizontal-scrollbar-thumb-background: none; + --horizontal-scrollbar-thumb-background-size: auto; + + /* Content padding */ + /* (You probably want to use this instead of setting the padding directly on the scrollable-component) */ + --content-padding: 0; +} +``` + + +## Browser compatibility + +Firefox, Chromium-based browsers (Chrome, Edge, Opera, ...) & WebKit-based browsers (Safari, ...) + + +## Why use Scrollable Component ? + +### Perks + +Simple, performant, modern, it probably outpasses a lot of old custom scrollbar packages + +- It's built for raw performance by using modern features from browsers, which also allow for better customization & cleaner code +- It does not override the viewport's native behaviors (Mouse Wheel scrolling, Swipe scrolling, Page Down/Up keys, Arrow keys, Middle Mouse Button's auto-scrolling, Scroll snapping, JavaScript API...) +- It uses the [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) specs, making it act like a black box from the outside (encapsulating HTML, CSS & JS) and leaving the DOM untouched, without extraneous `
` +- It's simple to use (you just need to add the `` tag around the content you want the custom scrollbars on) +- It's easy to customize (it uses CSS variables, like `--scrollbar-width: 16px;`) + +### Quirks + +This package is not intended to replace all the scrollbars of your website, especially not the body's one. Tampering with native behaviors is always at risk, especially for the Web Accessibility + +It's recommended to only use it sparingly, on small parts of your website (like modal boxes, chats, sidebars, dropdowns...) to enhance the user's experience through a cleaner UI + +- It only works on modern browsers +- It will never be as fast as native scrollbars +- It sacrifices some native functionalities (like Google Chrome's search result highlights in the scrollbar) +- The custom scrollbars are absolutely positioned above the native viewport, which means scrolling when the pointer directly interacts with them instead of the viewport, is in fact, handled with some JavaScript and not natively + + ## How it works Scrollable Component uses the [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) specs to create a custom element which handles all the work for you and which can even be extended